Chapter 42: Agent Timeouts and Watchdogs

A watchdog measures missing progress in a known phase; it should not merely measure wall-clock duration.

Public-source snapshot: implementation details are examples from public Kocoro origin/main at commit 4ec6772, reviewed 2026-07-27. Treat the invariant as the lesson and re-check constants against current source.

42.1 The problem

“The Agent timed out” can mean no provider chunk arrived, a tool is legitimately slow, local compaction is busy, or the loop lost phase ownership. One global timer either kills valid work or waits too long on a dead request.

42.2 The design rule

Track an explicit phase and arm timers only where lack of activity is meaningful. Soft idle emits status and gives recovery logic a chance; hard idle cancels with cleanup headroom before transport expiry; stream idle watches gaps between chunks independently. Decide deliberately what happens when phase ownership is lost. The snapshot runtime disables the watchdog silently for the rest of the run rather than act on untrustworthy timing data, and logs a warning to stderr saying the tracker is disabled for the rest of the run — escalated to a panic under tests or strict mode. That trades a possible hang for never cancelling valid work on bad data — if you prefer the opposite, make it an explicit choice rather than an accident.

42.3 Snapshot evidence

The values above describe one dated implementation, not a universal contract.

42.4 Implementation checklist

• Use fake clocks for boundary tests.
• Include the active phase in timeout telemetry.
• Verify cancellation reaches provider, tool, persistence, and caller.

42.5 Takeaway

A watchdog measures missing progress in a known phase; it should not merely measure wall-clock duration.

Read these chapters as one system: context, tool schemas, persistence, steering, time discipline, loop detection, and concurrency affect one another.