pi-error-watchdog

Watchdog extension for the Pi coding agent: automatically sends . to continue the session after any error stop — rate limits, "service unavailable", provider API errors, connection failures, 5xx outages.

Long-running agentic sessions often die mid-task on a transient provider error, and nothing resumes them until you notice. This watchdog keeps them going by itself.

Install

pi install npm:pi-error-watchdog

Behavior

• Default ON. No configuration needed after install.
• Unlimited retries. When a run stops with stopReason: "error", the watchdog sends . to continue the session — as many times as it takes, with no cap.
• Never at the start of a conversation. Before the first completed assistant exchange there is nothing to continue — pi's built-in auto-retry (3 attempts, backoff) already ran, and the watchdog stays quiet. The user decides what to resend.
• Natural stops are preserved. Normal model stops, user aborts (Esc), and any other stop reason never trigger a continuation.
• Works with pi's built-in retry. Pi first retries retryable errors itself (3x with exponential backoff). The watchdog only acts once the run has fully settled after all built-in retries are exhausted — so it covers both retryable errors and non-retryable ones like 401s.
• Subagent coverage. Background subagent child sessions (detached runners) load ambient user extensions, so they get the watchdog too. Foreground children run in the parent process and are covered by the parent session's watchdog.
• Print-mode safe. A continuation barrier keeps single-shot pi -p / --mode json invocations alive until the whole recovery sequence finishes — the process never exits mid-recovery.

Toggle

Command	Effect
/watchdog	Report current state
/watchdog on	Arm (default)
/watchdog off	Disarm — error stops are left alone

State persists in ~/.pi/agent/watchdog.json so background runner processes see it. Default is ON when no state file exists.

What counts as an "error stop"

Any assistant message finalized with stopReason: "error" and an error message — provider API errors, rate limits ("overloaded", 429), 5xx ("service unavailable"), network failures ("connection error", EAI_AGAIN, timed out), and provider-returned errors. Aborted runs (stopReason: "aborted" — your Esc) are intentional stops and never trigger a continuation.

How it works

1. agent_end captures the run's last assistant message.
2. agent_settled (fired only after pi's own retry/compaction handling fully drains) checks it: error stop + watchdog armed + a completed exchange exists + session idle → send . via pi.sendMessage({ triggerTurn: true }), which starts the next run synchronously.
3. The continuation barrier keeps the settled dispatch open until the continuation run settles; a further error chains another . — unlimited.
4. Every continuation ends in a normal stop, an abort, or /watchdog off.

Development

npm install
npx tsc --noEmit --strict --module nodenext --moduleResolution nodenext --target esnext --skipLibCheck src/index.ts

Functional tests use a flaky-test provider extension (test/flaky-provider.ts) that fails N times with a configurable error, then succeeds. See test/run-test.ps1 for the full battery: watchdog OFF (exit 1, no continuation), ON (recovery), start-of-conversation guard, chained continuations, and toggle round-trip.

License

MIT