From a6783acfdb175bf7c340dff91cde83dc0f0151da Mon Sep 17 00:00:00 2001
From: Jean-Baptiste <jean-baptiste@konvex-it.fr>
Date: Mon, 24 Aug 2026 00:12:38 +0200
Subject: [PATCH] fix(subagent): give the liveness signal a clock and make
 completion reversible
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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: agent a9be19fb0a7e0e504
last wrote at 23:42:18 and its completion was logged at 23:52:55 — 10 min 37 s
for a 30 s stability window — because the folder went quiet and no flush ran.

The same window also fires wrongly. Agents a8e8c25f42a65b026 and
a19dcbbb23270de85 were declared complete at 23:56:53 and 00:00:27 while still
writing minutes later: a tool call longer than the window reads as a finished
agent. That verdict was irreversible — the entry carried no recheck window, so
it hit the completed fast path forever and the agent could never light up
again. A stability completion now keeps a recheck window, so renewed growth
rehabilitates it and re-emits the spawn. That is what makes the tick safe:
adding a clock makes false completions more frequent, not less.

Rather than let such an agent oscillate, its stability window widens on each
rehabilitation along a capped ladder (30 s, 2 min, MAX_STABLE_MS) so it
converges. An assumed-finished entry is deliberately excluded: it carries no
evidence of long silences, and widening it would slow the normal case.

Widening needs one companion change. A wider window lets an agent stay silent
past the renderer's TTL without completing, and the renderer refuses a
heartbeat for an agent it no longer tracks — on its own the widening would
trade a blink for a permanent blackout. The growth branch therefore emits a
real spawn instead of a heartbeat once the agent has been unseen that long.

That agreement between the main process and the two views was three separate
60000 literals held together by a comment; shortening one alone silently
recreates the blackout. public/subagent-timing.js is now the single definition,
using the dual-mode pattern of public/shortcuts.js: classic script for the
renderer, module.exports for require().

Both renderer safety nets had the same shape of bug — 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, refreshes only the entries the prune removed, and stops when its map
is empty (ADR 0002: no steady-state cost).

Not changed: the watcher debounce has no maxWait, but the log shows completions
emitted while three transcripts were being written, so starvation under write
load is refuted and nothing was added for it.
---
 .ai/contexts/subagent-observability.md        | 169 +++++-
 eslint.config.js                              |  23 +
 public/grid-view.js                           |  30 +-
 public/index.html                             |   1 +
 public/sidebar.js                             |  30 +-
 public/subagent-timing.js                     |   9 +
 session-transitions.js                        |  65 ++-
 test/dom-grid-sidebar-prune-collision.test.js |   2 +-
 test/dom-grid-subagent-pills.test.js          |   2 +-
 test/dom-setup.js                             |   1 +
 test/dom-subagent-transcript.test.js          |   1 +
 test/dom-subagent-ttl-tick.test.js            | 282 ++++++++++
 test/session-transitions.test.js              |   8 +
 test/subagent-settle-tick.test.js             | 504 ++++++++++++++++++
 test/terminal-manager-harness.js              |   2 +-
 test/terminal-manager-lifecycle.test.js       |   2 +-
 16 files changed, 1117 insertions(+), 14 deletions(-)
 create mode 100644 public/subagent-timing.js
 create mode 100644 test/dom-subagent-ttl-tick.test.js
 create mode 100644 test/subagent-settle-tick.test.js

diff --git a/.ai/contexts/subagent-observability.md b/.ai/contexts/subagent-observability.md
index 9cf905a8..135898e6 100644
--- a/.ai/contexts/subagent-observability.md
+++ b/.ai/contexts/subagent-observability.md
@@ -66,7 +66,8 @@ This is the **#1 fork-specific feature** (upstream PR #47 still pending). It per
   `.running` from this Map on every render, so the state survives a full
   sidebar rebuild; the IPC handlers only fast-path the visual toggle between
   rebuilds (`reflectSubagentRunningState`).
-- **Why a TTL** (`SUBAGENT_LIVE_TTL_MS` = 60s, mirroring grid-view's):
+- **Why a TTL** (`SUBAGENT_LIVE_TTL_MS` = 60s, shared with grid-view — see
+  "One TTL, one definition" below):
   `detectSubagentTransitions()` only polls subagents of `!exited` sessions —
   if the parent's PTY dies before a subagent goes 30s quiet, the matching
   `subagent-completed` never fires and the entry would be stuck forever.
@@ -140,6 +141,20 @@ when a *new* subagent starts. Two rules keep that rescan quiet:
   re-added it, at the cost of a `statSync` and a `readSubagentMeta()` each.
   The map is now bounded by the directory's own file count.
 
+The settle tick reopens this question, because the predicate that arms it counts
+completed-but-still-falsifiable entries — which is exactly what bootstrap leaves
+behind for a *recent* file. So the periodic sweep now rescans the very entries
+PR #147 was about, with no watcher event involved. It does not wake the ghost:
+those entries are recorded `completed: true`, and the rehabilitation branch fires
+only on an mtime that actually moved. That is pinned by execution, not by
+reading — `test/subagent-settle-tick.test.js` drives the tick past the close of
+the window on a bootstrap file and asserts no IPC is ever emitted, and a sibling
+test grows the file mid-window to check the late spawn is still emitted, once.
+Neutralising the mtime-growth condition makes the first test report
+`the tick must never announce a bootstrap file, got
+["subagent-spawned","subagent-completed","subagent-spawned"]` — the ghost, now
+oscillating on a clock.
+
 Renderer side, `subagent-spawned` doubles as the still-alive heartbeat
 (`payload._heartbeat`). **A heartbeat refreshes an agent already tracked; it
 never creates an entry** — in `public/sidebar.js` and `public/grid-view.js`
@@ -175,6 +190,158 @@ an agent tracked from its first line. The renderer's 60 s TTL has the same
 shape. Anything that needs true liveness would have to come from the parent
 process, not from mtime.
 
+## The liveness signal needs a clock of its own (measured 2026-08-23/24)
+
+`detectSubagentTransitions()` owns three signals — spawn, heartbeat, completion —
+and until now it ran from exactly one place: the projects watcher's debounced
+flush (`main.js:startProjectsWatcher`, `setTimeout(flushChanges, 500)` re-armed
+on every `fs.watch` event over `PROJECTS_DIR`). A function that only runs when a
+file changes cannot detect that a file **stopped** changing. Three symptoms,
+all measured in `~/AppData/Roaming/switchboard/logs/main.log`:
+
+- **Completion arrives minutes late.** Agent `a9be19fb0a7e0e504`: last transcript
+  write 23:42:18, `[subagent-complete]` logged **23:52:55** — 10 min 37 s for a
+  30 s stability window. The parent was `waiting for your input` (OSC 9 at
+  23:43:35), so nothing wrote in the folder and no flush ran. The event fired at
+  the moment activity resumed, which is what the user saw as "the indicators
+  went dark when the parent came back".
+- **Completion also arrives *wrongly*.** Agents `a8e8c25f42a65b026` and
+  `a19dcbbb23270de85` were declared complete at 23:56:53 and 00:00:27 while
+  still writing at 00:02:00 and 00:01:45. A tool call longer than `STABLE_MS`
+  is indistinguishable from a finished agent — a documented limitation, but the
+  verdict was **irreversible**: the completion branch set `completed = true`
+  without a `_recheckStart`, so the entry hit the
+  `if (known.completed && !known._recheckStart) continue` fast path forever and
+  the agent could never light up again. `LIVE_RECHECK_MS` (5 min) now keeps a
+  stability completion falsifiable exactly like an assumed-finished one; renewed
+  growth rehabilitates it and re-emits the spawn (`[subagent-spawn-late]`).
+  This is load-bearing for the tick below: giving the stability clock a clock
+  makes false completions *more* frequent, not less, so reversibility is the
+  half that makes the pair safe.
+
+  **The window widens on each rehabilitation** — `STABLE_LADDER_MS`
+  (30 s -> 2 min -> `MAX_STABLE_MS` = 5 min, capped by name, carried on the
+  entry as `_stableMs`). An agent that has already gone quiet for longer than
+  its window is an agent whose silences are long; widening converges instead of
+  letting it oscillate complete -> rehabilitated -> complete, one visible blink
+  per cycle. The widening is deliberately **not** applied to the other
+  rehabilitation case: an *assumed*-finished entry (bootstrap, or a stale first
+  sighting) was never declared finished by the stability timer and carries no
+  evidence of long silences, so widening it would slow the normal case for
+  nothing. `_recheckMs` is the discriminator — it is set only on a stability
+  completion. Getting that wrong is caught by the two pre-existing bootstrap
+  reversibility tests.
+
+  **Widening required one companion change.** A wider window means an agent can
+  stay silent past the renderer's 60 s TTL without being completed — and the
+  renderer refuses a heartbeat for an agent it no longer tracks, by design. On
+  its own the widening would therefore have traded a blink for a permanent
+  blackout: exactly the bug being fixed, since before this branch the
+  completion/rehabilitation pair was the *only* path that re-lit a TTL-pruned
+  entry. So when the growth branch finds the agent unseen for at least
+  `SUBAGENT_LIVE_TTL_MS` it emits a **real spawn instead of a heartbeat**. That is
+  safe in all three cases the no-resurrect guard defends against: a completed
+  entry never reaches the growth branch, a TTL-pruned one is precisely what we
+  want to revive on fresh evidence of growth, and a dead parent never gets
+  scanned at all (`detectSubagentTransitions` runs only for `!exited`
+  sessions).
+- **Heartbeats stop too**, and the renderer's 60 s TTL then evicts a live agent.
+  Combined with "a heartbeat never resurrects an untracked agent", that eviction
+  is permanent as well.
+
+The settle tick (`SETTLE_TICK_MS`, `armSubagentSettleTick`) re-runs the scan for
+sessions that still hold a non-completed entry, independent of the watcher. It
+arms only when something is unsettled, re-arms from its own sweep, and stops on
+its own once every tracked agent has both completed **and** closed its recheck
+window — no idle cost when no subagent is running. `unref()` keeps it out of the
+way of process shutdown and of tests.
+
+A completed-but-still-falsifiable entry counts as unsettled on purpose: without
+that, in a silent folder its window could only ever close on a write to some
+*other* file in the same folder, so the "generous but bounded" promise above
+would not hold. Note that arming is guarded in two places — in
+`armSubagentSettleTick` and again in the sweep — so a test that only drains
+timers cannot tell the two apart; `test/subagent-settle-tick.test.js` scans a
+settled session directly and asserts nothing gets armed.
+
+**Refuted, so it does not get fixed here**: the debounce being *starved* by a
+flood of writes (re-armed faster than 500 ms while several transcripts append).
+The log disproves it — completions were emitted at 23:56:53 and 00:00:27 while
+three transcripts were being written, so the flush was running normally under
+load. No `maxWait` was added.
+
+### One TTL, one definition
+
+The main process and both renderer views must agree on the liveness TTL, and
+the failure is silent and one-directional: shorten the renderer's TTL alone and
+there is a band of durations in which the renderer has already pruned the entry
+while the main process is still sending heartbeats the renderer refuses — the
+permanent blackout this branch exists to fix, reintroduced with nothing to
+catch it. (Diverging the other way is harmless.)
+
+It used to be three independent `60000` literals held together by a comment.
+`public/subagent-timing.js` is now the single definition, following the
+dual-mode pattern already used by `public/shortcuts.js` and
+`public/terminal-manager.js`: a classic `<script>` for the renderer plus a
+`typeof module !== 'undefined'` export footer for `require()`. Three consumption
+contexts, all of which have to keep working:
+
+- **main process** — `require('./public/subagent-timing')` from
+  `session-transitions.js`. Root-to-`public/` is a new direction for this repo
+  but the directory is already in electron-builder's `files`, so it ships.
+- **renderer** — `<script src="subagent-timing.js">` in `index.html`, placed
+  before `grid-view.js` and `sidebar.js`. A top-level `const` lands in the
+  global *lexical* scope, not on `window`: sibling scripts resolve the bare
+  identifier, but `window.SUBAGENT_LIVE_TTL_MS` is `undefined`. Don't "verify"
+  the wiring by reading it off `window`.
+- **jsdom harness** — every harness that evaluates `sidebar.js` or
+  `grid-view.js` must evaluate `subagent-timing.js` first or they die on
+  `no-undef`/ReferenceError. Seven of them do (`test/dom-setup.js` plus six
+  test files with their own file lists); a new harness has to remember.
+
+`eslint.config.js` carries the constant in `rendererCrossFileGlobals` for the
+consumers, and gives the *producing* file its own block that switches that
+global `off` — otherwise `no-redeclare` flags the single definition, which is
+what the eight standing warnings on `shortcuts.js` are.
+
+### The renderer safety nets had no clock either
+
+`pruneStaleGridSubagents()` was called only from `wrapInGridCard()` and
+`pruneStaleSubagents()` only from `renderProjects()` — both render-driven, so a
+stale entry survived exactly in the idle case the TTL exists to cover. Each view
+now arms its own one-shot timer (`scheduleGridSubagentTtlTick` /
+`scheduleSubagentTtlTick`, names kept distinct per the shadowing rule above),
+scheduled **at the oldest entry's deadline** rather than on a polling interval:
+one wakeup per TTL period while agents are tracked, none at all when the map is
+empty, and a targeted refresh (`updateGridSubagentPills` /
+`reflectSubagentRunningState`) only for the entries the prune actually removed.
+That satisfies ADR 0002 — no steady-state cost, no render on an empty tick.
+
+The deadline arithmetic is `Math.max(1, oldest + TTL + 1 - now)`, and the tests
+assert on the armed `delay`, not just on the eviction — a constant interval or
+an inverted sign is otherwise invisible, which is precisely the property ADR
+0002 exists to protect. Note that the `Math.max` is unreachable: the prune
+deletes on a strict `spawnedAt < now - TTL`, so any entry that survives it
+satisfies `oldest + TTL >= now` and the expression is already `>= 1`. The `+1`
+is the part that keeps a boundary tick off `setTimeout(0)`. Both are kept, and
+the test pins the invariant (`delay >= 1`) rather than either guard, so it still
+holds if the prune's comparison is ever loosened to `<=`.
+
+These nets are a **backstop, not the fix**: with the main-process signal
+repaired they should almost never fire. `test/subagent-settle-tick.test.js` and
+`test/dom-subagent-ttl-tick.test.js` pin both halves; the DOM one substitutes
+`window.setTimeout` so the tick is driven by its own condition, never by a wall
+clock wait (see `docs/activity-trace.md`, "Testing the async prune path").
+
+### Still open
+
+The grid was reported showing two live pills while the sidebar showed one, at a
+moment when the log says one of the two had already been (falsely) completed.
+`onSubagentCompleted` removes the grid entry and calls
+`updateGridSubagentPills`, which is a no-op when `gridCards` has no card for
+that parent id — a plausible explanation, **not verified**: it needs the live
+DOM, which was not available.
+
 ## Subagent children inside a slug group (issue #128 ask 4, rehab-plan.md A3)
 
 - **The bug**: `buildSlugGroup()` used to append its sessions via the raw
diff --git a/eslint.config.js b/eslint.config.js
index 98c47050..8f3e5cc3 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -130,6 +130,7 @@ const rendererCrossFileGlobals = {
   folderId: 'readonly',
   slugId: 'readonly',
   subagentTypeColor: 'readonly',
+  SUBAGENT_LIVE_TTL_MS: 'readonly',
   getExpandedSubagents: 'readonly',
   saveExpandedSubagents: 'readonly',
   getExpandedSlugs: 'readonly',
@@ -295,6 +296,28 @@ module.exports = [
     },
   },
 
+  // Producer of a cross-file renderer global: classic <script> in the renderer,
+  // require()-d by the main process and tests. It declares SUBAGENT_LIVE_TTL_MS
+  // rather than consuming it, so the global is switched off here — otherwise
+  // no-redeclare flags the one definition the other two files depend on.
+  {
+    files: ['public/subagent-timing.js'],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: 'script',
+      globals: {
+        ...globals.browser,
+        module: 'writable',
+        SUBAGENT_LIVE_TTL_MS: 'off',
+      },
+    },
+    rules: {
+      'no-undef': 'error',
+      'no-unused-vars': ['warn', { args: 'none', varsIgnorePattern: '^_' }],
+      'no-redeclare': 'warn',
+    },
+  },
+
   // CodeMirror setup file uses ESM-style imports/closure that don't lint well
   // as a classic script — keep no-undef on but be permissive about unused.
   {
diff --git a/public/grid-view.js b/public/grid-view.js
index f6df5d62..e0a905bf 100644
--- a/public/grid-view.js
+++ b/public/grid-view.js
@@ -46,6 +46,7 @@ function gridSubagentColor(type) {
         activeSubagents.set(parentSessionId, map);
       }
       map.set(agentId, { agentId, subagentType, spawnedAt: Date.now() });
+      scheduleGridSubagentTtlTick();
       updateGridSubagentPills(parentSessionId);
     });
   }
@@ -67,7 +68,7 @@ function gridSubagentColor(type) {
 // Prune subagents that have been running for more than 60 s without a completion event.
 // see .ai/contexts/subagent-observability.md
 function pruneStaleGridSubagents() {
-  const cutoff = Date.now() - 60000;
+  const cutoff = Date.now() - SUBAGENT_LIVE_TTL_MS;
   for (const [parentId, map] of activeSubagents) {
     for (const [agentId, info] of map) {
       if (info.spawnedAt < cutoff) map.delete(agentId);
@@ -76,6 +77,33 @@ function pruneStaleGridSubagents() {
   }
 }
 
+let gridSubagentTtlTimer = null;
+
+function scheduleGridSubagentTtlTick() {
+  if (gridSubagentTtlTimer) return;
+  let oldest = Infinity;
+  for (const map of activeSubagents.values()) {
+    for (const info of map.values()) {
+      if (info.spawnedAt < oldest) oldest = info.spawnedAt;
+    }
+  }
+  if (oldest === Infinity) return;
+  const delay = Math.max(1, oldest + SUBAGENT_LIVE_TTL_MS + 1 - Date.now());
+  gridSubagentTtlTimer = setTimeout(runGridSubagentTtlTick, delay);
+}
+
+function runGridSubagentTtlTick() {
+  gridSubagentTtlTimer = null;
+  const sizeBefore = new Map();
+  for (const [parentId, map] of activeSubagents) sizeBefore.set(parentId, map.size);
+  pruneStaleGridSubagents();
+  for (const [parentId, size] of sizeBefore) {
+    const map = activeSubagents.get(parentId);
+    if (!map || map.size !== size) updateGridSubagentPills(parentId);
+  }
+  scheduleGridSubagentTtlTick();
+}
+
 // Re-render the pill row for a single card (if it exists in the grid).
 function updateGridSubagentPills(parentSessionId) {
   const card = gridCards.get(parentSessionId);
diff --git a/public/index.html b/public/index.html
index e407cf6d..63a7ac19 100644
--- a/public/index.html
+++ b/public/index.html
@@ -120,6 +120,7 @@
   <script src="file-panel.js"></script>
   <script src="settings-panel.js"></script>
   <script src="utils.js"></script>
+  <script src="subagent-timing.js"></script>
   <!-- shortcuts.js defines matchShortcut/appShortcuts helpers used by terminal-manager,
        grid-view, app and settings-panel — must load before those consumers. -->
   <script src="shortcuts.js"></script>
diff --git a/public/sidebar.js b/public/sidebar.js
index f2e96e0d..a19f4ea3 100644
--- a/public/sidebar.js
+++ b/public/sidebar.js
@@ -92,7 +92,6 @@ function subagentTypeColor(type) {
 // then evicts agents that went silent without evicting one that merely runs
 // longer than a minute.
 const activeSubagentsByParent = new Map();
-const SUBAGENT_LIVE_TTL_MS = 60000;
 
 function isSubagentActive(parentSessionId, agentId) {
   const map = activeSubagentsByParent.get(parentSessionId);
@@ -115,6 +114,34 @@ function pruneStaleSubagents() {
   if (window.ATRACE) window.atrace('subagents.prune', null, { map: 'activeSubagentsByParent', cutoff, parents: activeSubagentsByParent.size, agents: [...activeSubagentsByParent.values()].reduce((n, m) => n + m.size, 0), fn: 'pruneStaleSubagents' });
 }
 
+let subagentTtlTimer = null;
+
+function scheduleSubagentTtlTick() {
+  if (subagentTtlTimer) return;
+  let oldest = Infinity;
+  for (const map of activeSubagentsByParent.values()) {
+    for (const lastSeenAt of map.values()) {
+      if (lastSeenAt < oldest) oldest = lastSeenAt;
+    }
+  }
+  if (oldest === Infinity) return;
+  const delay = Math.max(1, oldest + SUBAGENT_LIVE_TTL_MS + 1 - Date.now());
+  subagentTtlTimer = setTimeout(runSubagentTtlTick, delay);
+}
+
+function runSubagentTtlTick() {
+  subagentTtlTimer = null;
+  const tracked = [];
+  for (const [parentId, map] of activeSubagentsByParent) {
+    for (const agentId of map.keys()) tracked.push([parentId, agentId]);
+  }
+  pruneStaleSubagents();
+  for (const [parentId, agentId] of tracked) {
+    if (!isSubagentActive(parentId, agentId)) reflectSubagentRunningState(parentId, agentId);
+  }
+  scheduleSubagentTtlTick();
+}
+
 // Drop all live-subagent state for a parent whose PTY just stopped, and sync
 // the DOM immediately. Called from app.js's updateRunningIndicators():
 // stop-session kills the PTY without emitting subagent-completed, and
@@ -180,6 +207,7 @@ function reflectSubagentRunningState(parentSessionId, agentId) {
       }
       if (window.ATRACE) window.atrace('recv.subagent-spawned', parentSessionId, { map: 'activeSubagentsByParent', op: 'set', agentId, from: map.get(agentId) ?? null, applied: true, bootstrap: !!payload._bootstrap, heartbeat: !!_heartbeat, fn: 'onSubagentSpawned' });
       map.set(agentId, Date.now());
+      scheduleSubagentTtlTick();
       reflectSubagentRunningState(parentSessionId, agentId);
     });
   }
diff --git a/public/subagent-timing.js b/public/subagent-timing.js
new file mode 100644
index 00000000..998651c5
--- /dev/null
+++ b/public/subagent-timing.js
@@ -0,0 +1,9 @@
+// Shared subagent liveness timings.
+// Classic <script> in the renderer, require()-d in the main process and tests.
+// see .ai/contexts/subagent-observability.md
+
+const SUBAGENT_LIVE_TTL_MS = 60000;
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { SUBAGENT_LIVE_TTL_MS };
+}
diff --git a/session-transitions.js b/session-transitions.js
index 246a9d25..be801f94 100644
--- a/session-transitions.js
+++ b/session-transitions.js
@@ -2,6 +2,7 @@ const path = require('path');
 const fs = require('fs');
 const { readSubagentMeta } = require('./read-session-file');
 const { enabled: TRACE, trace } = require('./activity-trace');
+const { SUBAGENT_LIVE_TTL_MS } = require('./public/subagent-timing');
 
 /**
  * Fork detection for active PTY sessions.
@@ -19,6 +20,47 @@ function init(ctx) {
 
 // --- Subagent spawn / completion detection ---
 
+// see .ai/contexts/subagent-observability.md
+const SETTLE_TICK_MS = 5000;
+const STABLE_MS = 30000;
+const MAX_STABLE_MS = 300000;
+const STABLE_LADDER_MS = [STABLE_MS, 120000, MAX_STABLE_MS];
+let settleTimer = null;
+
+function nextStableMs(current) {
+  const i = STABLE_LADDER_MS.indexOf(current || STABLE_MS);
+  if (i < 0 || i + 1 >= STABLE_LADDER_MS.length) return MAX_STABLE_MS;
+  return STABLE_LADDER_MS[i + 1];
+}
+
+function hasUnsettledSubagents(session) {
+  if (!session.knownSubagents) return false;
+  for (const known of session.knownSubagents.values()) {
+    if (!known.completed || known._recheckStart) return true;
+  }
+  return false;
+}
+
+function armSubagentSettleTick(session) {
+  if (settleTimer || !hasUnsettledSubagents(session)) return;
+  settleTimer = setTimeout(runSubagentSettleTick, SETTLE_TICK_MS);
+  if (typeof settleTimer.unref === 'function') settleTimer.unref();
+}
+
+function runSubagentSettleTick() {
+  settleTimer = null;
+  if (!activeSessions) return;
+  for (const [sessionId, session] of [...activeSessions]) {
+    if (session.exited || session.isPlainTerminal || !session.projectFolder) continue;
+    if (!hasUnsettledSubagents(session)) continue;
+    detectSubagentTransitions(
+      session.realSessionId || sessionId,
+      session,
+      path.join(PROJECTS_DIR, session.projectFolder)
+    );
+  }
+}
+
 /** Walk <folder>/<sessionId>/subagents/ and detect new or completed subagent files.
  *  Mutates session.knownSubagents (Map<agentId, { mtimeMs, completed }>).
  *  Emits IPC 'subagent-spawned' and 'subagent-completed' via mainWindow. */
@@ -79,8 +121,8 @@ function detectSubagentTransitions(sessionId, session, folderPath) {
 
   const mainWindow = getMainWindow();
   const now = Date.now();
-  const STABLE_MS = 30000; // 30 seconds of no mtime advance → completed
   const FRESH_SIGHTING_MS = 60000; // post-bootstrap: first sighting counts as live if newer than this
+  const LIVE_RECHECK_MS = 300000; // an agent completed by the stability timer stays falsifiable this long
   // Re-emit subagent-spawned (idempotent on the renderer side — it just
   // refreshes the entry's last-seen timestamp) at most every HEARTBEAT_MS
   // while an agent's file keeps growing. Without this, the renderer's 60s
@@ -170,7 +212,9 @@ function detectSubagentTransitions(sessionId, session, folderPath) {
         known.mtimeMs = mtimeMs;
         known.completed = false;
         known._completedAt = null;
+        if (known._recheckMs) known._stableMs = nextStableMs(known._stableMs);
         known._recheckStart = null;
+        known._recheckMs = null;
         known._stableStart = null;
         known.subagentType = meta.agentType || null;
         known.description = meta.description || null;
@@ -184,9 +228,10 @@ function detectSubagentTransitions(sessionId, session, folderPath) {
             description: meta.description || null,
           });
         }
-      } else if (now - known._recheckStart >= STABLE_MS) {
+      } else if (now - known._recheckStart >= (known._recheckMs || STABLE_MS)) {
         // Observed motionless for a full stability window — settled.
         known._recheckStart = null;
+        known._recheckMs = null;
       }
     } else {
       if (mtimeMs !== known.mtimeMs) {
@@ -194,25 +239,29 @@ function detectSubagentTransitions(sessionId, session, folderPath) {
         known.mtimeMs = mtimeMs;
         known._stableStart = null;
         // Still-alive heartbeat (throttled) — see HEARTBEAT_MS above.
-        if (now - (known._lastHeartbeatAt || 0) >= HEARTBEAT_MS
-            && mainWindow && !mainWindow.isDestroyed()) {
+        const unseenForMs = now - (known._lastHeartbeatAt || 0);
+        if (unseenForMs >= HEARTBEAT_MS && mainWindow && !mainWindow.isDestroyed()) {
+          // see .ai/contexts/subagent-observability.md
+          const stale = unseenForMs >= SUBAGENT_LIVE_TTL_MS;
           known._lastHeartbeatAt = now;
-          if (TRACE) trace('subagent.spawned', sessionId, { agentId, kind: 'heartbeat', subagentType: known.subagentType || null, sent: true });
+          if (TRACE) trace('subagent.spawned', sessionId, { agentId, kind: stale ? 'reannounce' : 'heartbeat', subagentType: known.subagentType || null, sent: true });
           mainWindow.webContents.send('subagent-spawned', {
             parentSessionId: sessionId,
             agentId,
             subagentType: known.subagentType || null,
             description: known.description || null,
-            _heartbeat: true,
+            ...(stale ? {} : { _heartbeat: true }),
           });
         }
       } else {
         // mtime stable — start or continue stability timer
         if (!known._stableStart) {
           known._stableStart = now;
-        } else if (now - known._stableStart >= STABLE_MS) {
+        } else if (now - known._stableStart >= (known._stableMs || STABLE_MS)) {
           known.completed = true;
           known._completedAt = now;
+          known._recheckStart = now;
+          known._recheckMs = LIVE_RECHECK_MS;
           log.info(`[subagent-complete] parent=${sessionId} agentId=${agentId}`);
           if (TRACE) trace('subagent.completed', sessionId, { agentId, stableForMs: now - known._stableStart, reason: 'mtime-stable', sent: !!(mainWindow && !mainWindow.isDestroyed()) });
           if (mainWindow && !mainWindow.isDestroyed()) {
@@ -238,6 +287,8 @@ function detectSubagentTransitions(sessionId, session, folderPath) {
       if (!onDisk.has(agentId)) session.knownSubagents.delete(agentId);
     }
   }
+
+  armSubagentSettleTick(session);
 }
 
 // --- Fork detection ---
diff --git a/test/dom-grid-sidebar-prune-collision.test.js b/test/dom-grid-sidebar-prune-collision.test.js
index dd787534..ee9f77cf 100644
--- a/test/dom-grid-sidebar-prune-collision.test.js
+++ b/test/dom-grid-sidebar-prune-collision.test.js
@@ -89,7 +89,7 @@ function setupCombinedDom() {
   const MORPHDOM_PATH = path.join(__dirname, '..', 'node_modules', 'morphdom', 'dist', 'morphdom-umd.js');
   vm.runInContext(fs.readFileSync(MORPHDOM_PATH, 'utf8'), dom.getInternalVMContext(), { filename: 'morphdom-umd.js' });
 
-  for (const file of ['utils.js', 'icons.js', 'shortcuts.js', 'grid-view.js', 'sidebar.js']) {
+  for (const file of ['utils.js', 'icons.js', 'shortcuts.js', 'subagent-timing.js', 'grid-view.js', 'sidebar.js']) {
     evalInWindow(dom, path.join(PUBLIC_DIR, file));
   }
 
diff --git a/test/dom-grid-subagent-pills.test.js b/test/dom-grid-subagent-pills.test.js
index 50b92fe7..012cd72f 100644
--- a/test/dom-grid-subagent-pills.test.js
+++ b/test/dom-grid-subagent-pills.test.js
@@ -58,7 +58,7 @@ function setupGridDom() {
   }
 
   const ctx = dom.getInternalVMContext();
-  for (const file of ['utils.js', 'shortcuts.js', 'grid-view.js']) {
+  for (const file of ['utils.js', 'shortcuts.js', 'subagent-timing.js', 'grid-view.js']) {
     vm.runInContext(fs.readFileSync(path.join(PUBLIC_DIR, file), 'utf8'), ctx, { filename: file });
   }
 
diff --git a/test/dom-setup.js b/test/dom-setup.js
index afc359f8..c4966973 100644
--- a/test/dom-setup.js
+++ b/test/dom-setup.js
@@ -119,6 +119,7 @@ function setupSidebarDom() {
   // Real utils.js and icons.js — small and dependency-free.
   evalInWindow(dom, path.join(PUBLIC_DIR, 'utils.js'));
   evalInWindow(dom, path.join(PUBLIC_DIR, 'icons.js'));
+  evalInWindow(dom, path.join(PUBLIC_DIR, 'subagent-timing.js'));
 
   // Finally, sidebar.js.
   evalInWindow(dom, path.join(PUBLIC_DIR, 'sidebar.js'));
diff --git a/test/dom-subagent-transcript.test.js b/test/dom-subagent-transcript.test.js
index 349a4c0d..20d884c5 100644
--- a/test/dom-subagent-transcript.test.js
+++ b/test/dom-subagent-transcript.test.js
@@ -146,6 +146,7 @@ function setupDom({ readSubagentJsonlResult = { entries: SAMPLE_ENTRIES }, readS
 
   evalInWindow(dom, path.join(PUBLIC_DIR, 'utils.js'));
   evalInWindow(dom, path.join(PUBLIC_DIR, 'icons.js'));
+  evalInWindow(dom, path.join(PUBLIC_DIR, 'subagent-timing.js'));
   evalInWindow(dom, path.join(PUBLIC_DIR, 'sidebar.js'));
   // jsonl-viewer.js defines showSubagentTranscript — eval'd here so the real
   // implementation is available when tests exercise it directly. For routing
diff --git a/test/dom-subagent-ttl-tick.test.js b/test/dom-subagent-ttl-tick.test.js
new file mode 100644
index 00000000..fea31fb8
--- /dev/null
+++ b/test/dom-subagent-ttl-tick.test.js
@@ -0,0 +1,282 @@
+// see .ai/contexts/subagent-observability.md
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const { JSDOM } = require('jsdom');
+
+const PUBLIC_DIR = path.join(__dirname, '..', 'public');
+
+function evalInWindow(dom, file) {
+  vm.runInContext(fs.readFileSync(file, 'utf8'), dom.getInternalVMContext(), { filename: file });
+}
+
+function setupCombinedDom() {
+  const dom = new JSDOM(
+    '<!DOCTYPE html><html><body><div id="sidebar-content"></div><div id="stats-content"></div>' +
+    '<div id="memory-content"></div><div id="placeholder"></div><div id="terminals"></div></body></html>',
+    { url: 'http://localhost/', runScripts: 'outside-only', pretendToBeVisual: true }
+  );
+  const { window } = dom;
+
+  const spawnedCbs = [];
+  const completedCbs = [];
+  const apiTarget = {
+    platform: 'linux',
+    onSubagentSpawned: (cb) => { spawnedCbs.push(cb); },
+    onSubagentCompleted: (cb) => { completedCbs.push(cb); },
+  };
+  window.api = new Proxy(apiTarget, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      return () => Promise.resolve({ ok: true });
+    },
+  });
+
+  const stubGlobals = {
+    openSessions: new Map(),
+    activeSessionId: null,
+    sessionMap: new Map(),
+    activePtyIds: new Set(),
+    sortedOrder: [],
+    cachedProjects: [],
+    confirmAndStopSession: () => {},
+    showSession: () => {},
+    sidebarContent: window.document.getElementById('sidebar-content'),
+    terminalsEl: window.document.getElementById('terminals'),
+    gridViewActive: false,
+    isMac: false,
+    replayHiddenBuffer: () => {},
+    updateRunningIndicators: () => {},
+    fitAndScroll: () => {},
+    statsContent: window.document.getElementById('stats-content'),
+    memoryContent: window.document.getElementById('memory-content'),
+    pendingSessions: new Map(),
+    lastActivityTime: new Map(),
+    searchMatchIds: null,
+    searchMatchProjectPaths: null,
+    showStarredOnly: false,
+    showRunningOnly: false,
+    showTodayOnly: false,
+    visibleSessionCount: 10,
+    sessionMaxAgeDays: 3650,
+    attentionSessions: new Set(),
+    responseReadySessions: new Set(),
+    sessionBusyState: new Map(),
+    cachedAllProjects: [],
+    pollActiveSessions: () => {},
+    showNewSessionPopover: () => {},
+    openSettingsViewer: () => {},
+    showResumeSessionDialog: () => {},
+    showJsonlViewer: () => {},
+    forkSession: () => {},
+    openSession: () => {},
+    loadProjects: () => {},
+    launchScheduleCreator: () => {},
+    getExpandedSlugs: () => new Set(),
+    saveExpandedSlugs: () => {},
+  };
+  for (const [k, v] of Object.entries(stubGlobals)) {
+    Object.defineProperty(window, k, { value: v, writable: true, configurable: true });
+  }
+
+  const MORPHDOM_PATH = path.join(__dirname, '..', 'node_modules', 'morphdom', 'dist', 'morphdom-umd.js');
+  vm.runInContext(fs.readFileSync(MORPHDOM_PATH, 'utf8'), dom.getInternalVMContext(), { filename: 'morphdom-umd.js' });
+  for (const file of ['utils.js', 'icons.js', 'shortcuts.js', 'subagent-timing.js', 'grid-view.js', 'sidebar.js']) {
+    evalInWindow(dom, path.join(PUBLIC_DIR, file));
+  }
+
+  // Capture scheduled timers instead of letting them run on the wall clock:
+  // the tick is driven by its own condition, never by waiting.
+  const scheduled = [];
+  window.setTimeout = (fn, delay) => { scheduled.push({ fn, delay }); return scheduled.length; };
+  window.clearTimeout = () => {};
+
+  return {
+    window,
+    document: window.document,
+    scheduled,
+    runScheduled() {
+      const pending = scheduled.splice(0, scheduled.length);
+      for (const { fn } of pending) fn();
+    },
+    emitSubagentSpawned(payload) { for (const cb of spawnedCbs) cb(payload); },
+    destroy() { window.close(); },
+  };
+}
+
+const PARENT = 'parent-1';
+const AGENT = 'agent-1';
+const AGENT2 = 'agent-2';
+const TTL_MS = 60000;
+
+/** Every armed timer must be due at the entry's deadline, not on a poll. */
+function assertArmedAt(ctx, expected, what) {
+  assert.ok(ctx.scheduled.length > 0, `expected an armed timer (${what})`);
+  for (const { delay } of ctx.scheduled) {
+    assert.ok(Number.isFinite(delay) && delay >= 1,
+      `${what}: a tick must never be armed at ${delay} — a non-positive delay spins on setTimeout(0)`);
+    assert.ok(Math.abs(delay - expected) <= 50,
+      `${what}: expected a wakeup ~${expected}ms away (the entry's deadline), got ${delay}ms`);
+  }
+}
+
+function sampleProject() {
+  return {
+    projectPath: '/home/dev/proj',
+    sessions: [
+      {
+        sessionId: PARENT,
+        name: 'parent session',
+        summary: 'parent session',
+        modified: '2026-05-22T10:00:00.000Z',
+        archived: 0,
+      },
+      {
+        sessionId: 'sub:' + PARENT + ':' + AGENT,
+        parentSessionId: PARENT,
+        agentId: AGENT,
+        subagentType: 'explore',
+        description: 'explore subagent',
+        modified: '2026-05-22T10:00:00.000Z',
+      },
+    ],
+  };
+}
+
+test('sidebar: a stale subagent is evicted by the TTL tick with no render in between', () => {
+  const ctx = setupCombinedDom();
+  try {
+    ctx.window.renderProjects([sampleProject()], true);
+    ctx.emitSubagentSpawned({ parentSessionId: PARENT, agentId: AGENT, subagentType: 'explore' });
+
+    const row = ctx.document.getElementById('si-sub:' + PARENT + ':' + AGENT);
+    assert.ok(row, 'the subagent row must be in the DOM');
+    assert.ok(row.classList.contains('running'), 'the spawn lights the row');
+    assert.equal(ctx.scheduled.length, 2, 'each view arms its own TTL timer on the spawn');
+    assertArmedAt(ctx, TTL_MS, 'fresh spawn');
+
+    // The subagent goes silent: no completion event, no heartbeat, and — the
+    // point of the test — no render to piggyback the prune on.
+    const t0 = ctx.window.Date.now();
+    ctx.window.Date.now = () => t0 + 61000;
+    ctx.runScheduled();
+
+    assert.equal(row.classList.contains('running'), false,
+      'the TTL tick must clear the row without waiting for a render');
+    const caret = ctx.document.getElementById('sub-caret-' + PARENT);
+    assert.equal(caret.classList.contains('has-running-child'), false,
+      'the caret badge must follow');
+    assert.equal(ctx.document.getElementById('si-' + PARENT).classList.contains('has-busy-agents'), false,
+      'the parent indicator must follow');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('grid: a stale subagent pill is removed by the TTL tick with no card rebuild', () => {
+  const ctx = setupCombinedDom();
+  try {
+    const element = ctx.document.createElement('div');
+    ctx.window.openSessions.set(PARENT, { closed: false, element, terminal: { focus: () => {} } });
+    ctx.window.sessionMap.set(PARENT, {
+      sessionId: PARENT, name: 'parent session', projectPath: '/home/dev/proj',
+      modified: '2026-05-22T10:00:00.000Z',
+    });
+    ctx.window.wrapInGridCard(PARENT);
+    ctx.emitSubagentSpawned({ parentSessionId: PARENT, agentId: AGENT, subagentType: 'explore' });
+
+    const card = ctx.document.querySelector('.grid-card[data-session-id="' + PARENT + '"]');
+    assert.equal(card.querySelectorAll('.grid-subagent-pill').length, 1, 'the pill renders on spawn');
+    assert.equal(ctx.scheduled.length, 2, 'each view arms its own TTL timer on the spawn');
+    assertArmedAt(ctx, TTL_MS, 'fresh spawn');
+
+    const t0 = ctx.window.Date.now();
+    ctx.window.Date.now = () => t0 + 61000;
+    ctx.runScheduled();
+
+    assert.equal(card.querySelectorAll('.grid-subagent-pill').length, 0,
+      'the TTL tick must clear the pill without waiting for wrapInGridCard');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('the TTL tick re-arms while an agent is live and stops once the map is empty', () => {
+  const ctx = setupCombinedDom();
+  try {
+    ctx.window.renderProjects([sampleProject()], true);
+    ctx.emitSubagentSpawned({ parentSessionId: PARENT, agentId: AGENT, subagentType: 'explore' });
+    assert.equal(ctx.scheduled.length, 2);
+    assertArmedAt(ctx, TTL_MS, 'fresh spawn');
+
+    // Fires while the agent is still within its TTL: nothing to prune, but the
+    // timer must re-arm so the eviction still happens later.
+    ctx.runScheduled();
+    const row = ctx.document.getElementById('si-sub:' + PARENT + ':' + AGENT);
+    assert.ok(row.classList.contains('running'), 'a fresh agent must survive the tick');
+    assert.equal(ctx.scheduled.length, 2, 'the tick must re-arm while an agent is tracked');
+    assertArmedAt(ctx, TTL_MS, 're-arm for an agent still inside its TTL');
+
+    const t0 = ctx.window.Date.now();
+    ctx.window.Date.now = () => t0 + 61000;
+    ctx.runScheduled();
+    assert.equal(row.classList.contains('running'), false);
+    assert.equal(ctx.scheduled.length, 0, 'an empty map must leave no timer running');
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('two agents share one timer per view, re-armed at the survivor\'s own deadline', () => {
+  // Covers the `if (subagentTtlTimer) return;` guard — a second spawn must not
+  // arm a second timer — and proves the re-arm is deadline-driven: after the
+  // older agent is pruned the next wakeup is the *younger* one's remaining TTL,
+  // not a fixed interval.
+  const ctx = setupCombinedDom();
+  try {
+    ctx.window.renderProjects([sampleProject()], true);
+    const t0 = ctx.window.Date.now();
+
+    ctx.emitSubagentSpawned({ parentSessionId: PARENT, agentId: AGENT, subagentType: 'explore' });
+    assert.equal(ctx.scheduled.length, 2, 'one timer per view');
+
+    ctx.window.Date.now = () => t0 + 30000;
+    ctx.emitSubagentSpawned({ parentSessionId: PARENT, agentId: AGENT2, subagentType: 'plan' });
+    assert.equal(ctx.scheduled.length, 2, 'a second agent must not arm a second timer per view');
+    assertArmedAt(ctx, TTL_MS, 'still armed on the older agent');
+
+    // The older agent's deadline: it is pruned, the younger one survives.
+    ctx.window.Date.now = () => t0 + TTL_MS + 1000;
+    ctx.runScheduled();
+
+    assert.equal(ctx.document.getElementById('si-sub:' + PARENT + ':' + AGENT).classList.contains('running'),
+      false, 'the older agent is evicted');
+    assertArmedAt(ctx, 30000 - 1000, "re-armed at the survivor's remaining TTL");
+  } finally {
+    ctx.destroy();
+  }
+});
+
+test('a tick that fires exactly on the deadline still makes progress', () => {
+  // The prune uses a strict `<`, so an entry sitting exactly on the cutoff
+  // survives. The re-arm must still be at least 1ms away: a 0ms delay would
+  // re-fire against an unchanged clock and spin.
+  const ctx = setupCombinedDom();
+  try {
+    ctx.window.renderProjects([sampleProject()], true);
+    const t0 = ctx.window.Date.now();
+    ctx.emitSubagentSpawned({ parentSessionId: PARENT, agentId: AGENT, subagentType: 'explore' });
+
+    ctx.window.Date.now = () => t0 + TTL_MS; // exactly on the cutoff
+    ctx.runScheduled();
+
+    assert.ok(ctx.document.getElementById('si-sub:' + PARENT + ':' + AGENT).classList.contains('running'),
+      'an entry exactly on the cutoff is not stale yet');
+    assertArmedAt(ctx, 1, 'boundary re-arm');
+  } finally {
+    ctx.destroy();
+  }
+});
diff --git a/test/session-transitions.test.js b/test/session-transitions.test.js
index d8258c0a..6362719b 100644
--- a/test/session-transitions.test.js
+++ b/test/session-transitions.test.js
@@ -7,6 +7,14 @@ const path = require('path');
 const sessionTransitions = require('../session-transitions');
 const { detectSubagentTransitions, init } = sessionTransitions;
 
+// detectSubagentTransitions arms the settle tick on every call. These tests
+// drive the scan by hand, so a real 5 s timer would be a phantom that could
+// fire onto an unrelated later test under CI load. Stub it out for the file:
+// nothing here needs setTimeout, and the tick has its own suite.
+const realSetTimeout = globalThis.setTimeout;
+test.before(() => { globalThis.setTimeout = () => ({ unref() {} }); });
+test.after(() => { globalThis.setTimeout = realSetTimeout; });
+
 function mkTmp() {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'switchboard-st-'));
 }
diff --git a/test/subagent-settle-tick.test.js b/test/subagent-settle-tick.test.js
new file mode 100644
index 00000000..8e741aae
--- /dev/null
+++ b/test/subagent-settle-tick.test.js
@@ -0,0 +1,504 @@
+// see .ai/contexts/subagent-observability.md
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { detectSubagentTransitions, init } = require('../session-transitions');
+
+const STABLE_MS = 30000;
+const SETTLE_TICK_MS = 5000;
+const LIVE_RECHECK_MS = 300000;
+const MAX_STABLE_MS = 300000;
+const RENDERER_TTL_MS = 60000;
+const STABLE_LADDER = [STABLE_MS, 120000, MAX_STABLE_MS];
+
+// The settle tick is armed with a bare setTimeout, so a spy on the global is
+// what makes the *arming* observable — asserting on emitted events alone
+// cannot tell a disarmed tick from one that re-arms forever doing nothing.
+const scheduled = [];
+const realSetTimeout = globalThis.setTimeout;
+test.before(() => {
+  globalThis.setTimeout = (fn, ms) => { scheduled.push({ fn, ms }); return { unref() {} }; };
+});
+test.after(() => { globalThis.setTimeout = realSetTimeout; });
+
+/** Run every currently-armed timer once. Callbacks may arm new ones. */
+function fireTimers() {
+  const due = scheduled.splice(0, scheduled.length);
+  for (const { fn } of due) fn();
+}
+
+function mkTmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'switchboard-tick-'));
+}
+
+function setMtime(p, ms) {
+  const t = ms / 1000;
+  fs.utimesSync(p, t, t);
+}
+
+/** Init the module and clear any tick left armed by a previous test — the
+ *  timer handle lives in module scope, so a leftover would block arming. */
+function setup(activeSessions = new Map()) {
+  const events = [];
+  init({
+    PROJECTS_DIR: '/unused',
+    activeSessions,
+    getMainWindow: () => ({
+      isDestroyed: () => false,
+      webContents: { send: (channel, payload) => events.push({ channel, payload, at: Date.now() }) },
+    }),
+    log: { info: () => {}, debug: () => {}, warn: () => {}, error: () => {} },
+    rekeyMcpServer: () => {},
+  });
+  fireTimers();
+  scheduled.length = 0;
+  return events;
+}
+
+/** Re-init with PROJECTS_DIR pointing at tmp so the tick can resolve folders. */
+function setupWithProjectsDir(tmp, activeSessions) {
+  const events = [];
+  init({
+    PROJECTS_DIR: tmp,
+    activeSessions,
+    getMainWindow: () => ({
+      isDestroyed: () => false,
+      webContents: { send: (channel, payload) => events.push({ channel, payload, at: Date.now() }) },
+    }),
+    log: { info: () => {}, debug: () => {}, warn: () => {}, error: () => {} },
+    rekeyMcpServer: () => {},
+  });
+  fireTimers();
+  scheduled.length = 0;
+  return events;
+}
+
+function seedLiveAgent(tmp, sessionId, agentId) {
+  const subDir = path.join(tmp, sessionId, 'subagents');
+  fs.mkdirSync(subDir, { recursive: true });
+  const filePath = path.join(subDir, `agent-${agentId}.jsonl`);
+  fs.writeFileSync(filePath, '', 'utf8');
+  setMtime(filePath, Date.now());
+  setMtime(subDir, Date.now());
+  return filePath;
+}
+
+function grow(filePath) {
+  fs.appendFileSync(filePath, 'x\n', 'utf8');
+  setMtime(filePath, Date.now());
+}
+
+test('a subagent that goes quiet completes without any further watcher flush', (t) => {
+  // Measured 2026-08-23: agent a9be19fb0a7e0e504 stopped writing at 23:42:18
+  // and subagent-completed was only logged at 23:52:55 — the folder went quiet,
+  // so the debounced watcher flush that owns the stability clock never ran.
+  const tmp = mkTmp();
+  const activeSessions = new Map();
+  try {
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    const events = setupWithProjectsDir(tmp, activeSessions);
+
+    const sessionId = 'parent';
+    const session = { projectFolder: '.' };
+    activeSessions.set(sessionId, session);
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+
+    detectSubagentTransitions(sessionId, session, tmp); // bootstrap on empty dir
+    seedLiveAgent(tmp, sessionId, 'quiet');
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(events.filter(e => e.channel === 'subagent-spawned').length, 1, 'spawn announced');
+
+    // From here nothing writes in the folder, so the watcher never fires again.
+    for (let i = 0; i < 10; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+
+    const completions = events.filter(e => e.channel === 'subagent-completed');
+    assert.equal(completions.length, 1,
+      `completion must fire from the settle tick alone, got ${JSON.stringify(events.map(e => e.channel))}`);
+    assert.equal(completions[0].payload.agentId, 'quiet');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('the settle tick disarms itself once nothing is left to watch', (t) => {
+  // Observing events is not enough: a tick that re-armed forever on a settled
+  // session would emit nothing and still be the steady-state cost ADR 0002
+  // forbids. Assert on the armed timer itself.
+  const tmp = mkTmp();
+  const activeSessions = new Map();
+  try {
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    setupWithProjectsDir(tmp, activeSessions);
+
+    const sessionId = 'parent';
+    const session = { projectFolder: '.' };
+    activeSessions.set(sessionId, session);
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+
+    detectSubagentTransitions(sessionId, session, tmp);
+    seedLiveAgent(tmp, sessionId, 'short');
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(scheduled.length, 1, 'a live agent arms the tick');
+
+    // Drive past completion AND past the recheck window that follows it.
+    for (let i = 0; i < 80; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+
+    const known = session.knownSubagents.get('short');
+    assert.equal(known.completed, true, 'the agent must have completed');
+    assert.equal(known._recheckStart, null, 'its recheck window must have closed');
+    assert.equal(scheduled.length, 0,
+      'a fully settled session must leave no timer armed');
+
+    // The sweep has a guard of its own, so draining alone cannot tell whether
+    // arming is guarded too. Call the scan directly on the settled session:
+    // an unguarded armSubagentSettleTick would arm here.
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(scheduled.length, 0,
+      'scanning a settled session must not arm the tick');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('the settle tick closes the recheck window of a completed agent in a silent folder', (t) => {
+  // A completed-but-still-falsifiable entry is not settled: if the tick ignored
+  // it, the window would only ever close on a write to some other file in the
+  // same folder, and in a silent folder it would stay open forever.
+  const tmp = mkTmp();
+  const activeSessions = new Map();
+  try {
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    setupWithProjectsDir(tmp, activeSessions);
+
+    const sessionId = 'parent';
+    const session = { projectFolder: '.' };
+    activeSessions.set(sessionId, session);
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+
+    detectSubagentTransitions(sessionId, session, tmp);
+    seedLiveAgent(tmp, sessionId, 'quiet');
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    // Just past completion: the entry is completed but still falsifiable.
+    for (let i = 0; i < 10; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+    const known = session.knownSubagents.get('quiet');
+    assert.equal(known.completed, true);
+    assert.notEqual(known._recheckStart, null, 'the window must be open right after completion');
+    assert.equal(scheduled.length, 1, 'an open recheck window must keep the tick armed');
+
+    // No watcher event ever arrives; only the tick can close the window.
+    for (let i = 0; i < 70; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+    assert.equal(session.knownSubagents.get('quiet')._recheckStart, null,
+      'the tick alone must close the recheck window');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('a stability completion stays falsifiable well past STABLE_MS', (t) => {
+  // Measured 2026-08-23: agents a8e8c25f42a65b026 and a19dcbbb23270de85 were
+  // both declared complete while still alive. Tool calls routinely outlast
+  // STABLE_MS, so a 30 s recheck window would freeze the entry before the
+  // agent's next write — the window has to be sized to the tool call.
+  const tmp = mkTmp();
+  const events = setup();
+  try {
+    const sessionId = 'parent';
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+    const session = {};
+
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    detectSubagentTransitions(sessionId, session, tmp);
+    const filePath = seedLiveAgent(tmp, sessionId, 'slow');
+    detectSubagentTransitions(sessionId, session, tmp);
+    detectSubagentTransitions(sessionId, session, tmp); // arms _stableStart
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp); // completed
+    assert.equal(events.filter(e => e.channel === 'subagent-completed').length, 1);
+
+    // A pass this far after the completion would close a STABLE_MS-sized window.
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    // The agent was only running a long tool call: it writes again.
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    const spawns = events.filter(e => e.channel === 'subagent-spawned');
+    assert.equal(spawns.length, 2,
+      `the withheld spawn must be re-emitted, got ${JSON.stringify(events.map(e => e.channel))}`);
+    assert.equal(spawns[1].payload._heartbeat, undefined,
+      'a re-announcement must be a real spawn, not a heartbeat the renderer would ignore');
+    assert.equal(session.knownSubagents.get('slow').completed, false);
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('the recheck window closes after LIVE_RECHECK_MS and the entry freezes', (t) => {
+  // The window is generous, not unbounded: past it the entry goes back to the
+  // zero-cost fast path and a later write can no longer resurrect it.
+  const tmp = mkTmp();
+  const events = setup();
+  try {
+    const sessionId = 'parent';
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+    const session = {};
+
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    detectSubagentTransitions(sessionId, session, tmp);
+    const filePath = seedLiveAgent(tmp, sessionId, 'slow');
+    detectSubagentTransitions(sessionId, session, tmp);
+    detectSubagentTransitions(sessionId, session, tmp);
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp); // completed
+    const spawnsAtCompletion = events.filter(e => e.channel === 'subagent-spawned').length;
+
+    t.mock.timers.tick(LIVE_RECHECK_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(session.knownSubagents.get('slow')._recheckStart, null,
+      'the window must close once LIVE_RECHECK_MS has elapsed');
+
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(events.filter(e => e.channel === 'subagent-spawned').length, spawnsAtCompletion,
+      'a frozen entry must not be re-announced');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('an agent that never oscillates keeps the plain STABLE_MS window', (t) => {
+  // The escalation must not slow down the normal case: only undoing a stability
+  // verdict widens the window.
+  const tmp = mkTmp();
+  const events = setup();
+  try {
+    const sessionId = 'parent';
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+    const session = {};
+
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    detectSubagentTransitions(sessionId, session, tmp);
+    seedLiveAgent(tmp, sessionId, 'plain');
+    detectSubagentTransitions(sessionId, session, tmp);
+    detectSubagentTransitions(sessionId, session, tmp); // arms _stableStart
+
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    assert.equal(events.filter(e => e.channel === 'subagent-completed').length, 1,
+      'a first silence of STABLE_MS must still complete the agent');
+    assert.ok(!session.knownSubagents.get('plain')._stableMs,
+      'an agent that was never rehabilitated must carry no widened window');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('the stability window widens on each rehabilitation and converges on MAX_STABLE_MS', (t) => {
+  // Maintainer's call on the oscillation: an agent that has already gone quiet
+  // for a long time is an agent whose silences are long, so widen its window
+  // instead of blinking at it. Bounded, and capped by name.
+  const tmp = mkTmp();
+  const events = setup();
+  try {
+    const sessionId = 'parent';
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+    const session = {};
+
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    detectSubagentTransitions(sessionId, session, tmp);
+    const filePath = seedLiveAgent(tmp, sessionId, 'flaky');
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    const known = () => session.knownSubagents.get('flaky');
+    const completions = () => events.filter(e => e.channel === 'subagent-completed').length;
+
+    // Cycle 1 — the window is still the plain STABLE_MS.
+    detectSubagentTransitions(sessionId, session, tmp);
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(completions(), 1, 'first silence completes at STABLE_MS');
+    t.mock.timers.tick(1000);
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(known()._stableMs, STABLE_LADDER[1], 'the window widens after the first rehabilitation');
+
+    // Cycle 2 — the same STABLE_MS silence must no longer be enough.
+    detectSubagentTransitions(sessionId, session, tmp);
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(completions(), 1, 'a widened window must not complete on a short silence');
+    t.mock.timers.tick(STABLE_LADDER[1]);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(completions(), 2, 'it completes once the widened window elapses');
+    t.mock.timers.tick(1000);
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(known()._stableMs, MAX_STABLE_MS, 'the second rehabilitation reaches the cap');
+
+    // Cycle 3 — the cap holds instead of growing further.
+    detectSubagentTransitions(sessionId, session, tmp);
+    t.mock.timers.tick(MAX_STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(completions(), 3);
+    t.mock.timers.tick(1000);
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.equal(known()._stableMs, MAX_STABLE_MS, 'the window converges, it does not keep growing');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('a silence longer than the renderer TTL is re-announced, not heartbeaten', (t) => {
+  // Companion to the widening: past RENDERER_TTL_MS the renderer has certainly
+  // pruned the entry, and it refuses heartbeats for agents it does not track.
+  // Without this the widened window would trade a blink for a permanent
+  // blackout — the very bug this branch fixes.
+  const tmp = mkTmp();
+  const events = setup();
+  try {
+    const sessionId = 'parent';
+    fs.mkdirSync(path.join(tmp, sessionId, 'subagents'), { recursive: true });
+    const session = {};
+
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    detectSubagentTransitions(sessionId, session, tmp);
+    const filePath = seedLiveAgent(tmp, sessionId, 'slow');
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    // Widen the window once so the agent can stay silent past the renderer TTL
+    // without being completed.
+    detectSubagentTransitions(sessionId, session, tmp);
+    t.mock.timers.tick(STABLE_MS + 1000);
+    detectSubagentTransitions(sessionId, session, tmp);
+    t.mock.timers.tick(1000);
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    const before = events.length;
+    t.mock.timers.tick(RENDERER_TTL_MS + 5000);
+    grow(filePath);
+    detectSubagentTransitions(sessionId, session, tmp);
+
+    const emitted = events.slice(before);
+    assert.equal(emitted.length, 1, `expected one emission, got ${JSON.stringify(emitted.map(e => e.channel))}`);
+    assert.equal(emitted[0].channel, 'subagent-spawned');
+    assert.equal(emitted[0].payload._heartbeat, undefined,
+      'past the renderer TTL the emission must be a real spawn the renderer will accept');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+/** Seed a file that already exists when the session is first scanned, aged by
+ *  `ageMs` — the shape PR #147's ghost had: written moments before a restart. */
+function seedPreexistingAgent(tmp, sessionId, agentId, ageMs) {
+  const subDir = path.join(tmp, sessionId, 'subagents');
+  fs.mkdirSync(subDir, { recursive: true });
+  const filePath = path.join(subDir, `agent-${agentId}.jsonl`);
+  fs.writeFileSync(filePath, '', 'utf8');
+  setMtime(filePath, Date.now() - ageMs);
+  setMtime(subDir, Date.now() - ageMs);
+  return filePath;
+}
+
+test('the settle tick does not resurrect the bootstrap ghost (PR #147)', (t) => {
+  // PR #147: a subagent that finished shortly before a restart used to come back
+  // as live. This branch adds a clock that rescans on its own, and the predicate
+  // that arms it now counts completed-but-still-falsifiable entries — which is
+  // exactly what bootstrap leaves behind for a recent file. Drive the tick past
+  // the window and assert the ghost stays buried.
+  const tmp = mkTmp();
+  const activeSessions = new Map();
+  try {
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    const events = setupWithProjectsDir(tmp, activeSessions);
+
+    const sessionId = 'parent';
+    const session = { projectFolder: '.' };
+    activeSessions.set(sessionId, session);
+    const filePath = seedPreexistingAgent(tmp, sessionId, 'ghost', 5000);
+
+    detectSubagentTransitions(sessionId, session, tmp); // bootstrap
+    assert.equal(events.length, 0, 'bootstrap is silent');
+    const known = () => session.knownSubagents.get('ghost');
+    assert.equal(known().completed, true, 'a pre-existing file is recorded as finished');
+    assert.notEqual(known()._recheckStart, null, 'a recent one keeps a recheck window');
+    assert.equal(scheduled.length, 1, 'that window is what arms the tick');
+
+    // Let the tick run on its own, past the close of the recheck window.
+    for (let i = 0; i < 20; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+
+    assert.deepEqual(events, [],
+      `the tick must never announce a bootstrap file, got ${JSON.stringify(events.map(e => e.channel))}`);
+    assert.equal(known()._recheckStart, null, 'the window closed');
+    assert.equal(known().completed, true, 'and the entry stayed finished');
+    assert.equal(scheduled.length, 0, 'a frozen entry leaves no timer armed');
+
+    // Frozen for good: growth after the window can no longer wake it.
+    grow(filePath);
+    for (let i = 0; i < 10; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+    detectSubagentTransitions(sessionId, session, tmp);
+    assert.deepEqual(events, [], 'a closed window never reopens');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('the settle tick still rehabilitates a bootstrap file that grows in its window', (t) => {
+  // The silence above must not have been bought by breaking the falsifiability
+  // #147 deliberately kept: an orphaned writer that survived a hard kill has to
+  // announce itself late rather than stay invisible for the whole session.
+  const tmp = mkTmp();
+  const activeSessions = new Map();
+  try {
+    t.mock.timers.enable({ apis: ['Date'], now: Date.now() });
+    const events = setupWithProjectsDir(tmp, activeSessions);
+
+    const sessionId = 'parent';
+    const session = { projectFolder: '.' };
+    activeSessions.set(sessionId, session);
+    const filePath = seedPreexistingAgent(tmp, sessionId, 'survivor', 5000);
+
+    detectSubagentTransitions(sessionId, session, tmp); // bootstrap
+    assert.equal(events.length, 0, 'bootstrap is silent');
+
+    // Still inside the recheck window, and it is still being written.
+    t.mock.timers.tick(SETTLE_TICK_MS);
+    fireTimers();
+    grow(filePath);
+    t.mock.timers.tick(SETTLE_TICK_MS);
+    fireTimers();
+
+    const spawns = events.filter(e => e.channel === 'subagent-spawned');
+    assert.equal(spawns.length, 1,
+      `the tick must emit the withheld spawn exactly once, got ${JSON.stringify(events.map(e => e.channel))}`);
+    assert.equal(spawns[0].payload.agentId, 'survivor');
+    assert.equal(spawns[0].payload._heartbeat, undefined, 'it is a spawn, not a heartbeat');
+    assert.equal(session.knownSubagents.get('survivor').completed, false, 'the assumption is undone');
+
+    // It goes quiet again — one late spawn, never a repeated one.
+    for (let i = 0; i < 20; i++) { t.mock.timers.tick(SETTLE_TICK_MS); fireTimers(); }
+    assert.equal(events.filter(e => e.channel === 'subagent-spawned').length, 1,
+      'the late spawn is announced once, not on every tick');
+  } finally {
+    t.mock.timers.reset();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
diff --git a/test/terminal-manager-harness.js b/test/terminal-manager-harness.js
index ea176304..e29a879c 100644
--- a/test/terminal-manager-harness.js
+++ b/test/terminal-manager-harness.js
@@ -159,7 +159,7 @@ function setupTerminalDom(opts = {}) {
   // lexical scope — it shadows the window stub, exactly as in production where
   // grid-view.js owns that global. Tests must read grid state via inCtx().
   const ctx = dom.getInternalVMContext();
-  for (const file of ['utils.js', 'shortcuts.js', 'terminal-context-menu.js', 'terminal-manager.js', 'grid-view.js']) {
+  for (const file of ['utils.js', 'shortcuts.js', 'subagent-timing.js', 'terminal-context-menu.js', 'terminal-manager.js', 'grid-view.js']) {
     const src = fs.readFileSync(path.join(PUBLIC_DIR, file), 'utf8');
     vm.runInContext(src, ctx, { filename: file });
   }
diff --git a/test/terminal-manager-lifecycle.test.js b/test/terminal-manager-lifecycle.test.js
index 12cc508d..5047d02e 100644
--- a/test/terminal-manager-lifecycle.test.js
+++ b/test/terminal-manager-lifecycle.test.js
@@ -533,7 +533,7 @@ test('safeFit: clamps rows to content box when cell height is available via _cor
   const fs2 = require('node:fs');
   const path2 = require('node:path');
   const vm2 = require('node:vm');
-  for (const file of ['utils.js', 'shortcuts.js', 'terminal-context-menu.js', 'terminal-manager.js', 'grid-view.js']) {
+  for (const file of ['utils.js', 'shortcuts.js', 'subagent-timing.js', 'terminal-context-menu.js', 'terminal-manager.js', 'grid-view.js']) {
     const src = fs2.readFileSync(path2.join(PUBLIC_DIR, file), 'utf8');
     vm2.runInContext(src, ctx, { filename: file });
   }