switchroom 0.17.6 → 0.18.3

package/telegram-plugin/tests/silent-turn-climb-transport.test.ts

@@ -0,0 +1,337 @@
+/**
+ * Outcome-based regression test for the deterministic silent-turn card climb.
+ *
+ * Phase 4(b) of `reference/rfcs/deterministic-turn-liveness.md`; serves
+ * `reference/jobs/know-what-my-agent-is-doing.md` (a busy-but-silent turn must
+ * visibly escalate, never freeze).
+ *
+ * ## What is REAL here, and what is a spy (no overclaim)
+ *
+ * The gateway is a start-on-import IIFE that cannot be instantiated in-process
+ * (the documented constraint behind every `*-wiring` structural test in this
+ * suite). So the shipped 0-label tick body was EXTRACTED into
+ * `feed-heartbeat-climb.ts` (`runSilentTurnHeartbeatTick`) and the gateway's
+ * `feedHeartbeatTick` calls it with its real deps — meaning the function under
+ * test IS the production decision logic, byte-for-byte, not a hand-copied
+ * mirror. What this test drives:
+ *
+ *   - REAL: `runSilentTurnHeartbeatTick` + `silentTurnClimbRender` — the shipped
+ *     guard placement (0-label check, open-vs-climb split, stale-guard, null
+ *     render), the gate SEQUENCE (cardDrainGate → mayDrain → openOrEditCard →
+ *     drain), and the rendered card bodies.
+ *   - SPY: the injected deps. The `drain` seam is where the gateway's
+ *     `drainActivitySummary` → `robustApiCall(bot.api.sendMessage /
+ *     bot.api.editMessageText)` lives in production; the spy implements the
+ *     drain's transport contract (send when no card id, edit once set) and
+ *     records every call with a timestamp. The real `drainActivitySummary` /
+ *     grammY transport is NOT executed here — the gateway wiring of the real
+ *     deps (and the real drain call) is pinned structurally by
+ *     `tests/feed-heartbeat-liveness-open.test.ts`, and end-to-end by the UAT
+ *     liveness scenarios.
+ *
+ * ## What it asserts
+ *
+ *   1. A ~40s silent tool call produces >=4 card EDITS with a CLIMBING elapsed —
+ *      the card never freezes. (Acceptance criterion of the RFC.)
+ *   2. Every climb mutation is an EDIT of the already-open card — never a new
+ *      send — so no mid-turn mutation can push-notify the device.
+ *   3. Each climb edit passes through the full gate sequence in order:
+ *      setPendingRender → cardDrainGate → mayDrain → openOrEditCard → drain
+ *      (mis-wiring the guards inside the tick body fails this).
+ *   4. `mayDrain === false` (drain in flight) suppresses the edit — the
+ *      single-flight guard is honoured.
+ *   5. The climb yields to model narration: a surfaced tool label
+ *      (`mirrorLineCount > 0`) returns `false` (labelled branch owns the tick)
+ *      and emits nothing.
+ *   6. The stale-guard: a turn younger than `minStaleMs` produces no edit (same
+ *      symmetry the labelled branch has).
+ *
+ * ## Why this FAILS on pre-fix code (its acceptance criterion)
+ *
+ * Pre-fix, the 0-label branch delegated solely to `openLivenessFeedIfDue`,
+ * whose WHEN-gate returns false the moment a card is open — an open 0-label
+ * card received ZERO edits during a silent tool. Reverting
+ * `runSilentTurnHeartbeatTick` to that behaviour (the open-path delegate with
+ * no climb) drives this test's edit count to 0, failing assertion 1 — through
+ * the same shipped function the gateway calls. Removing the gateway call site
+ * instead is caught by the structural pin in
+ * `tests/feed-heartbeat-liveness-open.test.ts`.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  runSilentTurnHeartbeatTick,
+  silentTurnClimbRender,
+  type SilentTurnTickDeps,
+} from '../feed-heartbeat-climb.js'
+
+// The gateway constants that drive the tick cadence (gateway.ts).
+const FEED_HEARTBEAT_TICK_MS = 6_000
+const FEED_HEARTBEAT_MIN_STALE_MS = 6_000
+const FEED_LIVENESS_OPEN_MS = 1_200
+
+/** A recorded transport call with the simulated wall-clock time it happened at. */
+interface TransportCall {
+  kind: 'sendMessage' | 'editMessageText'
+  at: number
+  text: string
+}
+
+/** Parse the climbing elapsed (in seconds) out of a rendered card header line
+ *  (`_6s · 0 tools_`, `_1m05s · 0 tools_`). Returns null if not present. */
+function parseHeaderElapsedSeconds(text: string): number | null {
+  const m = text.match(/_((?:(\d+)m)?(\d+)s) · \d+ tools?_/)
+  if (m == null) return null
+  const minutes = m[2] ? Number(m[2]) : 0
+  const seconds = Number(m[3])
+  return minutes * 60 + seconds
+}
+
+/**
+ * Test double for the turn's card surface + injected deps. The `drain` spy
+ * implements the drain's transport contract — `sendMessage` (an OPEN, the only
+ * mutation that push-notifies) when no card id exists, `editMessageText` (a
+ * silent card EDIT) once it does — standing in for `drainActivitySummary` →
+ * `robustApiCall(bot.api.*)`. Also records the gate-call ORDER per tick so the
+ * shipped sequence is pinned, and simulates the shared OPEN path
+ * (`openLivenessFeedIfDue`) opening the placeholder card.
+ */
+class TurnHarness {
+  calls: TransportCall[] = []
+  order: string[] = []
+  activityMessageId: number | null = null
+  pendingRender: string | null = null
+  mayDrainResult = true
+  private nextId = 100
+  now = 0
+
+  /** The real gateway wires these exact seams; each spy records its call. */
+  deps(openRender: () => string | null): SilentTurnTickDeps {
+    return {
+      openLivenessFeedIfDue: () => {
+        this.order.push('openLivenessFeedIfDue')
+        // Mirror of the shared OPEN path's contract: opens once, past its
+        // threshold, via a fresh sendMessage.
+        if (this.activityMessageId != null) return
+        const rendered = openRender()
+        if (rendered == null) return
+        this.activityMessageId = this.nextId++
+        this.calls.push({ kind: 'sendMessage', at: this.now, text: rendered })
+      },
+      setPendingRender: (rendered) => {
+        this.order.push('setPendingRender')
+        this.pendingRender = rendered
+      },
+      cardDrainGate: (run) => {
+        this.order.push('cardDrainGate')
+        run()
+      },
+      mayDrain: () => {
+        this.order.push('mayDrain')
+        return this.mayDrainResult
+      },
+      openOrEditCard: (apply) => {
+        this.order.push('openOrEditCard')
+        apply()
+      },
+      drain: () => {
+        this.order.push('drain')
+        // drainActivitySummary's transport contract: OPEN when no card id,
+        // EDIT in place once set. Here the card is always open (the tick only
+        // reaches drain via the climb), so this is always an edit.
+        const text = this.pendingRender ?? ''
+        if (this.activityMessageId == null) {
+          this.activityMessageId = this.nextId++
+          this.calls.push({ kind: 'sendMessage', at: this.now, text })
+        } else {
+          this.calls.push({ kind: 'editMessageText', at: this.now, text })
+        }
+      },
+    }
+  }
+
+  get sends(): TransportCall[] {
+    return this.calls.filter((c) => c.kind === 'sendMessage')
+  }
+  get edits(): TransportCall[] {
+    return this.calls.filter((c) => c.kind === 'editMessageText')
+  }
+}
+
+/** Drive the REAL tick across a silent window, the way the gateway's 6s
+ *  setInterval does: same view fields, real deps thunks. */
+function runSilentWindow(harness: TurnHarness, turnStart: number, windowMs: number): void {
+  const deps = harness.deps(() => 'placeholder')
+  for (let now = turnStart; now <= turnStart + windowMs; now += FEED_HEARTBEAT_TICK_MS) {
+    harness.now = now
+    const handled = runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: 0,
+        activityMessageId: harness.activityMessageId,
+        labeledToolCount: 0,
+        ageMs: now - turnStart,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      deps,
+    )
+    expect(handled).toBe(true) // 0-label turn: this branch owns every tick
+  }
+}
+
+describe('deterministic silent-turn card climb — real tick against a spy transport', () => {
+  it('a ~40s silent tool call yields >=4 card edits with climbing elapsed (never freezes)', () => {
+    const harness = new TurnHarness()
+    const turnStart = 1_000_000 // arbitrary simulated epoch
+    // Pre-open the card the way production does (early open ~1.2s in via the
+    // shared OPEN path) — the freeze reproduced specifically on an OPEN card.
+    harness.now = turnStart + FEED_LIVENESS_OPEN_MS
+    harness.deps(() => 'placeholder').openLivenessFeedIfDue()
+    expect(harness.activityMessageId).not.toBeNull()
+
+    runSilentWindow(harness, turnStart, 40_000)
+
+    // Exactly one OPEN (the pre-opened card) — the climb never sends.
+    expect(harness.sends.length).toBe(1)
+
+    // The acceptance criterion: the card is EDITED at least 4 times across the gap.
+    expect(
+      harness.edits.length,
+      `expected >=4 climbing card edits across a 40s silent tool, got ${harness.edits.length} ` +
+        `(pre-fix code freezes the 0-label card and produces 0 edits)`,
+    ).toBeGreaterThanOrEqual(4)
+
+    // The elapsed on each successive edit strictly climbs — no frozen counter.
+    const elapsedSeries = harness.edits
+      .map((c) => parseHeaderElapsedSeconds(c.text))
+      .filter((n): n is number => n != null)
+    expect(elapsedSeries.length).toBe(harness.edits.length)
+    for (let i = 1; i < elapsedSeries.length; i++) {
+      expect(
+        elapsedSeries[i],
+        `card elapsed must climb: edit[${i}]=${elapsedSeries[i]}s not > edit[${i - 1}]=${elapsedSeries[i - 1]}s`,
+      ).toBeGreaterThan(elapsedSeries[i - 1])
+    }
+
+    // Worst-case visible-update gap stays within ~two tick windows (RFC bound).
+    const editTimes = [harness.sends[0].at, ...harness.edits.map((c) => c.at)]
+    for (let i = 1; i < editTimes.length; i++) {
+      expect(editTimes[i] - editTimes[i - 1]).toBeLessThanOrEqual(2 * FEED_HEARTBEAT_TICK_MS)
+    }
+  })
+
+  it('every climb mutation is an editMessageText, never a new sendMessage (edits do not push-notify)', () => {
+    const harness = new TurnHarness()
+    const turnStart = 2_000_000
+    harness.now = turnStart + FEED_LIVENESS_OPEN_MS
+    harness.deps(() => 'placeholder').openLivenessFeedIfDue()
+    runSilentWindow(harness, turnStart, 40_000)
+
+    expect(harness.calls[0].kind).toBe('sendMessage')
+    for (const call of harness.calls.slice(1)) {
+      expect(call.kind).toBe('editMessageText')
+    }
+  })
+
+  it('each climb edit passes the full shipped gate sequence in order (pendingRender → cardDrainGate → mayDrain → openOrEditCard → drain)', () => {
+    const harness = new TurnHarness()
+    harness.activityMessageId = 55 // card already open
+    harness.now = 12_000
+    runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: 0,
+        activityMessageId: harness.activityMessageId,
+        labeledToolCount: 0,
+        ageMs: 12_000,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      harness.deps(() => null),
+    )
+    expect(harness.order).toEqual([
+      'setPendingRender',
+      'cardDrainGate',
+      'mayDrain',
+      'openOrEditCard',
+      'drain',
+    ])
+  })
+
+  it('a drain already in flight (mayDrain=false) suppresses the edit — single-flight honoured', () => {
+    const harness = new TurnHarness()
+    harness.activityMessageId = 55
+    harness.mayDrainResult = false
+    harness.now = 12_000
+    runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: 0,
+        activityMessageId: 55,
+        labeledToolCount: 0,
+        ageMs: 12_000,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      harness.deps(() => null),
+    )
+    expect(harness.edits.length).toBe(0)
+    // The gate was consulted, then the drain was NOT reached.
+    expect(harness.order).toContain('mayDrain')
+    expect(harness.order).not.toContain('drain')
+  })
+
+  it('the climb yields to model narration (a surfaced tool label hands the tick to the labelled branch)', () => {
+    const harness = new TurnHarness()
+    harness.activityMessageId = 55
+    const handled = runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: 3, // narration / tool labels surfaced
+        activityMessageId: 55,
+        labeledToolCount: 2,
+        ageMs: 30_000,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      harness.deps(() => null),
+    )
+    expect(handled).toBe(false) // labelled branch owns the tick
+    expect(harness.calls.length).toBe(0)
+    expect(harness.order.length).toBe(0)
+  })
+
+  it('the stale-guard: a turn younger than minStaleMs produces no climb edit (labelled-branch symmetry)', () => {
+    const harness = new TurnHarness()
+    harness.activityMessageId = 55
+    const handled = runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: 0,
+        activityMessageId: 55,
+        labeledToolCount: 0,
+        ageMs: FEED_HEARTBEAT_MIN_STALE_MS - 1,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      harness.deps(() => null),
+    )
+    expect(handled).toBe(true) // still the 0-label branch's tick
+    expect(harness.calls.length).toBe(0)
+  })
+
+  it('the climb does not OPEN a card — no card yet delegates to the one shared OPEN path', () => {
+    const harness = new TurnHarness()
+    harness.now = 20_000
+    runSilentTurnHeartbeatTick(
+      {
+        mirrorLineCount: 0,
+        activityMessageId: null,
+        labeledToolCount: 0,
+        ageMs: 20_000,
+        minStaleMs: FEED_HEARTBEAT_MIN_STALE_MS,
+      },
+      harness.deps(() => 'open-render'),
+    )
+    // Delegated to openLivenessFeedIfDue; nothing else ran.
+    expect(harness.order).toEqual(['openLivenessFeedIfDue'])
+    expect(harness.sends.length).toBe(1) // the OPEN path opened it
+    expect(harness.edits.length).toBe(0)
+  })
+
+  it('silentTurnClimbRender refuses when no card is open (opening is reply-is-last gated elsewhere)', () => {
+    expect(
+      silentTurnClimbRender({ mirrorLineCount: 0, activityMessageId: null, labeledToolCount: 0, ageMs: 30_000 }),
+    ).toBeNull()
+  })
+})

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -1296,6 +1296,145 @@ describe('startSubagentWatcher', () => {
     })
   })
 
+  // ─── deterministic-turn-liveness.md Known-Gap 2 — worktree-isolated sub-agents ──
+
+  describe('worktree-isolated sub-agent visibility (turn-liveness Known Gap 2)', () => {
+    /**
+     * A sub-agent dispatched with `switchroom worktree claim` runs under a
+     * different cwd than the parent agent, so Claude Code mints a
+     * *different* `.claude/projects/<slug>/` tree for it. Pre-fix, the
+     * #1116 foreign-slug filter above skips that slug forever — no
+     * activity stamp, no `🛠 Worker` feed, for the whole worktree worker's
+     * run. `extraWatchCwdsProvider` closes that gap: any cwd it returns is
+     * treated as a first-class watched slug, same as `agentCwd`.
+     */
+
+    let tmpRoot = ''
+    const startedWatchers: Array<{ stop(): void }> = []
+
+    beforeEach(() => {
+      tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-watcher-worktree-gap2-'))
+    })
+
+    afterEach(() => {
+      while (startedWatchers.length) {
+        try { startedWatchers.pop()?.stop() } catch { /* ignore */ }
+      }
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+    })
+
+    function startWatcherSync(opts: {
+      agentDir: string
+      agentCwd?: string
+      extraWatchCwdsProvider?: () => string[]
+    }): {
+      logs: string[]
+      poll: () => void
+      watcher: ReturnType<typeof startSubagentWatcher>
+    } {
+      const logs: string[] = []
+      const intervals: Array<{ fn: () => void; ref: number }> = []
+      let nextRef = 1
+      const watcher = startSubagentWatcher({
+        agentDir: opts.agentDir,
+        ...(opts.agentCwd !== undefined ? { agentCwd: opts.agentCwd } : {}),
+        ...(opts.extraWatchCwdsProvider !== undefined
+          ? { extraWatchCwdsProvider: opts.extraWatchCwdsProvider }
+          : {}),
+        stallThresholdMs: 60_000,
+        rescanMs: 500,
+        now: () => Date.now(),
+        setInterval: (fn) => {
+          const ref = nextRef++
+          intervals.push({ fn, ref })
+          return { ref }
+        },
+        clearInterval: () => {},
+        setTimeout: () => ({ ref: 0 }),
+        clearTimeout: () => {},
+        log: (msg) => logs.push(msg),
+      })
+      startedWatchers.push(watcher)
+      return { logs, poll: () => intervals[0]?.fn(), watcher }
+    }
+
+    it('watches a worktree-isolated cwd slug returned by extraWatchCwdsProvider', () => {
+      const agentDir = join(tmpRoot, 'agent')
+      const agentCwd = '/home/test/agent-own'
+      const worktreeCwd = '/home/test/.switchroom/worktrees/wt-abc123'
+      const ownSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-own', 'sess-A', 'subagents')
+      const worktreeSlug = join(
+        agentDir,
+        '.claude',
+        'projects',
+        '-home-test--switchroom-worktrees-wt-abc123',
+        'sess-B',
+        'subagents',
+      )
+      mkdirSync(ownSubagents, { recursive: true })
+      mkdirSync(worktreeSlug, { recursive: true })
+      writeFileSync(
+        join(ownSubagents, 'agent-ownworker.jsonl'),
+        buildJSONL(subAgentUserMsg('legit work')),
+      )
+      writeFileSync(
+        join(worktreeSlug, 'agent-worktreeworker.jsonl'),
+        buildJSONL(subAgentUserMsg('worktree-isolated work')),
+      )
+
+      // Pre-fix acceptance: without extraWatchCwdsProvider, the worktree
+      // slug is a "foreign" slug per #1116 and is skipped — this is the
+      // regression this test guards against.
+      const preFix = startWatcherSync({ agentDir, agentCwd })
+      preFix.poll()
+      expect(preFix.watcher.getRegistry().has('worktreeworker')).toBe(false)
+      preFix.watcher.stop()
+
+      const h = startWatcherSync({
+        agentDir,
+        agentCwd,
+        extraWatchCwdsProvider: () => [worktreeCwd],
+      })
+      h.poll()
+
+      const reg = h.watcher.getRegistry()
+      expect(reg.has('ownworker')).toBe(true)
+      expect(reg.has('worktreeworker')).toBe(true)
+    })
+
+    it('still skips a genuinely foreign project dir not returned by extraWatchCwdsProvider', () => {
+      const agentDir = join(tmpRoot, 'agent')
+      const agentCwd = '/home/test/agent-own'
+      const worktreeCwd = '/home/test/.switchroom/worktrees/wt-abc123'
+      const ownSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-own', 'sess-A', 'subagents')
+      const foreignSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-foreign', 'sess-C', 'subagents')
+      mkdirSync(ownSubagents, { recursive: true })
+      mkdirSync(foreignSubagents, { recursive: true })
+      writeFileSync(
+        join(ownSubagents, 'agent-ownworker.jsonl'),
+        buildJSONL(subAgentUserMsg('legit work')),
+      )
+      writeFileSync(
+        join(foreignSubagents, 'agent-foreignworker.jsonl'),
+        buildJSONL(subAgentUserMsg('a sibling agent, not a registered worktree')),
+      )
+
+      const h = startWatcherSync({
+        agentDir,
+        agentCwd,
+        // Registers a worktree cwd that is NOT the foreign dir above —
+        // proves extraWatchCwdsProvider adds only what it explicitly
+        // names, never a wildcard.
+        extraWatchCwdsProvider: () => [worktreeCwd],
+      })
+      h.poll()
+
+      const reg = h.watcher.getRegistry()
+      expect(reg.has('ownworker')).toBe(true)
+      expect(reg.has('foreignworker')).toBe(false)
+    })
+  })
+
   describe('issue #1116 — terminal cleanup must not re-fire completion (Bug B)', () => {
     /**
      * Pre-#1116: after `TERMINAL_CLEANUP_GRACE_MS` (30s) elapsed,

package/telegram-plugin/tests/telegram-activity-visibility-integration.test.ts

@@ -40,7 +40,12 @@ import { describe, it, expect } from 'vitest'
 import * as realFs from 'fs'
 import { startSubagentWatcher } from '../subagent-watcher.js'
 import { mayOpenActivityCard } from '../gateway/feed-open-gate.js'
-import { clipNarrative, appendActivityLabel } from '../tool-activity-summary.js'
+import {
+  clipNarrative,
+  appendActivityLabel,
+  renderActivityFeedWithNested,
+  formatStepSuffix,
+} from '../tool-activity-summary.js'
 import { evaluatePostAnswerLiveness } from '../turn-liveness-floor.js'
 import {
   createWorkerActivityFeed,
@@ -249,6 +254,7 @@ describe('Fix 2: post-answer background-agent liveness (watcher → gate → liv
       finalAnswerDeliveredAt: currentTurn!.finalAnswerDeliveredAt,
       now: currentTime + 5, // a heartbeat tick moments after the stamp
       staleCapMs: 30_000,
+      stillDispatched: false,
     })
     expect(verdictInWindow).toBe('emit')
   })
@@ -262,6 +268,7 @@ describe('Fix 2: post-answer background-agent liveness (watcher → gate → liv
       finalAnswerDeliveredAt: 1000,
       now: 50_000,
       staleCapMs: 30_000,
+      stillDispatched: false,
     })
     expect(verdict).toBe('idle')
   })
@@ -273,6 +280,7 @@ describe('Fix 2: post-answer background-agent liveness (watcher → gate → liv
         finalAnswerDeliveredAt: 1000,
         now: 1500,
         staleCapMs: 30_000,
+        stillDispatched: false,
       }),
     ).toBe('idle')
   })
@@ -310,9 +318,14 @@ describe('Fix 2 / concern 2: currentTurn nulls at turn_end → heartbeat path in
 
   // The gateway's feedHeartbeatTick post-answer entry, reduced to its decision:
   // `if (turn == null) return` (no-turn), else the REAL evaluatePostAnswerLiveness.
+  // `stillDispatched` defaults to false (a purely-background worker, no
+  // foreground `turn.foregroundSubAgents` tracking) so these existing tests
+  // keep proving the ORIGINAL staleness-cap behaviour is preserved for that
+  // case; a dedicated Fix-3 describe block below covers `stillDispatched: true`.
   function heartbeatVerdict(
     currentTurn: { finalAnswerDelivered: boolean; finalAnswerDeliveredAt?: number; subagentActivityAt?: number } | null,
     now: number,
+    stillDispatched = false,
   ): 'no-turn' | 'pre-answer' | ReturnType<typeof evaluatePostAnswerLiveness> {
     const turn = currentTurn
     if (turn == null) return 'no-turn' // gateway: `if (turn == null) return`
@@ -322,6 +335,7 @@ describe('Fix 2 / concern 2: currentTurn nulls at turn_end → heartbeat path in
       finalAnswerDeliveredAt: turn.finalAnswerDeliveredAt,
       now,
       staleCapMs: 30_000,
+      stillDispatched,
     })
   }
 
@@ -377,6 +391,146 @@ describe('Fix 2 / concern 2: currentTurn nulls at turn_end → heartbeat path in
   })
 })
 
+// ─── Fix 3 — sub-agent-delegation freeze (operator-confirmed: card frozen on
+//     "Running a command" for 41s / 3m12s while a sub-agent ran underneath) ──
+
+describe('Fix 3: a still-tracked foreground sub-agent bypasses the staleness cap (no mid-delegation freeze)', () => {
+  /**
+   * Reproduces the EXACT scenario the operator's 3 screenshots showed: a
+   * foreground `Task`/`Agent` dispatch is still outstanding (one long silent
+   * step — no new watcher narrative tick), so `subagentActivityAt` stops
+   * advancing, yet the worker has NOT reported finished. Before Fix 3 the
+   * staleness cap could not tell this apart from genuine completion and froze
+   * the card after 30s regardless. `stillDispatched: true` — sourced from
+   * `turn.foregroundSubAgents.size > 0` at the real call site — is the
+   * positive signal that closes the gap.
+   */
+
+  // Local copy of the gateway's post-answer decision (same as the "Fix 2 /
+  // concern 2" describe block above — duplicated here rather than hoisted to
+  // module scope so each describe stays self-contained/readable).
+  function heartbeatVerdict(
+    currentTurn: { finalAnswerDelivered: boolean; finalAnswerDeliveredAt?: number; subagentActivityAt?: number } | null,
+    now: number,
+    stillDispatched = false,
+  ): 'no-turn' | 'pre-answer' | ReturnType<typeof evaluatePostAnswerLiveness> {
+    const turn = currentTurn
+    if (turn == null) return 'no-turn'
+    if (!turn.finalAnswerDelivered) return 'pre-answer'
+    return evaluatePostAnswerLiveness({
+      subagentActivityAt: turn.subagentActivityAt,
+      finalAnswerDeliveredAt: turn.finalAnswerDeliveredAt,
+      now,
+      staleCapMs: 30_000,
+      stillDispatched,
+    })
+  }
+
+  it('long silent single step (41s, no new narrative) — bypasses the cap while still dispatched', () => {
+    const turn = {
+      finalAnswerDelivered: true,
+      finalAnswerDeliveredAt: 1000,
+      subagentActivityAt: 2000 as number | undefined,
+    }
+    const currentTurn: typeof turn | null = turn
+    // 41s after the last (and only) narrative advance — well past the 30s cap.
+    // Legacy (stillDispatched: false) behaviour would already be 'stale' here
+    // (proven by the concern-3 test above); with a tracked foreground worker
+    // it must stay 'emit' so the card keeps climbing instead of freezing.
+    expect(heartbeatVerdict(currentTurn, 2000 + 41_000, /* stillDispatched */ true)).toBe('emit')
+  })
+
+  it('long silent single step (3m12s) — still bypasses the cap while still dispatched', () => {
+    const turn = {
+      finalAnswerDelivered: true,
+      finalAnswerDeliveredAt: 1000,
+      subagentActivityAt: 2000 as number | undefined,
+    }
+    const currentTurn: typeof turn | null = turn
+    const threeMinTwelveSecMs = 3 * 60_000 + 12_000
+    expect(heartbeatVerdict(currentTurn, 2000 + threeMinTwelveSecMs, true)).toBe('emit')
+  })
+
+  it('once the foreground sub-agent is no longer tracked (finished), the cap re-applies normally', () => {
+    // The gateway removes the agentId from `turn.foregroundSubAgents` when it
+    // finishes (gateway.ts ~27032/27037) — `stillDispatched` then reads false
+    // again and the ORIGINAL runaway-climb protection re-engages exactly as
+    // before Fix 3. This is the adversarial check that Fix 3 doesn't remove
+    // the cap's protection outright, only bypasses it while genuinely unknown.
+    const turn = {
+      finalAnswerDelivered: true,
+      finalAnswerDeliveredAt: 1000,
+      subagentActivityAt: 2000 as number | undefined,
+    }
+    const currentTurn: typeof turn | null = turn
+    expect(heartbeatVerdict(currentTurn, 2000 + 41_000, false)).toBe('stale')
+  })
+
+  it('idle-gap suppression still wins over stillDispatched (no watcher activity ever ⇒ silent, reply-is-last preserved)', () => {
+    // Adversarial check: a turn that dispatched a foreground sub-agent but has
+    // had NO watcher tick at all since the answer (subagentActivityAt
+    // undefined) must stay 'idle', never 'emit', even if stillDispatched is
+    // true — a still-registered worker with zero ticks yet is not the same as
+    // one whose last tick went stale. This preserves the reply-is-last
+    // invariant for a turn that answered and dispatched but hasn't surfaced
+    // any post-answer step yet.
+    const turn = {
+      finalAnswerDelivered: true,
+      finalAnswerDeliveredAt: 1000,
+      subagentActivityAt: undefined as number | undefined,
+    }
+    const currentTurn: typeof turn | null = turn
+    expect(heartbeatVerdict(currentTurn, 50_000, true)).toBe('idle')
+  })
+
+  it('end-to-end: the RENDERED card text keeps changing across real heartbeat ticks while a foreground sub-agent is silently working (not just the verdict function)', () => {
+    // Full simulated turn: dispatch a foreground Task, one narrative tick
+    // lands, then NOTHING further for over three minutes (one long silent
+    // Bash inside the sub-agent) — the exact operator-reported shape. Drives
+    // the REAL `evaluatePostAnswerLiveness` verdict AND the REAL
+    // `renderActivityFeedWithNested`/`composeTurnActivity`-shaped render at
+    // each tick, asserting the VISIBLE text (not an internal label) actually
+    // climbs instead of freezing.
+    const turn = {
+      finalAnswerDelivered: true,
+      finalAnswerDeliveredAt: 1_000,
+      subagentActivityAt: 2_000 as number | undefined,
+      mirrorLines: ['Delegating to a sub-agent'],
+      foregroundSubAgents: new Map<string, string[]>([['agent-1', ['Running a command']]]),
+    }
+
+    function renderCardAt(now: number): string | null {
+      const verdict = evaluatePostAnswerLiveness({
+        subagentActivityAt: turn.subagentActivityAt,
+        finalAnswerDeliveredAt: turn.finalAnswerDeliveredAt,
+        now,
+        staleCapMs: 30_000,
+        stillDispatched: turn.foregroundSubAgents.size > 0,
+      })
+      if (verdict !== 'emit') return null // the pre-Fix-3 freeze point
+      const childLines = [...turn.foregroundSubAgents.values()].flat()
+      const header = { label: 'Agent', elapsedMs: now - 0, toolCount: 1, state: 'running' as const }
+      return renderActivityFeedWithNested(turn.mirrorLines, childLines, false, formatStepSuffix(now - turn.subagentActivityAt!), undefined, header)
+    }
+
+    const tick1 = renderCardAt(2_000 + 6_000) // 6s after the last tick
+    const tick2 = renderCardAt(2_000 + 41_000) // 41s — the first operator-reported freeze point
+    const tick3 = renderCardAt(2_000 + (3 * 60_000 + 12_000)) // 3m12s — the second
+
+    expect(tick1).not.toBeNull()
+    expect(tick2).not.toBeNull()
+    expect(tick3).not.toBeNull()
+    // The visible text must actually differ tick-over-tick (climbing elapsed),
+    // not be frozen at the same string for minutes.
+    expect(tick2).not.toBe(tick1)
+    expect(tick3).not.toBe(tick2)
+    // And it must contain the growing wall-clock evidence the operator was
+    // missing — a live elapsed suffix on the nested step.
+    expect(tick2).toContain('41s')
+    expect(tick3).toContain('3m12s')
+  })
+})
+
 // ─── Fix 2 — concern 2 resolution: the decoupled worker surfaces via the
 //     currentTurn-INDEPENDENT workerActivityFeed (and is bounded) ────────────