file-chat: Claude agents never woken — PTY idle heuristic starved by continuous TUI repaint

[realproject7]

EPIC Context

• Parent: none — standalone
• Epic goal: Restore reliable file-chat wake delivery without regressing active-turn safety.
• This ticket's role: Repair Claude-specific PTY repaint starvation with a bounded, safe deferred-wake path.
• Depends on: none Enables: reliable Claude file-chat operation under continuous TUI repaint
• Contracts to respect/expose: Deferred wakes must never barge into an active Codex or Gemini turn; timer/listener state is per session key and must be fully disposed on every terminal path.
• Out of scope here (later tickets): A genuine turn-activity detector replaces raw PTY-byte heuristics later — do not implement it here.

Summary

In file-chat mode, Claude Code agents can never receive PTY wake injections when their idle TUI repaints continuously. The current wake-delivery heuristic treats any output in the last 5 seconds as busy, and the deferred-wake drain resets its only timer on every PTY chunk. A ~200 ms repaint loop therefore prevents the required 5-second quiet gap indefinitely.

The root cause is confirmed in server/pty-dispatcher.js: isAgentBusy() is based on raw output age, and both defer paths enter the same queuePendingWake() drain. A hard deadline is appropriate only for the backend with verified repaint starvation, and only with the safety contract below.

Scope

1. Add a bounded deferred-wake deadline for Claude sessions only. Extend the session/spawn contract with explicit backend identity (or an equally explicit, tested dependency) so Codex and Gemini preserve their current genuine-quiescence-only behavior.
2. The Claude cap must not preempt the deliberate active-send suppression window. If the cap can be armed from the recentlySent path, either choose a cap at least ACTIVE_SUPPRESSION_MS or re-arm once for the remaining suppression duration; implement and test the selected rule.
3. Keep idle-gap delivery as the preferred path. The cap is solely a starvation escape hatch for continuous Claude repaint output.
4. Treat both timer handles and the onData listener as one per-key lifecycle. Clear the idle timer, hard-cap timer, and listener on idle drain, cap drain, replacement/cleanup, and session exit. A timer from one deferred-wake cycle must never consume or dispose a later cycle.
5. At cap-fire time, re-resolve the session by key and require a running session with a live term before injection.
6. Define repeated-mention behavior after a cap delivery: add a per-key cooldown that defers a pending wake rather than dropping it, preventing repeated cap injections during one long turn and avoiding loop-guard amplification.\n7. Give the delayed submit (\\r) timer created by injection an explicit owner and cleanup behavior so stopping a session during its delay cannot write to a dead term.\n8. Correct the stale queuePendingWake() comment that describes an unimplemented since_id high-water mark.

Deterministic test contract

Make the cap duration injectable/overridable by the dispatcher test harness so regression tests run at millisecond scale. Extend the PTY stub tests to invoke captured onData callbacks; a test that does not drive those callbacks does not cover the bug.

Required cases:

• A sub-threshold repeating Claude repaint invokes onData and still delivers one wake at the cap; this test fails before the fix.
• Codex and Gemini do not receive cap-driven injection during a continuously streaming active turn.
• A cap armed from the recent-send path obeys the selected active-suppression rule.
• Repeated deferred mentions yield exactly one injection per permitted cooldown window, with the next pending wake deferred rather than discarded.
• After idle drain, cap drain, and cleanupSession, no pending wake, listener, hard-cap/idle handle, or delayed-submit handle remains; a stale callback cannot affect a subsequent cycle.
• A cap firing after the session is no longer running (or lacks a term) performs no write.

Acceptance Criteria

• Claude agents under continuous sub-threshold TUI repaint receive a queued wake within the configured bounded latency.
• Codex and Gemini retain genuine-idleness-only wake behavior; no cap-driven text is injected into their active streaming turns.
• The active-send suppression contract remains intact for every path that can arm a cap.
• Idle and cap delivery are exactly-once per pending cycle, with no stale timer/listener cross-cycle behavior.
• Repeated mentions cannot create a wake storm or trigger loop-guard pause through cap-driven injection.
• Deterministic tests cover the six cases above, including a regression that fails on the pre-fix implementation.
• The existing full test suite and production build pass.

Non-Goals

• Do not replace raw-output busy detection with a full turn-state detector in this ticket.
• Do not change direct wake, non-file-chat behavior, or unrelated backend launch configuration.

[realproject7]

@re2 ticket review — REQUEST CHANGES (spec revision needed before implementation)

Reviewed at baseline main @ caf94e2. Root cause is confirmed and the hard-cap direction is right, but the proposal as written cannot go to implementation: it weakens the #736 mid-turn invariant for backends that don't have this bug, and it under-specifies cleanup + tests.

Confirmed (the diagnosis is correct)

• isAgentBusy() — server/pty-dispatcher.js:72-74 — busy = any PTY byte within IDLE_THRESHOLD_MS (5000, :7). A 200 ms repaint holds this permanently true.
• The drain's idle timer is reset on every onData — :103-113 — so the 5 s gap never arrives. Starvation confirmed.
• Both defer paths funnel into queuePendingWake() — dispatch-time :63-66 and coalesce-fire-time :163-166 — so the starvation blocks both.

Gaps that must be closed

G1 — BLOCKING: the cap preempts ACTIVE_SUPPRESSION_MS and barges in mid-turn on non-Claude backends.
MAX_DEFER_MS = 10000 < ACTIVE_SUPPRESSION_MS = 30000 (:9). queuePendingWake is reached from the recentlySent branch (:61-66, :161-166), which exists precisely because the agent is likely still mid-turn. Today the drain requires a real 5 s output gap — a genuine idleness signal. A cap that onData cannot postpone fires while output is actively streaming, which is exactly the mid-activity barge-in #736 forbids and #923 was careful to preserve.

The ticket's safety argument — "Claude queues input received mid-turn" — is Claude-specific. This dispatcher is backend-agnostic: Codex and Gemini sessions take the identical path, carry no such queueing guarantee, and are not affected by this bug at all. As written the fix imposes a new mid-turn injection risk on the two backends that currently work.

Please pick one and write it into scope:

• (preferred) scope the cap to the affected backend only, leaving Codex/Gemini behavior bit-for-bit unchanged; note that this requires a scope addition — the session object (server/index.js:648-662) carries no command/backend field today, so one must be added at spawn. Better to state that up front than have it discovered mid-PR.
• or set MAX_DEFER_MS >= ACTIVE_SUPPRESSION_MS so the cap can never preempt a deliberate suppression window.

G2 — BLOCKING: cleanupDrainListener() must clear hardCapHandle, and the ticket's own snippet doesn't reach it.
The proposal stores the handle on state but cleanupDrainListener only reads state.timeoutHandle (:124-126). If the idle timer wins the race, a stale hard-cap timer survives cleanup. That is not a benign no-op: drainFn (:84-97) checks only _pendingWake.get(key), so a subsequent wake queued for the same key gets consumed early by the stale timer, which then disposes the new listener. Cross-talk between wake cycles. Require an explicit assertion that both handles and the _drainListeners entry are gone after every drain path.

G3 — SHOULD: no duplicate-wake floor.
queuePendingWake early-returns on _drainListeners.has(key) (:99), so one listener per key — but a cap-driven drain removes the listener, so the next mention re-arms a fresh cap and injects again ~10 s later, repeatedly, while the agent is still mid-turn under continuous repaint. Unlike the direct path, the deferred path has no coalescing. Add a per-key minimum interval between cap-driven injections (or route the deferred path through the existing coalesce window).

G4 — SHOULD: the drain has no liveness re-check.
drainFn injects into the session.term captured at queue time (:96) with no session.state === "running" / non-null term guard. Currently unreachable — both teardown paths call cleanupPtyDispatcher first (server/index.js:735 markSessionExited, :778 stopAgentSession) — but the entire point of this change is a timer onData can't postpone, which makes that guard load-bearing the moment G2 is fixed imperfectly. It's two lines; add it.

G5 — BLOCKING on "deterministic tests": the ticket specifies none, and the existing suite can't express this one cheaply.
server/pty-dispatcher.test.js is a hand-rolled runner (not node:test), driving real timers with real sleeps — await new Promise(r => setTimeout(r, IDLE_THRESHOLD_MS + 100)) in tests 10 and 13. A 10 s cap tested the same way adds ~10 s+ per case to CI. Export MAX_DEFER_MS and make it overridable (e.g. via the deps object) so tests run in milliseconds.

Required cases:

1. 200 ms repaint loop → wake fires by the cap. Must fail before the fix — this is the actual regression test.
2. Output stops → idle drain still fires at IDLE_THRESHOLD_MS (no regression to tests 10/13).
3. Exactly one injection when both timers would otherwise fire.
4. cleanupSession clears the cap → no injection after stop (extend test 9).
5. _drainListeners empty after drain — no listener leak.

Non-blocking

Agree the esc to interrupt turn-state detector is out of scope, but please open it as a follow-up rather than leaving it as prose: the cap leaves genuinely long-running agents receiving wake prompts stacked mid-turn, which is a real (if lesser) cost of shipping the heuristic.

Checked (evidence)

• server/pty-dispatcher.js:7,9,63-66,72-74,84-97,99,103-116,118-128,161-166,187-196
• server/pty-dispatcher.test.js:29-50,166-232,234-241 (real-timer runner, existing drain coverage)
• server/index.js:648-662 (session shape — no backend field), :735, :778 (cleanup wiring)

[realproject7]

@re2 addendum — escalating one gap to BLOCKING

Following @dev's independent ticket review, I re-verified two claims at caf94e2 that change my earlier severities. My overall verdict is unchanged (REQUEST CHANGES — spec revision before implementation); one item moves from SHOULD to BLOCKING and one is strengthened.

G3 (duplicate wakes) → BLOCKING: a wake storm can trip the loop guard and stop all delivery

I originally filed this as a should-fix efficiency concern. Verified, it is a correctness concern of the same class the ticket is trying to fix:

• A cap-driven drain removes the listener, so each new mention during one long turn arms a fresh cycle → an injection roughly every MAX_DEFER_MS. The deferred path has no coalescing (only the direct path does, pty-dispatcher.js:142-173).
• Each injection costs the agent a turn, and a turn typically ends in a chat post — an agent-to-agent message.
• checkLoopGuard() (server/file-chat.js:247-280) pauses the project at maxHops = 30 agent-to-agent messages with no human reply, and only a human /continue clears it.
• dispatchToAgentPTY() returns early on isLoopGuardPaused(projectId) (pty-dispatcher.js:33) — before any wake logic.

So the failure mode is self-defeating: a fix for wake starvation can, under the exact conditions it targets (continuous repaint + a long turn + an active batch), generate enough redundant wakes to pause file-chat and halt wake delivery entirely until an operator intervenes. That is a worse outcome than the bug. A per-key post-injection cooldown that defers without dropping the pending flag is required, not optional.

G5 (tests) — strengthened: the harness structurally cannot see this bug

@dev's finding here is correct and I verified it independently. In server/pty-dispatcher.test.js, onDataCallbacks appears at exactly three places — declared (:31), pushed to by the term.onData stub (:35), returned from makeSessions (:49). There are zero call sites. No test has ever driven a PTY output event.

This is why repaint starvation shipped green: the drain's resetIdleTimer() path (:111-113 in the source) is unreachable from the current suite, so the tests only ever exercise the no-further-output fallback. The test contract in G5 should state this explicitly — the regression test must invoke the captured callbacks on a sub-threshold interval, and it must fail on today's code. A test that merely asserts the cap fires without driving onData reproduces the original blind spot.

Minor corrections to line references

Reading git show caf94e2:server/pty-dispatcher.js, the stale-coalesce re-check is at :163-166, not :170-174 — that range lands on state.timer = timer / _coalesceTimers.set(...), a different construct. Several other refs in circulation run a few lines hot (drainFn is :84-97; cleanupDrainListener is :118-128; the Claude catalog is agentModels.ts:23-41). Worth normalizing before the ticket is amended so the implementer isn't chasing offsets.

Two nits, non-blocking

• injectIntoTerm schedules the submitting \r on an untracked setTimeout (:179-181) that cleanupSession never clears. It's try/catch-wrapped and writes to a captured (possibly killed) term, so it's benign today — but it is the one timer that survives teardown, and this ticket is about timers surviving things they shouldn't.
• The queuePendingWake doc comment claims a "high-water mark (since_id)" (:76-79); the implementation is a plain boolean flag. Stale comment in the exact function being modified.