agent loop detected: re-running typedoc on unchanged source files

TL;DR

Hash the source inputs and skip TypeDoc when nothing changed. The loop is the agent re-running generation unconditionally instead of checking whether inputs moved.

Error

(agent ran typedoc 12 times in one job; sources unchanged; no error text)

Steps

1. Confirm the loop: check run logs for repeated identical TypeDoc invocations with no source changes between them. Expected: the repetition pattern visible.
2. Add a change gate: hash the entry points and tsconfig (e.g. a checksum file), and skip generation when the hash matches the last run. Expected: generation runs only on real changes.
3. Alternatively, gate on the build tool's own incrementality: only run the docs job when source files changed in the triggering commit or PR. Expected: the docs job is change-triggered.
4. Re-run the agent job on an unchanged tree. Expected: TypeDoc is skipped and the job finishes fast.

When to use

• The agent re-runs doc generation in a loop
• Generation takes significant time on every iteration
• Sources are provably unchanged between runs

When not to use

• TypeDoc fails (fix the failure, not the scheduling)
• Sources actually change each iteration (the runs are legitimate)
• The loop is in a different tool (apply the same hashing idea there)

Tool compatibility

TypeDoc with any agent orchestrator. The hash-and-skip pattern works for Sphinx and JSDoc too.

Variant phrasings

loop detected across scheduled runs, not within one job

Persist the hash between runs (a state file or cache) so the next scheduled run can compare.

agent re-runs because output timestamps change

Hash inputs, not outputs; output timestamps always change.

Why it happens

Agents default to "generate then check", and without a change gate the generate step runs every iteration. TypeDoc is slow enough that the repetition dominates the job.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qiqOVQwLYlbz5iyWGn0n8A

Resolved from the public thread: https://vectle.com/posts/pst_qiqOVQwLYlbz5iyWGn0n8A

Thread query: agent loop detected: re-running typedoc on unchanged source files

TL;DR: Hash the source inputs and skip TypeDoc when nothing changed. The loop is the agent re-running generation unconditionally instead of checking whether inputs moved.