switchroom 0.18.19 → 0.18.21

package/telegram-plugin/tests/worker-feed-terminal-state-truthful.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Residual B regression: a worker cleaned up by the TTL / authoritative
+ * `terminate` sweep — i.e. reaped / vanished / crashed WITHOUT ever delivering
+ * a clean `onFinish` result — must render a TRUTHFUL terminal state, NOT "done".
+ *
+ * `terminateWorker` synthesises the recap when NO clean finish arrived (a clean
+ * `onFinish` removes the row first, making `terminate` a no-op; an errored
+ * worker goes through `onFinish(outcome:'failed')`). So a row still present at
+ * terminate time genuinely ended without a result → it must render as the
+ * `incomplete` terminal ("incomplete · …"), never "done".
+ *
+ * OUTCOME assertions on the finalized card body (RED if `terminate` reverts to
+ * `state:'done'`), applied to the generic worker row so the guarantee holds at
+ * every nesting level (the feed keys rows by agentId, depth-agnostic):
+ *   - a solo reaped worker's terminal card reads `incomplete`, never `done`;
+ *   - a genuinely-`finish`ed worker still reads `done` with its result.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  createWorkerActivityFeed,
+  renderWorkerActivity,
+  type BotApiForWorkerFeed,
+  type WorkerActivityView,
+} from '../worker-activity-feed.js'
+
+function makeFeed(now: () => number) {
+  const sends: { text: string }[] = []
+  const edits: { messageId: number; text: string }[] = []
+  let seq = 900
+  const bot: BotApiForWorkerFeed = {
+    sendMessage: async (_c, text) => { sends.push({ text }); return { message_id: seq++ } },
+    editMessageText: async (_c, messageId, text) => { edits.push({ messageId, text }); return true },
+  }
+  const feed = createWorkerActivityFeed({
+    bot,
+    now,
+    minEditIntervalMs: 0,
+    firstPaintMinMs: 0,
+    setInterval: () => 0,
+    clearInterval: () => {},
+  })
+  return { feed, sends, edits }
+}
+const runningView = (desc: string, step: string, elapsedMs: number): WorkerActivityView => ({
+  description: desc, lastTool: null, toolCount: 3, latestSummary: step, elapsedMs, state: 'running',
+})
+async function drain(): Promise<void> {
+  for (let i = 0; i < 12; i++) await new Promise((r) => setImmediate(r))
+}
+
+describe('worker terminal state is truthful for reaped workers (Residual B)', () => {
+  it('a reaped/vanished worker (terminate, no clean finish) renders `incomplete`, never `done`', async () => {
+    let clock = 1000
+    const { feed, edits } = makeFeed(() => clock)
+    clock = 1000
+    await feed.update('w', 'chat', runningView('background job', 'doing work', 1000))
+    await drain()
+    clock = 5000
+    // Authoritative sweep / TTL backstop: no onFinish ever arrived.
+    await feed.terminate('w')
+    await drain()
+
+    const last = edits[edits.length - 1].text
+    expect(last, 'reaped worker must NOT read as done').not.toMatch(/\bdone\b/)
+    expect(last, 'reaped worker reads the truthful incomplete terminal').toContain('incomplete')
+    expect(feed.size).toBe(0)
+  })
+
+  it('a genuinely finished worker still renders `done` with its result', async () => {
+    let clock = 1000
+    const { feed, edits } = makeFeed(() => clock)
+    await feed.update('w', 'chat', runningView('background job', 'doing work', 1000))
+    await drain()
+    clock = 2000
+    await feed.finish('w', {
+      description: 'background job',
+      lastTool: null,
+      toolCount: 5,
+      latestSummary: 'the delivered result paragraph',
+      elapsedMs: 2000,
+      state: 'done',
+    })
+    await drain()
+    const last = edits[edits.length - 1].text
+    expect(last).toContain('done')
+    expect(last).toContain('the delivered result paragraph')
+    expect(last).not.toContain('incomplete')
+  })
+
+  // #3233 terminal-window race: the skeleton first-paint cue fires on EVERY
+  // no-growth poll, so one can land on a row that `finish()` just finalized
+  // (watcher poll cadence ≈ seconds). The `finalized` latch must absorb it —
+  // a late skeleton `update()` must NOT resurrect a fresh `running` card on an
+  // already-done worker. This exercises that path with a skeleton-shaped cue
+  // (empty step line, running state) arriving after finish.
+  it('a late skeleton update() after finish() is absorbed by the finalized latch (no resurrection)', async () => {
+    let clock = 1000
+    const { feed, edits } = makeFeed(() => clock)
+    await feed.update('w', 'chat', runningView('background job', 'doing work', 1000))
+    await drain()
+    clock = 2000
+    await feed.finish('w', {
+      description: 'background job',
+      lastTool: null,
+      toolCount: 5,
+      latestSummary: 'the delivered result paragraph',
+      elapsedMs: 2000,
+      state: 'done',
+    })
+    await drain()
+    const editsAfterFinish = edits.length
+    // Late skeleton cue (empty latestSummary, running state) — the shape the
+    // watcher emits on a no-growth poll — lands AFTER finalization.
+    clock = 2500
+    await feed.update('w', 'chat', {
+      description: 'background job',
+      lastTool: null,
+      toolCount: 5,
+      latestSummary: '',
+      elapsedMs: 2500,
+      state: 'running',
+    })
+    await drain()
+    // No further edit, no resurrection: the terminal card stays `done`.
+    expect(edits.length).toBe(editsAfterFinish)
+    expect(edits[edits.length - 1].text).toContain('done')
+    expect(feed.has('w')).toBe(false)
+  })
+
+  it('renderWorkerActivity renders the `incomplete` state as a finished card without a fabricated result', () => {
+    const card = renderWorkerActivity({
+      description: 'background job',
+      lastTool: null,
+      toolCount: 3,
+      latestSummary: '', // reaped: no result text
+      elapsedMs: 4000,
+      state: 'incomplete',
+    })
+    expect(card).toContain('incomplete')
+    expect(card).not.toMatch(/\bdone\b/)
+    // No fabricated result paragraph (latestSummary empty) → no ✅ result block.
+    expect(card).not.toContain('✅')
+  })
+
+  it('renderWorkerActivity NEVER renders a result/⚠️ block for `incomplete`, even with a non-empty latestSummary (deterministic guard, not caller-discipline)', () => {
+    // Latent-trap regression guard: the live call site (terminateWorker) always
+    // passes latestSummary:'' for a reaped worker, but a future/direct caller
+    // could pass stray text. The truthful-no-result invariant must be enforced
+    // in the renderer — an `incomplete` worker produced no result, so it must
+    // never fabricate a ⚠️-prefixed result paragraph regardless of the summary.
+    const card = renderWorkerActivity({
+      description: 'background job',
+      lastTool: null,
+      toolCount: 3,
+      latestSummary: 'this looks like a real result but the worker never finished',
+      elapsedMs: 4000,
+      state: 'incomplete',
+    })
+    expect(card).toContain('incomplete')
+    // The renderer maps a non-`done` finished result to the ⚠️ emoji; the guard
+    // must suppress that block entirely for `incomplete`.
+    expect(card).not.toContain('⚠️')
+    expect(card).not.toContain('this looks like a real result')
+  })
+})

package/telegram-plugin/tool-activity-summary.ts

@@ -170,8 +170,10 @@ export function clipNarrative(s: string): string {
  * `description` — italicised task description (optional)
  * `elapsedMs`   — wall-clock elapsed, rendered via `formatFeedElapsed`
  * `toolCount`   — labeled tool calls this turn
- * `state`       — 'running' | 'done' | 'failed' (controls the status line wording;
- *                 'failed' renders `failed · …` so a failed worker never reads as done)
+ * `state`       — 'running' | 'done' | 'failed' | 'incomplete' (controls the
+ *                 status line wording; 'failed'/'incomplete' render
+ *                 `failed · …` / `incomplete · …` so a failed or reaped worker
+ *                 never reads as done)
  *
  * Returns a two-element array of ready Telegram HTML lines (no trailing newline).
  */
@@ -181,7 +183,7 @@ export function renderActivityHeader(
   description: string,
   elapsedMs: number,
   toolCount: number,
-  state: 'running' | 'done' | 'failed',
+  state: 'running' | 'done' | 'failed' | 'incomplete',
   model?: string,
 ): [string, string] {
   const toolWord = toolCount === 1 ? 'tool' : 'tools'
@@ -283,7 +285,7 @@ export interface StatusCardHeader {
   description?: string
   elapsedMs: number
   toolCount: number
-  state: 'running' | 'done' | 'failed'
+  state: 'running' | 'done' | 'failed' | 'incomplete'
   /** Live model id (raw, e.g. `claude-opus-4-8`) — rendered as a short friendly
    *  tag on the metrics line via `formatModelLabel`. Omitted when unknown. */
   model?: string
@@ -582,6 +584,16 @@ export interface CombinedWorkerRow {
   toolCount: number
   /** The worker's latest step line (raw prose or friendly tool label). */
   currentStep: string
+  /**
+   * The worker's accumulated narrative history (oldest→newest, raw/unescaped),
+   * already deduped + rolling-window capped upstream (STATUS_ROLLING_LINES).
+   * When present + non-empty, the combined feed paints the worker's last-K
+   * lines as a `✓`/`→` step trail (prior steps struck, newest in-progress) —
+   * the same idiom as the single-worker card — with K set by the adaptive
+   * per-worker line budget. Absent/empty → falls back to the single
+   * `currentStep` line (back-compat for direct callers).
+   */
+  historyLines?: string[]
   /** Live model id (raw, e.g. `claude-opus-4-8`); omitted when unknown. */
   model?: string
 }
@@ -593,17 +605,53 @@ export interface CombinedWorkerFeedOpts {
   maxRows: number
 }
 
+/**
+ * Total per-worker BODY line budget for the combined feed — the sum, across all
+ * visible workers, of (one header line + that worker's history lines). The top
+ * `🛠 Workers · N running` line and the `+M more working…` spill are OUTSIDE
+ * this budget (fixed chrome). 13 is chosen so the card stays a compact glance,
+ * not a wall: at 2 workers it yields the full 5-line history each (2·1 header +
+ * 2·5 history = 12 ≤ 13), and it degrades to a single history line each by ~6
+ * workers — matching the pre-adaptive one-line-per-worker floor while never
+ * letting a 2–3 worker fan-out lose its narrative trail.
+ */
+const MAX_COMBINED_BODY_LINES = 13
+/** Each visible worker costs one header line before any history. */
+const PER_WORKER_HEADER_COST = 1
+
+/**
+ * Deterministic per-worker history depth for `w` visible workers:
+ *   clamp( floor( (BUDGET − headerCost·w) / w ), 1, STATUS_ROLLING_LINES )
+ * So 2 workers → 5 lines each, 3 → 3, 4 → 2, ≥6 → 1 (today's single-line floor
+ * is the graceful-degradation floor, never below it). Pure function of the
+ * visible worker count — no model input, consistent with deterministic controls.
+ */
+export function combinedHistoryDepth(w: number): number {
+  if (w <= 0) return 1
+  const raw = Math.floor((MAX_COMBINED_BODY_LINES - PER_WORKER_HEADER_COST * w) / w)
+  return Math.max(1, Math.min(STATUS_ROLLING_LINES, raw))
+}
+
 /**
  * Render N≥1 live workers into ONE combined feed body (ready Telegram
  * markdown; callers send verbatim — do NOT re-escape). Layout:
  *
  *   🛠 **Workers** · _N running_
  *   **{desc1}** _· {elapsed} · {n} tools_
- *   → _{step1}_
+ *   ~~_✓ {earlier step}_~~
+ *   **→ {newest step}**
  *   **{desc2}** _· {elapsed} · {n} tools_
- *   → _{step2}_
+ *   **→ {newest step}**
  *   _+M more working…_
  *
+ * ADAPTIVE DENSITY: each visible worker renders its last-K narrative lines as a
+ * `✓`/`→` trail (prior steps struck, newest bold in-progress) — the single-
+ * worker card's idiom — where K = `combinedHistoryDepth(visibleCount)` splits a
+ * fixed body-line budget across the running workers. So 2 workers each show
+ * their full recent history and a 6-way fan-out degrades to one line each, the
+ * card staying bounded regardless of fan-out. When a worker has no history yet
+ * it falls back to a single `→ starting…`/currentStep line.
+ *
  * Pure. Rows are rendered in the order supplied (the manager passes them
  * dispatch-order, oldest first). `maxRows` caps the visible rows; the hidden
  * remainder collapses to a single `+M more working…` line. A total-budget
@@ -618,29 +666,43 @@ export function renderCombinedWorkerFeed(
   if (rows.length === 0) return null
   const maxRows = Math.max(1, Math.floor(opts.maxRows))
 
-  const rowLines = (r: CombinedWorkerRow): [string, string] => {
+  const rowHeader = (r: CombinedWorkerRow): string => {
     const desc = escapeMarkdown(
       truncate(stripMarkdown(r.description).replace(/\s+/g, ' ').trim() || 'background task', COMBINED_ROW_DESC_MAX),
     )
     const toolWord = r.toolCount === 1 ? 'tool' : 'tools'
     const modelLabel = formatModelLabel(r.model)
     const modelPart = modelLabel != null ? ` · ${escapeMarkdown(modelLabel)}` : ''
-    const header = `**${desc}** _· ${formatFeedElapsed(r.elapsedMs)} · ${r.toolCount} ${toolWord}${modelPart}_`
-    const stepClean = stripMarkdown(r.currentStep).replace(/\s+/g, ' ').trim()
-    const step =
-      stepClean.length > 0
-        ? `→ _${escapeMarkdown(truncate(stepClean, STATUS_LINE_MAX))}_`
-        : `→ _starting…_`
-    return [header, step]
+    return `**${desc}** _· ${formatFeedElapsed(r.elapsedMs)} · ${r.toolCount} ${toolWord}${modelPart}_`
+  }
+
+  // Raw (unescaped) history for a worker, oldest→newest, empty lines stripped.
+  // Falls back to the single currentStep when no history was supplied.
+  const rowHistory = (r: CombinedWorkerRow): string[] => {
+    const src = r.historyLines != null && r.historyLines.length > 0 ? r.historyLines : [r.currentStep]
+    return src.filter((s) => s != null && stripMarkdown(s).replace(/\s+/g, ' ').trim().length > 0)
   }
 
   const compose = (visibleCount: number): string => {
     const shown = rows.slice(0, visibleCount)
     const hidden = rows.length - shown.length
+    // Adaptive depth: split the fixed body-line budget across the VISIBLE
+    // workers so the card stays bounded regardless of fan-out.
+    const depth = combinedHistoryDepth(shown.length)
     const out: string[] = [`🛠 **Workers** · _${rows.length} running_`]
     for (const r of shown) {
-      const [h, s] = rowLines(r)
-      out.push(h, s)
+      out.push(rowHeader(r))
+      const hist = rowHistory(r)
+      if (hist.length === 0) {
+        out.push('→ _starting…_')
+        continue
+      }
+      // Paint the last-K history lines with the SAME `✓`/`→` idiom as the
+      // single-worker card: escape each raw line through the shared per-line
+      // pipeline (escapeStepLine), then renderStepFeed strikes the prior steps
+      // and bolds the newest in-progress step.
+      const esc = hist.slice(-depth).map(escapeStepLine)
+      renderStepFeed(out, esc, false)
     }
     if (hidden > 0) out.push(`_+${hidden} more working…_`)
     return stackCardLines(out)

package/telegram-plugin/turn-flush-safety.ts

@@ -197,10 +197,10 @@ export function decideTurnFlush(input: FlushDecisionInput): FlushDecision {
   // lone `\n` collapses adjacent blocks into one run — on the Bot API 10.1
   // rich-markdown path (#2669) a single newline is a soft break, so the blocks
   // render as an undifferentiated wall-of-text. `\n\n` is the GFM paragraph
-  // separator; the Bot API 10.1 rich renderer shows it as one visible blank
-  // line, so the paragraphs render with real separation on their own (the
-  // former NBSP spacer pass was removed in the #2669 follow-up — it added a
-  // spurious second blank line).
+  // separator; the gateway send path then wedges visible spacers into those
+  // gaps via addParagraphSpacers (mirroring the reply path, #2692) so the
+  // paragraphs render with real separation (the rich GFM renderer otherwise
+  // shows a bare `\n\n` gap TIGHT).
   //
   // The silent-marker guards below are unaffected by this change:
   // isSilentFlushMarker length-guards the whole joined string; the composite /

package/telegram-plugin/worker-activity-feed.ts

@@ -69,7 +69,20 @@ export function isWorkerActivityFeedEnabled(envVal: string | undefined): boolean
   return envVal !== '0'
 }
 
-export type WorkerActivityState = 'running' | 'done' | 'failed'
+/**
+ * Terminal states a worker card can render.
+ *   - 'running'    — live.
+ *   - 'done'       — clean finish WITH a result (✅).
+ *   - 'failed'     — clean finish reporting a failure / crash observed in the
+ *                    transcript (⚠️).
+ *   - 'incomplete' — force-reaped / vanished / crashed WITHOUT any clean finish
+ *                    (the TTL sweep or the watcher's authoritative
+ *                    `onTerminalCleanup` synthesised the terminal because
+ *                    neither `onFinish` nor a turn_end ever delivered a result).
+ *                    Renders `incomplete · …` so a reaped worker NEVER reads as
+ *                    "done" — the truthful "ended without result" terminal.
+ */
+export type WorkerActivityState = 'running' | 'done' | 'failed' | 'incomplete'
 
 /** The render-relevant snapshot of a worker at one instant. */
 export interface WorkerActivityView {
@@ -141,7 +154,7 @@ const DESC_MAX = 80
  */
 export function renderWorkerActivity(v: WorkerActivityView, liveSuffix = ''): string {
   const desc = truncate(stripMarkdown(v.description).trim() || 'background task', DESC_MAX)
-  const finished = v.state === 'done' || v.state === 'failed'
+  const finished = v.state === 'done' || v.state === 'failed' || v.state === 'incomplete'
 
   // Raw narrative steps (unstripped/unescaped) — the unified renderer runs the
   // full per-line pipeline (stripMarkdown → collapse ws → clip → escape).
@@ -169,8 +182,15 @@ export function renderWorkerActivity(v: WorkerActivityView, liveSuffix = ''): st
 
   // Terminal: latestSummary carries the worker's final result text (gateway
   // onFinish), distinct from the running narrative steps. Pass it as `result`.
+  //
+  // Truthful-no-result invariant (deterministic control, not caller-discipline):
+  // an `incomplete` worker produced NO result, so it must NEVER render a result
+  // block regardless of whatever `latestSummary` happens to carry. The current
+  // call site (terminateWorker) always sets latestSummary:'' for incomplete, but
+  // enforce the invariant HERE so any future/direct caller can't fabricate a
+  // `⚠️`-prefixed result paragraph out of stray summary text.
   let result: { emoji: string; text: string } | undefined
-  if (finished) {
+  if (finished && v.state !== 'incomplete') {
     const text = cleanWorkerResultParagraph(v.latestSummary)
     if (text.length > 0) result = { emoji: v.state === 'done' ? '✅' : '⚠️', text }
   }
@@ -257,6 +277,27 @@ export interface WorkerActivityFeedOpts {
    * `channels.telegram.worker_feed.max_rows` via the config cascade.
    */
   maxRows?: number
+  /**
+   * Backstop TTL (ms): a worker row that has received no `update()` cue for
+   * longer than this AND is not already finished is force-terminated by the
+   * heartbeat sweep — its row is removed, and when it was the last live worker
+   * the shared card collapses to its terminal summary and unpins. This is the
+   * durable guard against an immortal card if BOTH terminal signals are missed
+   * (the gateway's `onFinish` AND the watcher's `onTerminalCleanup` sweep).
+   *
+   * The gateway DERIVES this in code from the watcher's effective in-flight
+   * terminal cap (`resolveInflightTerminalCapMs()` — the same env/default the
+   * watcher resolves) plus a margin, so the invariant "never reap a row the
+   * watcher still considers live" holds even if an operator raises the cap via
+   * `SWITCHROOM_SUBAGENT_INFLIGHT_TERMINAL_CAP_MS`. A worker mid-very-long tool
+   * can go silent up to the cap before the watcher declares it terminal, so any
+   * row still present past cap + margin is a definitive leak — the watcher would
+   * already have swept a live worker.
+   *
+   * Fallback default (this module, for direct / non-gateway callers) 50 min.
+   * Tests inject a small value.
+   */
+  staleWorkerTtlMs?: number
   /**
    * Group-level status-pin reconcile hook (#3207 review). Because workers now
    * COALESCE into one shared message, the pin MUST follow the GROUP lifecycle,
@@ -309,6 +350,15 @@ interface WorkerRow {
    * stable sort order within the combined feed.
    */
   dispatchAtMs: number | null
+  /**
+   * Wall-clock ms of the most recent `update()` cue for this worker (its last
+   * observed liveness). The heartbeat's backstop TTL sweep force-terminates a
+   * row whose `lastUpdateAt` is older than `staleWorkerTtlMs` — the durable
+   * guard that no card can go immortal even if every terminal signal (onFinish
+   * AND the onTerminalCleanup sweep) is somehow missed. Stamped on row creation
+   * and on every `update()`.
+   */
+  lastUpdateAt: number
   /**
    * Wall-clock ms the CURRENT step started — stamped whenever a NEW narrative
    * line lands (the `→` line changes). The heartbeat's step suffix shows the
@@ -432,6 +482,17 @@ export interface WorkerActivityFeed {
    *  in the group — force the terminal recap edit. No-op if the worker was
    *  never tracked. */
   finish(agentId: string, view: WorkerActivityView): Promise<void>
+  /**
+   * Force a worker terminal from an AUTHORITATIVE watcher sweep
+   * (`onTerminalCleanup`) or the backstop TTL, WITHOUT an external result view:
+   * the terminal recap is synthesised from the worker's own last-known row
+   * state (state → `done`, no fabricated result text — the real result reaches
+   * the user via the separate handback, if one ran). When it was the last live
+   * worker the shared card collapses to its terminal summary and unpins; with
+   * siblings, its row is dropped and the combined body re-renders. Idempotent —
+   * a no-op if the worker was already removed (e.g. `onFinish` fired first).
+   */
+  terminate(agentId: string): Promise<void>
   /** Forget a worker's state without a recap edit (e.g. error path); re-renders
    *  the group so the dropped worker disappears from the combined body. */
   drop(agentId: string): void
@@ -461,6 +522,7 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
   const firstPaintMin = opts.firstPaintMinMs ?? 8000
   const heartbeatTickMs = opts.heartbeatTickMs ?? 6000
   const maxRows = Math.max(1, Math.floor(opts.maxRows ?? 8))
+  const staleWorkerTtlMs = Math.max(1, Math.floor(opts.staleWorkerTtlMs ?? 50 * 60_000))
   const reconcilePinFn = opts.reconcilePin ?? (() => {})
   const setIntervalFn =
     opts.setInterval ??
@@ -616,6 +678,11 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
         elapsedMs: elapsedFor(r),
         toolCount: v.toolCount,
         currentStep,
+        // Full per-worker rolling history (oldest→newest) so the combined feed
+        // can paint an adaptive-depth ✓/→ trail, not just the latest line. The
+        // renderer clamps depth to the shared body-line budget; when a worker
+        // has no narrative yet this is empty and it falls back to currentStep.
+        historyLines: r.narrative.length > 0 ? [...r.narrative] : undefined,
         model: v.model,
       }
     })
@@ -785,10 +852,110 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
     }
   }
 
+  /**
+   * Shared terminal-finalize path for a worker whose row is still tracked.
+   * Latches the row terminal synchronously (so a late `running` cue on the
+   * chain can't resurrect it), then on the chain either drops the row + re-
+   * renders the surviving siblings, or — when it was the last live worker —
+   * finalizes the shared message to its terminal recap. Used by `finish` (with
+   * the gateway's onFinish view) AND by `terminate` (authoritative watcher
+   * sweep / TTL backstop, view synthesised from the row's own last state).
+   */
+  function finalizeWorker(group: FeedGroup, agentId: string, row: WorkerRow, view: WorkerActivityView): Promise<void> {
+    row.finished = true
+    // Preserve the truthful terminal state through to the row (done / failed /
+    // incomplete) — never collapse a reaped 'incomplete' into 'done'. view.state
+    // is always terminal on this path (finalize is only reached for a finishing
+    // worker), so threading it verbatim is correct.
+    row.state = view.state
+    markFinalized(agentId)
+    group.chain = group.chain
+      .then(() => {
+        const others = runningRows(group).filter((w) => w.agentId !== agentId)
+        if (others.length > 0) {
+          // Siblings still live → drop this row from the combined body and re-
+          // render the running set. The group pin STAYS (siblings still need
+          // the shared message).
+          removeWorker(group, agentId)
+          syncPin(group)
+          return doRender(group, { force: true })
+        }
+        // Last live worker → finalize the shared message to its terminal recap.
+        const recap: WorkerActivityView = { ...view, narrativeLines: [...row.narrative] }
+        return doRender(group, { force: true, terminalRecap: recap, finishingAgentId: agentId })
+      })
+      .catch((err) => {
+        log(`worker-feed: finalize chain error ${agentId}: ${(err as Error).message}`)
+      })
+    return group.chain
+  }
+
+  /**
+   * Force a worker terminal without an external result view (authoritative
+   * `onTerminalCleanup` sweep or the TTL backstop). Synthesises the recap from
+   * the row's own last-known state — state `incomplete` (NOT `done`), NO
+   * fabricated result text (the real result, if any, reaches the user via the
+   * separate handback). Reaching here means NO clean finish arrived: a clean
+   * `onFinish` removes the row FIRST (this call is then a no-op), and an
+   * errored worker goes through `onFinish(outcome:'failed')` → `finish` — so a
+   * row still present at terminate time genuinely ended WITHOUT a result. It
+   * must therefore render `incomplete · …`, never "done" (a crash/vanish read
+   * as "done" was the residual this fixes). Idempotent: a no-op once the worker
+   * was already removed (onFinish first). Depth-generic: operates on the
+   * generic worker row by agentId, identical at every nesting level.
+   */
+  function terminateWorker(agentId: string): Promise<void> {
+    const g = groupOfAgent(agentId)
+    const row = g?.workers.get(agentId)
+    if (g == null || row == null) {
+      // Already gone (onFinish removed it) — latch finalized so a late cue can't
+      // resurrect, and no-op.
+      markFinalized(agentId)
+      return Promise.resolve()
+    }
+    if (row.finished) {
+      // Terminal already latched; the chain will settle removal. No-op.
+      return g.chain
+    }
+    const lv = row.lastView
+    const view: WorkerActivityView = {
+      description: lv?.description ?? 'background task',
+      lastTool: null,
+      toolCount: lv?.toolCount ?? 0,
+      // No fabricated result paragraph — an authoritative sweep can't know what
+      // the worker returned; the terminal card shows the header struck-through
+      // as `incomplete`, and the handback (if it ran) carries the actual result.
+      latestSummary: '',
+      elapsedMs: liveElapsed(row, nowFn()),
+      state: 'incomplete',
+      model: lv?.model,
+    }
+    return finalizeWorker(g, agentId, row, view)
+  }
+
   // Arm the heartbeat once at construction. The real timer is `.unref()`'d so
   // it never keeps the process alive; tests inject setInterval/clearInterval.
   function heartbeatTick(): void {
     const now = nowFn()
+    // Backstop TTL sweep: force-terminate any worker row that has gone silent
+    // past `staleWorkerTtlMs` (no `update()` cue AND not already finished). This
+    // is the durable guard against an immortal card if BOTH terminal signals
+    // are missed — the gateway's `onFinish` AND the watcher's authoritative
+    // `onTerminalCleanup` sweep. Collect the stale agent ids first (terminate
+    // mutates the group's worker map), then terminate each through its chain so
+    // the render/unpin happens under the normal cooldown/flood guards.
+    const staleAgentIds: string[] = []
+    for (const g of groups.values()) {
+      for (const row of g.workers.values()) {
+        if (!row.finished && now - row.lastUpdateAt >= staleWorkerTtlMs) {
+          staleAgentIds.push(row.agentId)
+        }
+      }
+    }
+    for (const agentId of staleAgentIds) {
+      log(`worker-feed: TTL reap agent=${agentId} — no update in ${Math.floor((now - (groupOfAgent(agentId)?.workers.get(agentId)?.lastUpdateAt ?? now)) / 1000)}s (>= ${Math.floor(staleWorkerTtlMs / 1000)}s); force-terminating leaked row`)
+      void terminateWorker(agentId)
+    }
     for (const g of [...groups.values()]) {
       // Deferred-finalize re-drive: a terminal edit that hit a cooldown/flood
       // window was staged on `pendingFinalize`. Re-drive it once the cooldown
@@ -888,12 +1055,16 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
           lastView: null,
           state: 'running',
           finished: false,
+          lastUpdateAt: nowFn(),
           dispatchAtMs: null,
           stepStartedAtMs: null,
         }
         g.workers.set(agentId, row)
         agentIndex.set(agentId, feedKey)
       }
+      // Stamp liveness for the backstop TTL sweep (this is the worker's most
+      // recent observed activity cue).
+      row.lastUpdateAt = nowFn()
       // Accumulate before the gate so a throttled tick still grows the
       // narrative — it surfaces on the next edit that does fire.
       accumulateNarrative(row, view)
@@ -916,33 +1087,13 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
         markFinalized(agentId)
         return Promise.resolve()
       }
-      // Latch synchronously so a late `running` cue on the chain can't resurrect.
-      row.finished = true
-      row.state = view.state === 'failed' ? 'failed' : 'done'
-      markFinalized(agentId)
-
-      const group = g
-      group.chain = group.chain
-        .then(() => {
-          const others = runningRows(group).filter((w) => w.agentId !== agentId)
-          if (others.length > 0) {
-            // Siblings still live → drop this row from the combined body and
-            // re-render the running set. The result reaches the user via the
-            // separate handback, never folded into this cosmetic edit. The
-            // group pin STAYS (siblings still need the shared message) — a
-            // per-worker unpin here was the #3207 review blocker.
-            removeWorker(group, agentId)
-            syncPin(group)
-            return doRender(group, { force: true })
-          }
-          // Last live worker → finalize the shared message to its terminal recap.
-          const recap: WorkerActivityView = { ...view, narrativeLines: [...row.narrative] }
-          return doRender(group, { force: true, terminalRecap: recap, finishingAgentId: agentId })
-        })
-        .catch((err) => {
-          log(`worker-feed: finish chain error ${agentId}: ${(err as Error).message}`)
-        })
-      return group.chain
+      // Latch + finalize via the shared path (drop-with-siblings / terminal
+      // recap on the last worker). Synchronous latch inside finalizeWorker
+      // stops a late `running` cue on the chain from resurrecting the row.
+      return finalizeWorker(g, agentId, row, view)
+    },
+    terminate(agentId) {
+      return terminateWorker(agentId)
     },
     drop(agentId) {
       // A dropped worker is also done — mark finalized so a late tick can't