AGENTS.md

1# src/hooks/todo-continuation-enforcer/ (Boulder Continuation Mechanism)
2 
3**Generated:** 2026-07-17 (7d664b96b)
4 
5## OVERVIEW
6 
717 source files (~1690 LOC). The "boulder" Continuation Tier hook: forces Sisyphus to keep rolling when incomplete todos remain. Fires on `session.idle`, injects a continuation prompt after a 2s countdown toast.
8 
9## HOW IT WORKS
10 
11```
12session.idle
13  → Is main session (not prometheus/compaction/plan)? (DEFAULT_SKIP_AGENTS)
14  → No abort detected recently? (ABORT_WINDOW_MS = 3s)
15  → Todos still incomplete? (todo.ts)
16  → No background tasks running?
17  → Cooldown passed? (CONTINUATION_COOLDOWN_MS = 5s, exponential backoff)
18  → Failure count < max? (MAX_CONSECUTIVE_FAILURES = 5)
19  → Not paused at turn boundary? (continuationBlockReason)
20  → Start 2s countdown toast → inject CONTINUATION_PROMPT
21```
22 
23## TURN-BOUNDARY PAUSE
24 
25After injecting `CONTINUATION_PROMPT` the hook watches the next turn before
26rearming. `awaitingPostInjectionProgressCheck` is set on injection; assistant
27activity (`message.updated` / `message.part.updated` / `message.part.delta` with
28role=assistant, or `tool.execute.before/after`) marks `continuationResponseObserved`.
29 
30On the next `session.idle`, `trackContinuationProgress` resolves the pause:
31 
32- No progress + `continuationResponseObserved` set: `continuationBlockReason = "directive-response"`. The assistant answered without advancing todos, so rearming stops.
33- Genuine user message inside the accepted-continuation window: `continuationBlockReason = "user-interruption"`. Synthetic/internal split messages (continuation echo, system directives) are filtered out. When the user `message.updated` event lacks parts, classification is deferred to `message.part.updated` by stashing `pendingUserMessageID`.
34 
35While `continuationBlockReason` is set, `handleSessionIdle` and `continuation-injection.ts` skip. It is cleared on real todo progress, abort, or a fresh injection.
36 
37## KEY FILES
38 
39| File | Purpose |
40|------|---------|
41| `handler.ts` | `createTodoContinuationHandler()`: event router. Handles `session.error` (abort + token-limit detection) and `session.compacted`; delegates `session.idle` and the message lifecycle to idle/non-idle handlers |
42| `idle-event.ts` | `handleSessionIdle()`: main decision gate for `session.idle` |
43| `non-idle-events.ts` | `handleNonIdleEvent()`: `message.updated` / `message.part.updated` / `message.part.delta` and `tool.execute` handlers; classifies user interruptions vs assistant turns for the turn-boundary pause |
44| `session-state.ts` | `SessionStateStore`: per-session failure/abort/cooldown/progress state |
45| `todo.ts` | Check todo completion status via session store |
46| `countdown.ts` | 2s countdown toast before injection |
47| `abort-detection.ts` | Detect MessageAbortedError / AbortError |
48| `continuation-injection.ts` | Build + inject CONTINUATION_PROMPT into session |
49| `message-directory.ts` | Temp dir for message injection exchange |
50| `constants.ts` | Timing constants, CONTINUATION_PROMPT, skip agents |
51| `types.ts` | `SessionState`, handler argument types |
52 
53## CONSTANTS
54 
55```typescript
56DEFAULT_SKIP_AGENTS = ["prometheus", "compaction", "plan"]
57CONTINUATION_COOLDOWN_MS = 5_000      // 5s base, exponential backoff per failure
58MAX_CONSECUTIVE_FAILURES = 5          // Then 5min pause (exponential backoff)
59FAILURE_RESET_WINDOW_MS = 5 * 60_000  // 5min window for failure reset
60COUNTDOWN_SECONDS = 2
61ABORT_WINDOW_MS = 3000                // Grace after abort signal
62```
63 
64## STATE PER SESSION
65 
66```typescript
67interface SessionState {
68  stagnationCount: number                       // Turns without todo progress
69  consecutiveFailures: number                   // Resets after FAILURE_RESET_WINDOW_MS
70  lastInjectedAt?: number                       // Cooldown base (exponential backoff)
71  abortDetectedAt?: number                      // Cleared after ABORT_WINDOW_MS
72  wasCancelled?: boolean                        // Abort/cancel flag
73  tokenLimitDetected?: boolean                  // Skip retry on context overflow
74  awaitingPostInjectionProgressCheck?: boolean  // Injected, awaiting next turn
75  continuationResponseObserved?: boolean       // Assistant replied to injection
76  continuationBlockReason?: "directive-response" | "user-interruption"
77  pendingUserMessageID?: string                // Deferred user msg pending part classification
78  countdownStartedAt?: number
79  inFlight?: boolean                           // Injection in progress
80  allTodosCompletedAt?: number
81}
82```
83 
84## RELATIONSHIP TO ATLAS
85 
86`todoContinuationEnforcer` handles **main Sisyphus sessions** only.
87`atlasHook` handles **boulder/ralph/subagent sessions** with a different decision gate.
88Both fire on `session.idle` but check session type first.
89