fix(subagent): give the liveness signal a clock and make completion reversible

[devsuitup]

detectSubagentTransitions() owns spawn, heartbeat and completion, but it only ran from the projects watcher's debounced flush. A function that runs when a file changes cannot see that a file stopped changing.

Measured in the app's own main.log, both failure directions:

Too late. Agent a9be19fb0a7e0e504 last wrote at 23:42:18; its completion was logged at 23:52:55 — 10 min 37 s for a 30 s stability window. The parent was idle (Claude is waiting for your input at 23:43:35), so nothing wrote in the folder and no flush ran. The event only fired when activity resumed, which is also what a user sees: the indicator clears the moment you start typing again, not when the agent finished.

Too early, and permanently. Three agents were declared complete while still working:

23:54:43 spawn a8e8c25f42a65b026 → 23:56:53 complete   (still writing at 00:02)
23:55:16 spawn a19dcbbb23270de85 → 00:00:27 complete   (still writing at 00:01:45)
00:11:29 spawn a412bb1bce6ecd952 → 00:14:18 complete   (still running)

A tool call longer than STABLE_MS is indistinguishable from a finished agent — that limitation was known and documented. What was not: the verdict was irreversible. The completion branch set completed = true with no recheck window, so the entry hit the completed fast path forever and the agent could never be announced again. That is why a session with several live subagents ends up showing no running indicator at all.

This is also why the tick alone would have made things worse: giving the stability window a clock makes false completions more frequent, not less. The two had to be fixed together.

Fix

• Main process: a self-arming settle tick (SETTLE_TICK_MS = 5 s) that only arms while an entry is uncompleted, re-arms from its own sweep, stops on its own, and is unref()d. No cost when no subagent is running.
• Main process: a stability completion now keeps a recheck window (LIVE_RECHECK_MS), so renewed growth rehabilitates the entry and re-emits the spawn — the same machinery already used for an assumed-finished file, now applied to this path too.
• Renderer: both safety nets had the same defect — pruneStaleGridSubagents() ran only from wrapInGridCard() and pruneStaleSubagents() only from renderProjects(), so a stale entry survived exactly in the idle case the TTL exists to cover. Each view now arms a one-shot timer at the oldest entry's deadline (not an interval), refreshes only the entries the prune actually removed, and stops when its map is empty — ADR 0002, no steady-state cost. These are a backstop; with the main-process signal repaired they should almost never fire.

Not changed

The watcher debounce has no maxWait. Starvation under sustained write load was the working hypothesis and it is refuted: the log shows completions emitted while three transcripts were being written. The real starvation is silence, not noise. HEARTBEAT_MS and the renderer TTL are untouched — widening them would only make the underlying defect rarer and harder to find.

Tests

test/subagent-settle-tick.test.js and test/dom-subagent-ttl-tick.test.js. Mock timers on both sides — no wall-clock waits, per docs/activity-trace.md. Every assertion checked by reverting the fix:

drop the settle tick arming     → completion must fire from the settle tick alone
drop the recheck window         → the withheld spawn must be re-emitted
drop the renderer timer arming  → each view arms its own TTL timer on the spawn — 0 !== 2
drop the targeted refresh       → the TTL tick must clear the row without waiting for a render

691 tests, 684 pass, 0 fail, 7 pre-existing skips. ESLint: 0 errors, 265 warnings before and after.

Reasoning and measurements in .ai/contexts/subagent-observability.md.