switchroom 0.18.9 → 0.18.10

package/telegram-plugin/registry/subagents-schema.ts

@@ -183,6 +183,20 @@ export interface ReapStuckRunningArgs {
   ttlMs: number
   /** Current time (DI for tests). */
   now: number
+  /**
+   * Optional liveness cross-check against the in-memory file-discovery
+   * registry. Called with a candidate row's `jsonl_agent_id` (null when
+   * linkage never happened); return `true` if the watcher is actively
+   * tailing a live worker for that id. When it returns true the row is
+   * NOT reaped — the DB's `last_activity_at` is a *stale* liveness signal
+   * (it's only bumped when the JSONL is linked, and it freezes during a
+   * long in-flight tool call), so a row the watcher knows is alive must
+   * not be independently classified as dead here. The watcher owns that
+   * worker's terminal transition. Incident 2026-07-10: a live, actively-
+   * card-editing worker was reaped as terminal because this cross-check
+   * didn't exist. Omit to preserve the pre-fix unconditional behaviour.
+   */
+  isLive?: (jsonlAgentId: string | null) => boolean
 }
 
 export interface ReapStuckRunningResult {
@@ -524,14 +538,23 @@ export function reapStuckRunningRows(
   args: ReapStuckRunningArgs,
 ): ReapStuckRunningResult {
   const cutoff = args.now - args.ttlMs
-  const candidates = db
+  const rows = db
     .prepare(`
-      SELECT id FROM subagents
+      SELECT id, jsonl_agent_id FROM subagents
       WHERE status = 'running'
         AND background = 1
         AND COALESCE(last_activity_at, started_at) < ?
     `)
-    .all(cutoff) as Array<{ id: string }>
+    .all(cutoff) as Array<{ id: string; jsonl_agent_id: string | null }>
+
+  // Cross-check each stale-by-DB candidate against the live in-memory
+  // registry. A worker the watcher is actively tailing is NOT dead just
+  // because its DB `last_activity_at` is stale/NULL — the watcher owns
+  // its terminal transition. Skipping these prevents the incident where a
+  // live, actively-card-editing worker was reaped as terminal.
+  const candidates = args.isLive
+    ? rows.filter((r) => !args.isLive!(r.jsonl_agent_id))
+    : rows
 
   for (const row of candidates) {
     recordSubagentStall(db, {

package/telegram-plugin/registry/subagents.test.ts

@@ -665,6 +665,73 @@ describe('reapStuckRunningRows', () => {
     expect(result.reaped).toBe(5)
     expect(result.ids.sort()).toEqual(['sa-0', 'sa-1', 'sa-2', 'sa-3', 'sa-4'])
   })
+
+  // Incident 2026-07-10: a live, actively-card-editing worker was reaped as
+  // terminal because the DB `last_activity_at` was stale (linkage never
+  // bumped it) while the in-memory file-discovery registry knew it was
+  // alive. The reaper must cross-check the live registry before reaping.
+  it('does NOT reap a row the live registry reports as an active worker', () => {
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, {
+      id: 'sa-live',
+      background: true,
+      startedAt: 1000,
+      jsonlAgentId: 'a3c5b2d5765810114',
+    })
+    // DB liveness is stale (past ttl) — but the watcher is actively tailing
+    // this worker, so isLive returns true and the row is spared.
+    const liveIds = new Set(['a3c5b2d5765810114'])
+    const result = reapStuckRunningRows(db, {
+      ttlMs: 500,
+      now: 5000,
+      isLive: (jid) => jid != null && liveIds.has(jid),
+    })
+    expect(result.reaped).toBe(0)
+    expect(getSubagent(db, 'sa-live')!.status).toBe('running')
+  })
+
+  it('still reaps a stale row that is NOT in the live registry (genuine orphan)', () => {
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, {
+      id: 'sa-orphan',
+      background: true,
+      startedAt: 1000,
+      jsonlAgentId: 'dead-worker',
+    })
+    // Also a live one to prove the predicate discriminates per-row.
+    recordSubagentStart(db, {
+      id: 'sa-alive',
+      background: true,
+      startedAt: 1000,
+      jsonlAgentId: 'live-worker',
+    })
+    const liveIds = new Set(['live-worker'])
+    const result = reapStuckRunningRows(db, {
+      ttlMs: 500,
+      now: 5000,
+      isLive: (jid) => jid != null && liveIds.has(jid),
+    })
+    expect(result.reaped).toBe(1)
+    expect(result.ids).toEqual(['sa-orphan'])
+    expect(getSubagent(db, 'sa-orphan')!.status).toBe('stalled')
+    expect(getSubagent(db, 'sa-alive')!.status).toBe('running')
+  })
+
+  it('reaps a stale row with NULL jsonl_agent_id (the watcher predicate never matches an unlinked row)', () => {
+    const db = openFreshSubagentsDbInMemory()
+    recordSubagentStart(db, { id: 'sa-unlinked', background: true, startedAt: 1000 })
+    // Mirror the production predicate shape: a null jsonl_agent_id can't
+    // key into the registry, so it always reports not-live and the reaper
+    // (the safety net for exactly this unlinked-orphan case) still fires.
+    const liveIds = new Set<string>()
+    const result = reapStuckRunningRows(db, {
+      ttlMs: 500,
+      now: 5000,
+      isLive: (jid) => jid != null && liveIds.has(jid),
+    })
+    expect(result.reaped).toBe(1)
+    expect(getSubagent(db, 'sa-unlinked')!.status).toBe('stalled')
+  })
 })
 
 // ---------------------------------------------------------------------------

package/telegram-plugin/retry-api-call.ts

@@ -371,3 +371,34 @@ export function isMessageTooLongError(err: unknown): boolean {
     d.includes('text is too long')
   )
 }
+
+/**
+ * True when Telegram rejected a `sendPhoto` / `sendMediaGroup` because the
+ * image is unusable AS A PHOTO — dimensions out of range (Telegram caps
+ * photos at width+height ≤ 10000 and aspect ratio ≤ 20), the file can't be
+ * saved as a photo, or it exceeds the photo-path size ceiling (~10MB;
+ * documents allow ~50MB). A tall phone screenshot is the canonical trigger
+ * (PHOTO_INVALID_DIMENSIONS in the #klanker 2026-07-10 incident).
+ *
+ * These 400s are deliberately NOT swallowed or retried by `retryApiCall`
+ * (only not-modified / not-found / thread-not-found are) — they surface to
+ * the caller, which recovers by re-sending the SAME file as a document
+ * (`sendDocument`) so the user still receives it. Same "caller-level
+ * fallback" shape as the THREAD_NOT_FOUND and isHtmlParseRejectError
+ * contracts above.
+ */
+export function isPhotoDimensionRejectError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  const d = (err.description || '').toLowerCase()
+  return (
+    d.includes('photo_invalid_dimensions') ||
+    d.includes('photo_save_file_invalid') ||
+    d.includes('photo dimensions') ||
+    d.includes('image_process_failed') ||
+    // size-driven rejections of the photo path
+    d.includes('photo is too big') ||
+    d.includes('too big for a photo') ||
+    d.includes('image is too big') ||
+    d.includes('file is too big')
+  )
+}

package/telegram-plugin/subagent-watcher.ts

@@ -140,6 +140,21 @@ export interface WorkerEntry {
    * the renderer only ever shows the latest.
    */
   lastTool: { name: string; sanitisedArg: string } | null
+  /**
+   * Tool-use ids for tool calls this worker has STARTED but not yet
+   * finished — a `sub_agent_tool_use` was observed with no matching
+   * `sub_agent_tool_result` yet. A non-empty set means the worker is
+   * currently *inside* a tool call (e.g. a long-running `Bash` frame-
+   * capture loop that can legally run 10+ minutes with zero JSONL
+   * growth). The silent-stall terminal synthesis (checkStalls Pass 2)
+   * MUST NOT fire while this is non-empty: a frozen `lastActivityAt`
+   * during an in-flight tool call is expected, not a dead worker.
+   * Cleared on the matching `sub_agent_tool_result` and on
+   * `sub_agent_turn_end` (belt-and-braces). Tool-use lines with a null
+   * `toolUseId` can't be paired, so they don't participate — Bash and
+   * every real long-runner always carries a `toolu_…` id.
+   */
+  inflightToolUseIds: Set<string>
   /**
    * True if the underlying JSONL file existed before the watcher started.
    * Historical entries are tracked for late state transitions but are
@@ -300,6 +315,21 @@ export interface SubagentWatcherConfig {
    * synthesis; tests use a tiny value to exercise the path.
    */
   silentStallTerminalMs?: number
+  /**
+   * Upper bound (ms of total JSONL idle) on the in-flight tool-call
+   * deferral of terminal synthesis. While a tool call is in flight
+   * (tool_use seen, matching tool_result not yet), synthesis is deferred —
+   * a long `Bash` legitimately freezes the JSONL for 10+ min (incident
+   * 2026-07-10). But a worker that DIES mid-tool (process killed; JSONL
+   * stops growing but is never deleted) would otherwise defer forever, and
+   * the reaper's isLive cross-check would shield it from the DB net too —
+   * wedged for the life of the gateway. Past this cap the deferral ends
+   * and synthesis proceeds. Default 45 min
+   * (DEFAULT_INFLIGHT_TERMINAL_CAP_MS) — above any legitimate single tool
+   * call, below the 1h reaper TTL. Env override
+   * `SWITCHROOM_SUBAGENT_INFLIGHT_TERMINAL_CAP_MS`.
+   */
+  inflightTerminalCapMs?: number
   /**
    * Freshness window (ms) for promoting a running-at-boot worker file to
    * live. A file whose last write (mtime) is older than this is treated as
@@ -409,6 +439,34 @@ export interface SubagentWatcherConfig {
    * (the handback) regardless. Retained as an unwired hook.
    */
   onStallTerminal?: (agentId: string, description: string) => void
+  /**
+   * Issue #3023 (card resurrection). Fires when a worker whose card was
+   * FALSELY finalised — its terminal state came from silent-stall synthesis
+   * (`onStallTerminal` above), NOT a real `sub_agent_turn_end` — resumes
+   * writing to its JSONL after the synthesis. The synthesis was wrong: the
+   * worker is still alive, so the operator invariant ("active work must
+   * always be visible") requires its progress surface to come back. The
+   * watcher re-registers the worker as a LIVE, non-historical entry (so
+   * `onProgress` / stall-detection / the real handback resume), and fires
+   * this so the gateway can revive the worker's activity card (clear the
+   * feed's finalized gate → repaint on the next progress tick).
+   *
+   * GUARD (at-most-once per false finish + bounded chain): a given false
+   * finish is resurrected at most once. A worker that is resurrected and
+   * then falsely finalised AGAIN is NOT resurrected a second time — it is
+   * named-as-lost via `onWorkerLost` instead, so a pathological worker
+   * can't loop finish→resurrect forever.
+   */
+  onResurrect?: (agentId: string, description: string) => void
+  /**
+   * Issue #3023 (bounded resurrection chain). Fires when a worker that was
+   * already resurrected once is falsely finalised a second time and its
+   * JSONL resumes yet again. Rather than resurrect it forever, the watcher
+   * declares it LOST (a single log line names it) and stops resurrecting.
+   * The gateway may surface this however it likes; the invariant is only
+   * that the chain is bounded, not that a lost worker gets a fresh card.
+   */
+  onWorkerLost?: (agentId: string, description: string) => void
   /**
    * Called exactly once per sub-agent when its watcher observes a terminal
    * transition (`done` or `failed`). Mirrors the existing `sub_agent_started`
@@ -536,6 +594,12 @@ const DEFAULT_SILENT_SYNTHESIS_STALL_THRESHOLD_MS = 300_000
  * ceiling that closed-out cards used to wait on.
  */
 const DEFAULT_SILENT_STALL_TERMINAL_MS = 300_000
+// Upper bound on the in-flight tool-call deferral of terminal synthesis.
+// 45 min: comfortably above any legitimate single tool call (Bash caps at
+// 10 min per call; the incident loop ran ~10 min) but below the 1h DB
+// reaper TTL, so the watcher — not the reaper — still owns the terminal
+// transition for a worker that died mid-tool.
+const DEFAULT_INFLIGHT_TERMINAL_CAP_MS = 45 * 60_000
 
 /**
  * Tools that legitimately run for minutes with ZERO intervening JSONL
@@ -553,6 +617,21 @@ const DEFAULT_SILENT_STALL_TERMINAL_MS = 300_000
  */
 const LONG_RUNNING_TOOLS: ReadonlySet<string> = new Set(['Bash'])
 
+/**
+ * Issue #3023 (bounded resurrection chain). Maximum number of times a single
+ * worker may have its falsely-finalised card resurrected. Once a worker has
+ * been resurrected this many times and is falsely finalised AGAIN, the next
+ * post-terminal JSONL resumption names it LOST rather than resurrecting it —
+ * so a pathological finish→resurrect→finish loop is bounded, not infinite.
+ * One resurrection is enough to recover the real 2026-07-10 incident (a
+ * single false finish from one over-long tool call); a second false finish on
+ * the same worker is a signal the heuristics can't track it, so we stop.
+ */
+const MAX_RESURRECTIONS = 1
+/** Cap on the false-finish tracker so it can't grow unbounded over a
+ *  long-lived gateway; oldest record is evicted FIFO past this. */
+const FALSE_FINISH_TRACKER_CAP = 512
+
 /** True when the tool named legitimately runs quiet for minutes (see
  *  LONG_RUNNING_TOOLS). Null/undefined tool name → false. */
 function isLongRunningTool(name: string | null | undefined): boolean {
@@ -1144,6 +1223,14 @@ export function readSubTail(
             entry.lastReplyText = ev.input.text as string
           }
           entry.toolCount++
+          // Track this as an IN-FLIGHT tool call so the silent-stall
+          // terminal synthesis (checkStalls Pass 2) doesn't misread the
+          // frozen JSONL of a long-running tool (a 10-min `Bash` loop) as
+          // a dead worker. Only pairable (non-null id) tool_uses count —
+          // Bash + every real long-runner always carries a `toolu_…` id.
+          if (ev.toolUseId != null && ev.toolUseId !== '') {
+            entry.inflightToolUseIds.add(ev.toolUseId)
+          }
           // P0 of #662: surface the most recent tool name + sanitised
           // arg so the driver's fleet-state shadow can render the
           // last-tool column on the v2 status card. Sanitiser lives in
@@ -1197,6 +1284,16 @@ export function readSubTail(
             }
           }
         } else if (ev.kind === 'sub_agent_nested_spawn') {
+          // A nested Agent/Task dispatch is the same frozen-JSONL shape as
+          // a long tool call: a FOREGROUND nested child blocks this worker
+          // until it returns, with the matching tool_result only landing
+          // then — so gate terminal synthesis on it too. The existing
+          // `sub_agent_tool_result` handler clears the id (a background
+          // nested dispatch's "launched" result lands almost immediately,
+          // so it barely defers). Same cap applies.
+          if (ev.toolUseId != null && ev.toolUseId.length > 0) {
+            entry.inflightToolUseIds.add(ev.toolUseId)
+          }
           // Nested (depth-2+) dispatch keying: this worker just dispatched a
           // sub-agent of its own. The PreToolUse hook can't attribute it (the
           // main turn's turn-active.json marker is long gone for a background
@@ -1254,7 +1351,17 @@ export function readSubTail(
             fireNarrativeProgress() // prior pending was pure narration → SHOW
           }
           entry.pendingNarrative = { text: ev.text }
+        } else if (ev.kind === 'sub_agent_tool_result') {
+          // The tool call completed — clear it from the in-flight set so
+          // the terminal-synthesis gate re-opens. Idempotent: a result
+          // whose tool_use we never tracked (null id, parallel spill) is
+          // a harmless no-op delete.
+          if (ev.toolUseId != null && ev.toolUseId !== '') {
+            entry.inflightToolUseIds.delete(ev.toolUseId)
+          }
         } else if (ev.kind === 'sub_agent_turn_end') {
+          // Belt-and-braces: a turn boundary means nothing is in flight.
+          entry.inflightToolUseIds.clear()
           // Narrative-dedup gate step 3: a trailing sub_agent_text block with
           // nothing after it. SUPPRESS only when it drafts the foreground
           // sub-agent's delivered reply (entry.lastReplyText, set above on a
@@ -1346,6 +1453,10 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     config.silentStallTerminalMs
     ?? parseEnvMs('SWITCHROOM_SUBAGENT_STALL_TERMINAL_MS')
     ?? DEFAULT_SILENT_STALL_TERMINAL_MS
+  const inflightTerminalCapMs =
+    config.inflightTerminalCapMs
+    ?? parseEnvMs('SWITCHROOM_SUBAGENT_INFLIGHT_TERMINAL_CAP_MS')
+    ?? DEFAULT_INFLIGHT_TERMINAL_CAP_MS
   const inflightPromoteMaxAgeMs =
     config.inflightPromoteMaxAgeMs
     ?? parseEnvMs('SWITCHROOM_SUBAGENT_INFLIGHT_MAX_AGE_MS')
@@ -1428,6 +1539,39 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
    * terminal JSONLs as a no-op.
    */
   const terminatedAgentIds = new Set<string>()
+  /**
+   * Issue #3023 (card resurrection). Per-worker record of a FALSE terminal
+   * finish — a terminal state produced by silent-stall synthesis (NOT a real
+   * `sub_agent_turn_end`). Keyed by agentId; SURVIVES `cleanupTerminalAgent`
+   * (which drops the registry entry) precisely so a post-terminal JSONL
+   * resumption can be detected after the entry is gone.
+   *
+   * A genuine completion (`turn_end`) or a genuine boot-time historical
+   * rediscovery NEVER writes here — only synthesis does — so those paths can
+   * never be resurrected. This map IS the discriminator between "old
+   * completed worker rediscovered at boot" (no record → stays suppressed)
+   * and "worker I finalised moments ago whose JSONL just grew again"
+   * (record present → resurrect).
+   *
+   *   - `synthesisedAt`  — wall-clock ms the false finish fired.
+   *   - `sizeAtSynthesis`— JSONL byte size at that moment; post-terminal
+   *                        growth past this proves the worker resumed.
+   *   - `resurrectionCount` — times this worker has been resurrected. Bounds
+   *                        the chain: once it reaches MAX, the next false
+   *                        finish is named-as-lost, not resurrected.
+   *   - `resurrectedForThisFinish` — at-most-once guard for the CURRENT false
+   *                        finish; reset when a new synthesis records over it.
+   *   - `lost` — the chain bound was hit; no further resurrection.
+   */
+  interface FalseFinishRecord {
+    filePath: string
+    synthesisedAt: number
+    sizeAtSynthesis: number
+    resurrectionCount: number
+    resurrectedForThisFinish: boolean
+    lost: boolean
+  }
+  const falseFinishTracker = new Map<string, FalseFinishRecord>()
   /**
    * True while the initial boot scan is running. During this window every
    * newly discovered file is added to historicalFiles.
@@ -1463,6 +1607,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       lastResultText: '',
       lastProgressBucketIdx: null,
       lastTool: null,
+      inflightToolUseIds: new Set<string>(),
       historical: isHistorical,
     }
     registry.set(agentId, entry)
@@ -1778,6 +1923,188 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     log?.(`subagent-watcher: cleaned up terminal agent ${agentId}`)
   }
 
+  // ─── Card resurrection (issue #3023) ─────────────────────────────────────
+
+  /**
+   * Record a FALSE terminal finish (silent-stall synthesis). Preserves any
+   * carried-over `resurrectionCount` from a prior false finish on the same
+   * worker (bounded-chain guard) while re-arming the per-finish at-most-once
+   * guard. Best-effort file-size snapshot: an unreadable stat records 0, so
+   * ANY later readable growth still counts as a resumption.
+   */
+  function recordFalseFinish(agentId: string, filePath: string, n: number): void {
+    let size = 0
+    try {
+      size = fs.statSync(filePath).size
+    } catch { /* unreadable → 0, any later growth still trips resumption */ }
+    const prior = falseFinishTracker.get(agentId)
+    if (prior == null && falseFinishTracker.size >= FALSE_FINISH_TRACKER_CAP) {
+      const oldest = falseFinishTracker.keys().next().value
+      if (oldest != null) falseFinishTracker.delete(oldest)
+    }
+    falseFinishTracker.set(agentId, {
+      filePath,
+      synthesisedAt: n,
+      sizeAtSynthesis: size,
+      resurrectionCount: prior?.resurrectionCount ?? 0,
+      resurrectedForThisFinish: false,
+      // `lost` is sticky: once a worker is named-lost it stays lost.
+      lost: prior?.lost ?? false,
+    })
+  }
+
+  /**
+   * Bring a falsely-finalised worker back to LIVE. Cancels any pending
+   * terminal cleanup and clears the terminated/historical suppression, then
+   * revives via one of two branches so `onProgress`, stall-detection and a
+   * genuine future handback all resume:
+   *
+   *   1. IN-PLACE REVIVE (registry entry still present — cleanup grace hadn't
+   *      elapsed): flip the existing entry back to `running` and reset its
+   *      stall/completion flags. The entry KEEPS its existing tail cursor and
+   *      FSWatcher, so the card repaints INCREMENTALLY from where it left off —
+   *      it does NOT re-read from cursor 0.
+   *   2. SWEPT RE-REGISTER (entry already dropped by cleanupTerminalAgent):
+   *      `registerAgent` re-registers the JSONL as a fresh non-historical
+   *      entry, re-reading from cursor 0 to rebuild the worker's activity so
+   *      the revived card catches up instead of showing a frozen stub.
+   */
+  function resurrectAgent(agentId: string, filePath: string): void {
+    const pc = pendingCloses.get(agentId)
+    if (pc != null) {
+      clearT(pc)
+      pendingCloses.delete(agentId)
+    }
+    terminatedAgentIds.delete(agentId)
+    historicalFiles.delete(filePath)
+
+    const existing = registry.get(agentId)
+    if (existing != null) {
+      // Cleanup grace hadn't elapsed — revive the live entry in place so the
+      // existing tail/FSWatcher keeps feeding it.
+      existing.state = 'running'
+      existing.historical = false
+      existing.stallNotified = false
+      existing.stalledAt = null
+      existing.stallTerminalSynthesised = false
+      // Re-arm the completion notification INTENTIONALLY (issue #3023). The
+      // false synthesized finish already fired `onFinish` once, delivering a
+      // (possibly wrong / incomplete) synthesized handback to the parent.
+      // Clearing this lets a genuine future `sub_agent_turn_end` fire `onFinish`
+      // a SECOND time — and that is the desired behaviour: the corrected REAL
+      // result must reach the parent, superseding the false one. This does NOT
+      // double-deliver harmfully: the gateway's handback spool dedups only
+      // CONCURRENTLY-LIVE envelopes for the same worker (inbound-spool.ts:
+      // `s:handback:<agentId>` — `live.has(id)` guard, no permanent tombstone),
+      // so the first (synthesized) handback drains + acks as a normal turn, is
+      // removed from the live set, and the later real handback is then
+      // delivered as a fresh turn rather than being suppressed. See the
+      // "resurrected worker's real turn_end re-fires onFinish" test.
+      existing.completionNotified = false
+      existing.errored = false
+      existing.errorDetail = undefined
+      // The worker just proved it is alive (its JSONL grew), so restart the
+      // stall clock from now — otherwise the pre-synthesis idle would carry
+      // over and a fresh stall/synthesis could fire almost immediately.
+      existing.lastActivityAt = nowFn()
+      knownFiles.add(filePath)
+      // KNOWN LIMITATION (issue #3023): we revive the IN-MEMORY registry entry
+      // to `running`, but the subagents DB row stays `completed`/`failed` (the
+      // stall-synthesis path wrote a terminal row via recordSubagentEnd). We do
+      // NOT flip it back: `recordSubagentResume` only reverses `stalled→running`
+      // by design ("terminal beats both stalled and running" — see its doc),
+      // and there is no terminal→running edge because the stuck-row reaper and
+      // audit consistency both lean on terminal being final. Consequence:
+      // `countRunningBackgroundSubagents` (WHERE status='running') UNDERCOUNTS a
+      // resurrected worker until its genuine `turn_end` re-terminates the entry.
+      // Impact is bounded and benign — that count only gates the deferred-👍
+      // reaction promotion (reaction-defer.ts), so at worst a 👍 promotes one
+      // resurrection-window early; it is never a delivery/correctness path. Left
+      // as a known limitation rather than punching a terminal→running hole in
+      // the schema invariant.
+      return
+    }
+    // Entry was already swept — re-register from scratch as a live worker.
+    knownFiles.add(filePath)
+    registerAgent(filePath, agentId)
+  }
+
+  /**
+   * Detect post-terminal JSONL resumption for falsely-finalised workers and
+   * either resurrect the card (once per false finish) or name the worker lost
+   * (bounded chain). Called on every poll tick.
+   */
+  function checkResurrections(): void {
+    const n = nowFn()
+    for (const [agentId, rec] of falseFinishTracker) {
+      if (rec.lost) continue
+      if (rec.resurrectedForThisFinish) continue
+      let size: number
+      try {
+        size = fs.statSync(rec.filePath).size
+      } catch {
+        continue // file vanished / unreadable — nothing to resurrect
+      }
+      // Growth past the synthesis snapshot is the proof the worker resumed.
+      // (The tracker itself already excludes genuine completions and boot-time
+      // historical rediscoveries — they never record here — so size growth is
+      // a sufficient signal; no mtime dependence needed.)
+      //
+      // BOUNDED FALSE-POSITIVE (issue #3023, accepted): ANY byte growth past
+      // the snapshot trips resurrection, including a late buffered `turn_end`
+      // flush from a genuinely-done worker. If the silent-stall synthesis fired
+      // moments before Claude Code finally flushed the worker's real
+      // `sub_agent_turn_end` line, that trailing write grows the JSONL and we
+      // resurrect a worker that is actually finished — a benign
+      // resurrect→immediate-refinish flicker that burns ONE unit of the
+      // resurrection budget (MAX_RESURRECTIONS). We accept this because (a) the
+      // flicker is self-healing: the very next poll sees the terminal line,
+      // fires a real `turn_end`, and re-finalises the card; (b) the corrected
+      // real handback still reaches the parent (see the completionNotified
+      // reset in resurrectAgent); and (c) the alternative — parsing the tail to
+      // distinguish a real turn_end flush from live resumption — is far more
+      // fragile than a bounded, harmless re-finish. The chain bound guarantees
+      // this can never loop. Covered by the "late turn_end after synthesis"
+      // resurrection test.
+      if (size <= rec.sizeAtSynthesis) continue
+
+      const entry = registry.get(agentId)
+      const description = entry?.description ?? 'sub-agent'
+
+      if (rec.resurrectionCount >= MAX_RESURRECTIONS) {
+        // Bounded-chain guard: this worker was already resurrected once and
+        // has now falsely finished again. Do NOT resurrect forever — name it
+        // lost and stop. One log line names the worker for the operator.
+        rec.lost = true
+        log?.(`subagent-watcher: worker ${agentId} FALSELY finalised again after a prior resurrection (resurrectionCount=${rec.resurrectionCount} >= ${MAX_RESURRECTIONS}) — NAMED AS LOST, not resurrecting again (bounded resurrection chain, issue #3023)`)
+        if (config.onWorkerLost != null) {
+          try {
+            config.onWorkerLost(agentId, description)
+          } catch (cbErr) {
+            log?.(`subagent-watcher: onWorkerLost callback error ${agentId}: ${(cbErr as Error).message}`)
+          }
+        }
+        continue
+      }
+
+      // Resurrect: at-most-once for THIS false finish.
+      rec.resurrectionCount++
+      rec.resurrectedForThisFinish = true
+      log?.(`subagent-watcher: RESURRECTING worker ${agentId} — JSONL resumed growing (${rec.sizeAtSynthesis} → ${size} bytes) after a false terminal synthesis; the worker is still alive, reviving its card (resurrection #${rec.resurrectionCount}, issue #3023)`)
+      // Fire onResurrect FIRST so the gateway clears the feed's finalized
+      // gate before the re-registration below replays onProgress ticks —
+      // otherwise those first ticks would be swallowed by the finalized gate.
+      if (config.onResurrect != null) {
+        try {
+          config.onResurrect(agentId, description)
+        } catch (cbErr) {
+          log?.(`subagent-watcher: onResurrect callback error ${agentId}: ${(cbErr as Error).message}`)
+        }
+      }
+      resurrectAgent(agentId, rec.filePath)
+    }
+  }
+
   // ─── Stall detection ────────────────────────────────────────────────────
 
   function checkStalls(): void {
@@ -1862,11 +2189,57 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       if (entry.stallTerminalSynthesised) continue
       if (entry.stalledAt == null) continue
       if (n - entry.stalledAt < silentStallTerminalMs) continue
+      // In-flight tool-call gate (incident 2026-07-10): a worker whose
+      // transcript ends in a `tool_use` with no matching `tool_result`
+      // yet is NOT silent — it's *inside* a long tool call (a `Bash`
+      // frame-capture loop legally runs 10+ minutes with zero JSONL
+      // growth). Synthesising `sub_agent_turn_end` here finalises a live
+      // worker's card while it keeps running (real incident: card 16201
+      // reaped at t+13min, worker resumed 92ms later with no card).
+      //
+      // The deferral is CAPPED, not unconditional (design reconciliation
+      // with #2777/#2782, whose contract is "a bg worker JSONL that
+      // legitimately lacks turn_end must still release the completion
+      // gate"): a worker that DIES mid-tool (process killed; JSONL frozen
+      // but never deleted) would otherwise defer forever, and the reaper's
+      // isLive cross-check would shield it from the DB net too. So: while
+      // a tool call is in flight, defer synthesis up to
+      // `inflightTerminalCapMs` of total JSONL idle (default 45 min — far
+      // above any legitimate single tool call, below the 1h reaper TTL);
+      // past the cap, synthesis proceeds. A tool_result landing at any
+      // point drains the set and re-arms normal detection via the
+      // un-stall path.
+      if (entry.inflightToolUseIds.size > 0) {
+        const totalIdleMs = n - entry.lastActivityAt
+        if (totalIdleMs < inflightTerminalCapMs) {
+          log?.(`subagent-watcher: silent-stall terminal synthesis deferred for ${entry.agentId} — ${entry.inflightToolUseIds.size} tool call(s) still in flight, ${Math.floor(totalIdleMs / 1000)}s idle < ${Math.floor(inflightTerminalCapMs / 1000)}s cap (long-running tool, not a dead worker)`)
+          continue
+        }
+        log?.(`subagent-watcher: in-flight deferral cap reached for ${entry.agentId} (${Math.floor(totalIdleMs / 1000)}s idle >= ${Math.floor(inflightTerminalCapMs / 1000)}s cap with ${entry.inflightToolUseIds.size} tool call(s) still unresolved) — treating as died-mid-tool, proceeding with terminal synthesis`)
+      }
+      // TODO(#3023/PR #3029): the cap-reached path above is a SECOND source of
+      // possibly-false terminal synthesis (a worker mid-very-long-tool that is
+      // NOT dead gets finalised here). PR #3029 adds `recordFalseFinish(...)`
+      // to this synthesis block so a later JSONL resumption can resurrect the
+      // card. When #3029 lands, make sure the merge resolution keeps
+      // `recordFalseFinish(entry.agentId, entry.filePath, n)` covering BOTH
+      // the plain silent-stall path and this cap-reached fall-through (they
+      // share this block, so a clean merge does — verify at conflict time).
+      // Intentionally NOT wired here to keep this PR standalone (no
+      // cross-PR dependency; recordFalseFinish does not exist on this branch).
       entry.stallTerminalSynthesised = true
       entry.state = 'done'
       const postStallSec = Math.floor((n - entry.stalledAt) / 1000)
       const totalIdleSec = Math.floor((n - entry.lastActivityAt) / 1000)
       log?.(`subagent-watcher: silent-stall terminal synthesis for ${entry.agentId} (stalled ${postStallSec}s post-notify, ${totalIdleSec}s total idle) — bg worker JSONL lacks turn_end; synthesising sub_agent_turn_end so deferred-completion gate releases`)
+      // Issue #3023: this terminal state is SYNTHESISED, not a real
+      // `turn_end` — it may be wrong (the worker could still be alive). Record
+      // a false-finish so a later JSONL resumption can resurrect the card. The
+      // record survives cleanupTerminalAgent (keyed by agentId, in its own
+      // map). A carried-over resurrectionCount from a PRIOR false finish is
+      // preserved so the chain stays bounded; resurrectedForThisFinish resets
+      // to arm the at-most-once guard for THIS finish.
+      recordFalseFinish(entry.agentId, entry.filePath, n)
       // Persist completion to the registry DB so reaper / audit paths
       // see the same terminal state as the JSONL-driven path.
       if (db != null) {
@@ -2087,6 +2460,10 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
 
     // Stall detection
     checkStalls()
+
+    // Issue #3023: revive any worker whose falsely-finalised card's JSONL has
+    // resumed growing (or name it lost if the resurrection chain is spent).
+    checkResurrections()
   }
 
   // Initial boot scan: discover pre-existing files and mark them historical
@@ -2103,7 +2480,21 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
   function runReaper(): void {
     if (db == null) return
     try {
-      const result = reapStuckRunningRows(db, { ttlMs: reaperTtlMs, now: nowFn() })
+      const result = reapStuckRunningRows(db, {
+        ttlMs: reaperTtlMs,
+        now: nowFn(),
+        // Liveness cross-check: never reap a row whose worker the watcher
+        // is actively tailing. A live entry is `running`, non-historical,
+        // and still in the in-memory registry (cleanupTerminalAgent drops
+        // it on real termination). The DB `last_activity_at` freezes during
+        // a long in-flight tool call and is NULL when linkage failed — both
+        // would otherwise false-positive a live worker as terminal.
+        isLive: (jsonlAgentId) => {
+          if (jsonlAgentId == null) return false
+          const entry = registry.get(jsonlAgentId)
+          return entry != null && entry.state === 'running' && !entry.historical
+        },
+      })
       if (result.reaped > 0) {
         log?.(`subagent-watcher: reaper transitioned ${result.reaped} stuck-running row(s) to stalled (ttl=${Math.round(reaperTtlMs / 60_000)}min)`)
       }