fix(sessions): the gate is the universal turn heartbeat (v0.326.0)

[vikasprogrammer]

Reported: a session actively doing work shows ready.

Yes — because it was launched before the lifecycle hook shipped. But it's a real hole either way: #593 made isWorking self-heal against a stale flag, and left the opposite direction with no backstop at all — nothing could set the flag back.

Hook settings are written into the agent folder at launch, so a session launched before UserPromptSubmit was wired never fires it. Once its busy_since was cleared it could never regain it.

Confirmed on the reported session ses_c63f1492dc12ce06:

pane:        ✽ Germinating… (1m 2s · ↓ 2.6k tokens)
gate events: every few seconds
busy_since:  NULL          ← nothing left that could set it
console:     ready

Fix — put the heartbeat on the one hook that cannot be missing

The gate hook is wired into every session that exists; it is the invariant. A tool call is proof a turn is running, so it stamps busy_since too.

Three properties that make it safe:

• answered: false — a tool call is not a human answering, so it never retires a "waiting on you" card. (A session blocked on an approval reads needs you regardless — that outranks working.)
• it re-stamps a flag older than MID_TURN_MAX_MS, turning that ceiling from a dumb timer into an honest activity test: a long turn still calling tools keeps its spinner, a wedged one emits nothing and ages out. Without this arm a real 2h+ turn would silently read ready — the same class of bug in a new place.
• throttled to one write per 30s per session (in-memory, dropped by clearTurnBusy so the first tool call of the next turn is never swallowed). The gate is a hot path and node:sqlite is synchronous — a lock-taking write there is the event-loop blocking that has made a busy box feel unresponsive before, and the statement is a no-op mid-turn anyway.

Verification

9 new assertions in scripts/turn-lifecycle-test.cjs (49 total): an old session with no UserPromptSubmit goes working on a tool call; a tool call doesn't clear a waiting card; the throttle never swallows the first call of a turn; a 3h-old stamp is wedged until a tool call revives it. Full suite green.

Deploy note: server restart required. Works on already-running sessions — that's the point.

🤖 Generated with Claude Code

https://claude.ai/code/session_015ZUfffxY4hKv7M6wMCcaTz