switchroom 0.18.32 → 0.19.0

package/telegram-plugin/gateway/voice-ondemand-callback-handler.ts

@@ -0,0 +1,204 @@
+/**
+ * On-demand voice ('🔊 Listen') callback family (`voice:<token>`) extracted
+ * verbatim from the gateway's `callback_query:data` dispatcher
+ * (switchroom#2996 P6 dispatcher drain).
+ *
+ * Handles the tap INTERNALLY — synthesizes the cached reply text and sends it
+ * as a native voice note. MUST run before the agent-callback routing in the
+ * dispatcher so a tap never reaches the agent as an inbound message.
+ *
+ * Returns true when the callback was a voice-on-demand tap (handled —
+ * dispatcher must `return`), false otherwise (dispatcher falls through).
+ *
+ * DI note (check-bot-api-wrapping, cluster-F pattern): the raw
+ * `bot.api.sendVoice` / `bot.api.editMessageReplyMarkup` calls are NOT made
+ * here — they are injected as `sendVoiceByFileId` / `sendVoiceByUpload` /
+ * `stripListenKeyboard`, bound in gateway.ts inside `robustApiCall(...)` with
+ * their existing allow-raw-bot-api markers. This module has no raw Bot API
+ * site.
+ */
+
+import { readFileSync } from 'node:fs'
+import type { Context } from 'grammy'
+import {
+  isVoiceOnDemandCallback,
+  parseVoiceOnDemandToken,
+  type VoiceOnDemandPayload,
+} from '../voice-ondemand.js'
+import { sendVoiceReusingFileId, type SentVoiceMessage } from '../voice-send.js'
+import { synthesizeViaSidecar } from '../voice-synthesize-sidecar.js'
+import { normalizeForTts } from '../tts-normalize.js'
+import { materializeSidecarToken } from '../../src/telegram/materialize-sidecar-token.js'
+
+export interface VoiceSendOpts {
+  reply_parameters?: { message_id: number }
+  message_thread_id?: number
+}
+
+export interface VoiceOnDemandCallbackDeps {
+  loadAccess: () => { allowFrom: string[] }
+  voiceOnDemandCache: {
+    get: (token: string) => VoiceOnDemandPayload | null
+    setTelegramFileId: (token: string, fileId: string) => void
+  }
+  /** robustApiCall(() => bot.api.sendVoice(chatId, fileId, opts), verbOpts) — bound in gateway.ts. */
+  sendVoiceByFileId: (
+    chatId: string,
+    fileId: string,
+    sendOpts: VoiceSendOpts,
+    threadId: number | undefined,
+  ) => Promise<SentVoiceMessage>
+  /** robustApiCall(() => bot.api.sendVoice(chatId, new InputFile(audio), opts), verbOpts) — bound in gateway.ts. */
+  sendVoiceByUpload: (
+    chatId: string,
+    audio: Uint8Array,
+    sendOpts: VoiceSendOpts,
+    threadId: number | undefined,
+  ) => Promise<SentVoiceMessage>
+  /** robustApiCall(() => bot.api.editMessageReplyMarkup(...)) — bound in gateway.ts; swallows failure. */
+  stripListenKeyboard: (
+    chatId: string,
+    messageId: number,
+    threadId: number | undefined,
+  ) => Promise<void>
+  /** stderr log sink. */
+  log: (line: string) => void
+}
+
+/** Handle a `voice:` callback. Returns false if `data` is not one. */
+export async function handleVoiceOnDemandCallback(
+  ctx: Context,
+  data: string,
+  deps: VoiceOnDemandCallbackDeps,
+): Promise<boolean> {
+  if (!isVoiceOnDemandCallback(data)) return false
+  const access = deps.loadAccess()
+  const senderId = String(ctx.from!.id)
+  if (!access.allowFrom.includes(senderId)) {
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return true
+  }
+  const token = parseVoiceOnDemandToken(data)
+  const entry = token != null ? deps.voiceOnDemandCache.get(token) : null
+  if (entry == null) {
+    await ctx
+      .answerCallbackQuery({ text: 'Voice expired — send again to hear it.' })
+      .catch(() => {})
+    return true
+  }
+  const cbChatId = String(ctx.chat?.id ?? ctx.from!.id)
+  const cbMessageId = ctx.callbackQuery?.message?.message_id
+  const cbThreadId = (() => {
+    const msg = ctx.callbackQuery?.message
+    if (msg && 'is_topic_message' in msg && msg.is_topic_message && 'message_thread_id' in msg) {
+      const tid = (msg as { message_thread_id?: number }).message_thread_id
+      return typeof tid === 'number' ? tid : undefined
+    }
+    return undefined
+  })()
+  const tok = token as string
+  const sendOpts: VoiceSendOpts = {
+    ...(cbMessageId != null ? { reply_parameters: { message_id: cbMessageId } } : {}),
+    ...(cbThreadId != null ? { message_thread_id: cbThreadId } : {}),
+  }
+
+  // #2763 attach-on-tap: prefer the eagerly pre-synthesized file (written by
+  // the pre-synth queue at reply time). If it's on disk, attach it
+  // immediately — no GPU wait. Missing/unreadable file (expired + swept,
+  // crash, pre-feature entry, kill-switched gateway) falls back transparently
+  // to the lazy synth path. Only invoked when there's no reusable file_id (or
+  // a stored id was rejected as stale) — see sendVoiceReusingFileId.
+  const loadAudio = async (): Promise<Uint8Array | null> => {
+    let audio: Uint8Array | null = null
+    if (entry.filePath != null) {
+      try {
+        audio = readFileSync(entry.filePath)
+      } catch {
+        audio = null // swept/missing — lazy fallback
+      }
+    }
+    if (audio != null) {
+      await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+      return audio
+    }
+    await ctx.answerCallbackQuery({ text: '🔊 Synthesizing…' }).catch(() => {})
+    // Local sidecar (kokoro) synthesis — same helper the immediate voice-out
+    // path uses. On-demand is a local-engine feature; the cache is only
+    // populated when resolveVoiceOutPlan gated the local verdict.
+    const sidecarToken = await materializeSidecarToken()
+    if (!sidecarToken) {
+      await ctx
+        .answerCallbackQuery({ text: 'Voice sidecar unavailable — try again later.' })
+        .catch(() => {})
+      return null
+    }
+    const result = await synthesizeViaSidecar({
+      token: sidecarToken,
+      // #2760 Phase 1: same deterministic normalization as the immediate
+      // voice-out path — the Listen lazy path builds its own /tts body from
+      // the persisted cache, so it must normalize independently (cache
+      // entries may predate the flag flip).
+      text: normalizeForTts(entry.text),
+      voice: entry.voice,
+      speed: entry.speed,
+    })
+    if (!result.ok) {
+      deps.log(
+        `telegram gateway: voice-out on-demand: synthesis failed reason=${result.reason}\n`,
+      )
+      await ctx
+        .answerCallbackQuery({ text: `Voice failed: ${result.reason}` })
+        .catch(() => {})
+      return null
+    }
+    return result.audio
+  }
+
+  // Fast path: if we already captured a reusable file_id, ack instantly and
+  // send BY the id — no disk read, no re-upload. First tap (no id yet) and a
+  // stale-id fallback both go through loadAudio + InputFile below and refresh
+  // the stored id from the returned message.
+  if (entry.telegramFileId != null) {
+    await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+  }
+  const sendResult = await sendVoiceReusingFileId({
+    fileId: entry.telegramFileId ?? null,
+    sendByFileId: (fid) => deps.sendVoiceByFileId(cbChatId, fid, sendOpts, cbThreadId),
+    loadAudio,
+    sendByUpload: (audioOut) => deps.sendVoiceByUpload(cbChatId, audioOut, sendOpts, cbThreadId),
+    onFileId: (fid) => deps.voiceOnDemandCache.setTelegramFileId(tok, fid),
+    log: (line) => deps.log(line),
+  })
+
+  if (!sendResult.ok) {
+    // no-audio already surfaced a toast inside loadAudio; send-failed is
+    // logged non-fatally — the '🔊 Listen' keyboard is left intact so the
+    // user can retry (only a successful send strips it below).
+    if (sendResult.reason === 'send-failed') {
+      const err = sendResult.error
+      const msg = err instanceof Error ? err.message : String(err)
+      deps.log(
+        `telegram gateway: voice-out on-demand: sendVoice failed (non-fatal): ${msg}\n`,
+      )
+    }
+    return true
+  }
+  try {
+    // Single-use on SUCCESS: strip the '🔊 Listen' keyboard so the button
+    // can't be re-tapped now that the audio has been delivered. Mirrors the
+    // agent-button single_use strip (keyboardIsSingleUse) house style.
+    // Best-effort + non-fatal — a failed strip only leaves a replayable
+    // button, never drops the delivered audio. Only reached on a successful
+    // sendVoice; expiry / synth-failure / sidecar-unavailable all return
+    // earlier WITHOUT stripping, so the user can retry those.
+    if (cbMessageId != null) {
+      await deps.stripListenKeyboard(cbChatId, cbMessageId, cbThreadId).catch(() => {})
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    deps.log(
+      `telegram gateway: voice-out on-demand: strip-listen-keyboard failed (non-fatal): ${msg}\n`,
+    )
+  }
+  return true
+}

package/telegram-plugin/gateway/worker-feed-dispatch.ts

@@ -1,5 +1,45 @@
 import type { Subagent } from '../registry/subagents-schema.js'
 
+/**
+ * The narrow slice of the worker-activity feed `handleWorkerResume` needs —
+ * structurally satisfied by `WorkerActivityFeed` (worker-activity-feed.ts)
+ * without importing it (keeps this module dependency-light and the seam
+ * trivially mockable in tests).
+ */
+export interface WorkerFeedForResume {
+  resurrect(agentId: string): void
+}
+
+/**
+ * Issue #3373 (SendMessage-resume feed re-surface) — the gateway's `onResume`
+ * handler body, extracted so the seam is unit-testable and gateway.ts keeps
+ * only a thin delegation (the line-ratchet drains inline bodies).
+ *
+ * A worker with a GENUINE terminal completion that is resumed via SendMessage
+ * grows its jsonl past the terminal boundary and is re-registered live by the
+ * watcher (#3315). This clears the feed's terminal `finalized` latch
+ * (`feed.resurrect`) so the resumed worker's next onProgress cue repaints a
+ * fresh live row — without it the latch swallows every resumed cue and the
+ * worker reads as silence. Distinct from the #3023 `onResurrect` path: no
+ * bounded-chain budget (a worker may be stopped/resumed any number of times).
+ *
+ * Best-effort: a resurrect failure is logged, never thrown back into the
+ * watcher's poll loop. `feed` may be null/undefined (feed disabled) — the
+ * re-surface log line is still emitted for the audit trail.
+ */
+export function handleWorkerResume(
+  feed: WorkerFeedForResume | null | undefined,
+  agentId: string,
+  log: (msg: string) => void,
+): void {
+  try {
+    feed?.resurrect(agentId)
+  } catch (err) {
+    log(`telegram gateway: worker resume feed re-surface error agent=${agentId}: ${(err as Error).message}`)
+  }
+  log(`telegram gateway: worker ${agentId} card RE-SURFACED — resumed via SendMessage after a genuine terminal (issue #3373)`)
+}
+
 export interface WorkerFeedDispatch {
   /** True when the sub-agent was dispatched with `run_in_background: true`. */
   isBackground: boolean

package/telegram-plugin/narrative-dedup.ts

@@ -25,9 +25,32 @@
  * message.
  */
 
-/** Tools whose `input.text` IS the canonical answer surface. */
+/** Tool suffixes whose `input.text` IS the canonical answer surface. */
 export const REPLY_TOOLS = new Set(['reply', 'stream_reply'])
 
+/**
+ * Strip this plugin's `mcp__<server-key>__telegram__` prefix, matched by the
+ * same key-agnostic regex `computeLabel` / `isTelegramReplyTool` use so renames
+ * and forks (`clerk-telegram`, `switchroom-telegram`, …) all resolve. A bare
+ * name (no prefix) is returned unchanged.
+ */
+const TELEGRAM_TOOL_PREFIX_RE = /^mcp__[^_].*?telegram__/
+
+/**
+ * Prefix-aware membership test for {@link REPLY_TOOLS}.
+ *
+ * Production jsonl carries the fully-qualified MCP tool name
+ * (`mcp__switchroom-telegram__stream_reply`), so a bare `REPLY_TOOLS.has(name)`
+ * is always false in prod and the draft-then-send suppression path silently
+ * goes inert (#3231). Bare names ('reply' / 'stream_reply') can still appear
+ * from non-MCP sources, so both wire shapes must match: strip the telegram MCP
+ * prefix (a no-op for bare names) then test the suffix against REPLY_TOOLS.
+ */
+export function isReplyTool(toolName: string | null | undefined): boolean {
+  if (typeof toolName !== 'string') return false
+  return REPLY_TOOLS.has(toolName.replace(TELEGRAM_TOOL_PREFIX_RE, ''))
+}
+
 /**
  * Normalize for prefix comparison: strip markdown/HTML-ish emphasis,
  * heading and quote marks, collapse whitespace, lowercase. Mirrors the

package/telegram-plugin/narrative-flush.ts

@@ -39,7 +39,7 @@
  * effects and the per-turn lifetime.
  */
 
-import { REPLY_TOOLS, isDraftOfReply } from './narrative-dedup.js'
+import { isReplyTool, isDraftOfReply } from './narrative-dedup.js'
 
 /**
  * Time-box for the parked-narrative early-paint (the kernel's home for the
@@ -139,7 +139,7 @@ export class NarrativeFlushController {
   resolveOnTool(toolName: string, input: Record<string, unknown> | undefined): void {
     this.scheduler.disarm()
     const replyText =
-      REPLY_TOOLS.has(toolName) && typeof input?.text === 'string' ? (input.text as string) : null
+      isReplyTool(toolName) && typeof input?.text === 'string' ? (input.text as string) : null
     if (replyText != null) this.maybeRetract(replyText)
     const pending = this.pending
     if (pending == null) return

package/telegram-plugin/render/render.ts

@@ -203,10 +203,34 @@ function renderTable(node: TableNode): string {
   return [headerLine, sepLine, ...bodyLines].join("\n");
 }
 
+/**
+ * Escape a line-leading `#` in rendered PROSE so Telegram cannot promote the
+ * line to a heading (#3304 regression).
+ *
+ * Per CommonMark/GFM, `#` opens an ATX heading only when followed by a space,
+ * another `#`, or end-of-line — so micromark correctly parses `#3304 is
+ * merged.` as a plain paragraph, and this renderer re-emits it verbatim
+ * (`escapeMarkdown` deliberately leaves `#` alone). But Telegram's Bot API
+ * 10.1 server-side rich-markdown parser is NON-spec here: any line-leading
+ * `#` run is read as a heading, so an issue reference opening a line renders
+ * the whole paragraph as huge heading text. Backslash-escaping the first `#`
+ * of each such line keeps it literal on Telegram while remaining a no-op
+ * visually (Telegram honours backslash escapes, same mechanism the link-href
+ * `)` escape relies on).
+ *
+ * Applied ONLY to paragraph output (including paragraphs nested in
+ * blockquotes / list items via their renderBlock recursion), never to
+ * heading, code-block, or table nodes — so a genuine `# Title` heading node
+ * still renders as `# Title`.
+ */
+function escapeLineLeadingHash(text: string): string {
+  return text.replace(/^([ \t]{0,3})#/gm, "$1\\#");
+}
+
 function renderBlock(node: Block): string {
   switch (node.type) {
     case "paragraph":
-      return renderInlineChildren(node.children);
+      return escapeLineLeadingHash(renderInlineChildren(node.children));
     case "heading":
       return `${"#".repeat(node.level)} ${renderInlineChildren(node.children)}`;
     case "blockquote":

package/telegram-plugin/status-no-truncate.ts

@@ -28,6 +28,19 @@ import { RICH_MESSAGE_MAX_CHARS } from './format.js'
  */
 export const STATUS_ROLLING_LINES = 5
 
+/**
+ * Ceiling on the per-worker recent-step history RETAINED in `row.narrative`
+ * (worker-activity-feed.ts) and the deepest trail the worker cards will render.
+ *
+ * Distinct from `STATUS_ROLLING_LINES` (which governs the 🤖 agent card's
+ * window and stays at 5) so raising the worker trail never widens the agent
+ * card. Set to 6 because the deterministic per-worker depth curve
+ * (`workerHistoryDepth`, tool-activity-summary.ts) peaks at 6 for a lone
+ * worker — `max(3, 7 − workerCount)` at `w = 1`. The buffer must retain at
+ * least this many lines or the renderer would ask for 6 and only find 5.
+ */
+export const WORKER_HISTORY_MAX = 6
+
 /**
  * Per-line character cap, applied to every step + child step on BOTH
  * surfaces before HTML-escaping (clip raw → escape last). A line longer

package/telegram-plugin/subagent-watcher.ts

@@ -46,7 +46,7 @@ import { homedir } from 'os'
 import { projectSubagentLine, sanitizeCwdToProjectName, detectErrorInTranscriptLine } from './session-tail.js'
 import { sanitiseToolArg } from './fleet-state.js'
 import { clipNarrative, describeToolUse } from './tool-activity-summary.js'
-import { REPLY_TOOLS } from './narrative-dedup.js'
+import { isReplyTool } from './narrative-dedup.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from './narrative-flush.js'
 import { truncate } from './card-format.js'
 import { bumpSubagentActivity, recordSubagentStall, recordSubagentResume, recordSubagentEnd, reapStuckRunningRows, countRunningBackgroundSubagents, recordNestedSubagentDispatch, recordSubagentModel } from './registry/subagents-schema.js'
@@ -551,6 +551,31 @@ export interface SubagentWatcherConfig {
    * that the chain is bounded, not that a lost worker gets a fresh card.
    */
   onWorkerLost?: (agentId: string, description: string) => void
+  /**
+   * Issue #3373 (SendMessage-resume feed re-surface). Fires when a worker that
+   * had a GENUINE terminal completion (a real `sub_agent_turn_end`, then swept
+   * by `cleanupTerminalAgent`) is RESUMED via SendMessage — its
+   * `agent-<id>.jsonl` grows PAST the byte size recorded at terminal cleanup,
+   * and `scanSubagentsDir` re-registers it as a fresh live entry (#3315).
+   *
+   * This is DISTINCT from `onResurrect` (#3023), which reverses a FALSE finish
+   * from silent-stall synthesis and carries bounded-chain semantics. A
+   * SendMessage resume is a real, legitimately-unbounded lifecycle event (a
+   * worker may be stopped and resumed many times), so it does NOT route through
+   * the resurrection budget — it fires here every time growth-past-terminal is
+   * observed.
+   *
+   * Why it exists: the live worker-activity feed latches a terminal `finalized`
+   * gate per agentId (worker-activity-feed.ts) so a late zombie tick can't
+   * repaint a done worker. The #3315 re-registration re-arms the watcher and
+   * re-fires `onProgress`, but those cues are SWALLOWED by that latch — so a
+   * resumed long-running worker reads as silence with no card. The gateway
+   * wires this to `feed.resurrect(agentId)` (clear the latch) so the subsequent
+   * `onProgress` cue repaints a fresh live row. Deterministic: gated solely on
+   * the file growing past the recorded terminal boundary, never on model
+   * discipline. Best-effort; the callback is expected to be idempotent.
+   */
+  onResume?: (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`
@@ -846,6 +871,17 @@ const DEFAULT_REAPER_INTERVAL_MS = 15 * 60_000     // 15 minutes
  */
 const TERMINAL_CLEANUP_GRACE_MS = 30_000
 
+/**
+ * Bounded tail window (bytes) the boot-reconcile fast-path reads to decide
+ * whether a stale historical worker already reached `turn_end` before this
+ * boot (see `probeReachedTurnEndAtBoot`). Large enough to contain any realistic
+ * final line (a `turn_duration` line is ~100 bytes; an `end_turn` assistant
+ * answer line is well under this), yet a tiny fraction of the multi-MB
+ * transcripts a long-running worker accumulates — so the boot read is O(window)
+ * per record instead of O(filesize). 512 KiB.
+ */
+const BOOT_TERMINAL_PROBE_WINDOW_BYTES = 512 * 1024
+
 /**
  * Throttle for the liveness-path retry of `backfillJsonlAgentId` (see
  * WorkerEntry.lastBackfillAttemptAt). Cheap (one meta.json read + two
@@ -1551,8 +1587,8 @@ export function readSubTail(
           const narrativeJustFired = resolvePendingSubNarrative(ev.toolName, ev.input)
           // NIT 3: capture a foreground sub-agent's actual reply text so the
           // turn_end path can suppress a trailing draft of it (see
-          // resolvePendingSubNarrative). Only REPLY_TOOLS carry the answer.
-          if (REPLY_TOOLS.has(ev.toolName) && typeof ev.input?.text === 'string') {
+          // resolvePendingSubNarrative). Only reply tools carry the answer.
+          if (isReplyTool(ev.toolName) && typeof ev.input?.text === 'string') {
             entry.lastReplyText = ev.input.text as string
           }
           entry.toolCount++
@@ -1923,6 +1959,58 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
 
   let stopped = false
 
+  /**
+   * Cheap boot-terminal probe. Reads only a BOUNDED TAIL of a JSONL (not the
+   * whole multi-MB transcript) and runs the canonical `projectSubagentLine`
+   * projector over its complete lines to decide whether the worker had already
+   * reached `sub_agent_turn_end` before this boot. Used by the boot-reconcile
+   * fast-path to tell a done-at-boot worker (which still needs terminal
+   * cleanup — feed-row sweep, card collapse/unpin) apart from a running-at-boot
+   * dead prior-session worker (which needs nothing) WITHOUT the expensive full
+   * read. `done` is the only terminal boot state (`WorkerState` never flips to
+   * `'failed'` at boot — see its doc), and its signal (`system/turn_duration`
+   * or an `end_turn` assistant line) is always the tail of the file, so a
+   * bounded window catches it. Conservative on error: an unreadable/oversized
+   * final line returns `false`, so the entry falls through to the running-stale
+   * skip rather than being mis-swept.
+   */
+  function probeReachedTurnEndAtBoot(filePath: string, size: number): boolean {
+    if (size <= 0) return false
+    const start = Math.max(0, size - BOOT_TERMINAL_PROBE_WINDOW_BYTES)
+    let raw: string
+    try {
+      const len = size - start
+      const buf = Buffer.alloc(len)
+      const fd = fs.openSync(filePath, 'r')
+      try {
+        fs.readSync(fd, buf, 0, len, start)
+      } finally {
+        fs.closeSync(fd)
+      }
+      raw = buf.toString('utf-8')
+    } catch {
+      return false
+    }
+    const lines = raw.split('\n')
+    // If we started mid-file, the first fragment is a partial line — drop it
+    // (projectSubagentLine would JSON-parse-fail on it anyway, but be explicit).
+    if (start > 0) lines.shift()
+    const probeState = { hasEmittedStart: true } // suppress start events; irrelevant here
+    for (const line of lines) {
+      if (!line) continue
+      let events
+      try {
+        events = projectSubagentLine(line, 'probe', probeState)
+      } catch {
+        continue
+      }
+      for (const ev of events) {
+        if (ev.kind === 'sub_agent_turn_end') return true
+      }
+    }
+    return false
+  }
+
   // ─── Per-agent registration ─────────────────────────────────────────────
 
   /**
@@ -1969,6 +2057,85 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     }
     registry.set(agentId, entry)
 
+    // Boot reconcile fast-path (perf): a historical boot entry whose file's
+    // LAST WRITE already exceeds the in-flight promotion freshness window is a
+    // provably-dead prior-session worker. The freshness gate below reaches the
+    // exact same verdict ("stale — leaving historical, no live transition to
+    // observe"), but only AFTER the full initial `readSubTail` (a whole-
+    // transcript parse plus per-record sqlite liveness/backfill round-trips).
+    // On a busy 24/7 agent, hundreds of these dead JSONLs accumulate, and doing
+    // that O(n) work synchronously at boot delayed the gateway answering
+    // Telegram by minutes after every restart — the agent looked dead. Since
+    // the age check ALONE decides "dead prior-session worker" (identical
+    // threshold `inflightPromoteMaxAgeMs`), compute it up front and short-
+    // circuit: register a minimal historical entry, skip the read, the
+    // promotion attempt, and the FSWatcher. A resume re-registration (#3315)
+    // passes isHistorical=false (historicalFiles.delete precedes it) and a
+    // genuinely fresh in-flight-at-boot worker fails the age check, so both
+    // still take the full path below.
+    if (isHistorical) {
+      let mtimeMs: number | null = null
+      let fileSize = 0
+      try {
+        const st = fs.statSync(filePath)
+        if (typeof st.size === 'number') fileSize = st.size
+        if (typeof st.mtimeMs === 'number') mtimeMs = st.mtimeMs
+      } catch {
+        /* unreadable → mtimeMs stays null → conservative full path below */
+      }
+      // Only fast-path when the mtime is KNOWN and already past the freshness
+      // window — a confidently-dead prior-session worker. A missing/unreadable
+      // mtime is NOT treated as dead here (unlike the freshness gate's
+      // Infinity-is-stale rule): we conservatively fall through to the full
+      // path so the read still happens, since the whole optimisation targets
+      // real on-disk files (which always carry an mtime) and the boot cost only
+      // bites at fleet scale where mtimes are present.
+      if (mtimeMs != null && n - mtimeMs > inflightPromoteMaxAgeMs) {
+        const fileAgeMs = n - mtimeMs
+        // The expensive boot work was the full initial `readSubTail` (whole-
+        // transcript parse + per-record sqlite liveness/backfill round-trips)
+        // done for EVERY historical `running` JSONL, including the hundreds a
+        // busy 24/7 agent hoards that were last written days-to-weeks ago. It
+        // produced nothing actionable for a worker the freshness gate was about
+        // to leave historical anyway, yet its O(filesize) disk reads (×~1177 on
+        // the incident agent) delayed the gateway answering Telegram by minutes
+        // after every restart. Replace it with a BOUNDED tail probe.
+        //
+        // The probe distinguishes the two stale-at-boot populations WITHOUT the
+        // full read, so we don't over-skip: a *done*-at-boot worker (its JSONL
+        // already reached `turn_end`) must still reach `scheduleTerminalCleanup`
+        // — otherwise its worker-feed row leaks as a ghost (card never
+        // collapsed/unpinned; #<worker-feed ghost-leak>). A *running*-at-boot
+        // dead prior-session worker (never wrote a terminal `turn_end` — the
+        // incident population) needs nothing: no read, no backfill, no watcher,
+        // no cleanup.
+        const doneAtBoot = probeReachedTurnEndAtBoot(filePath, fileSize)
+        // Park the tail cursor at the boot-time EOF either way. A historical
+        // entry whose cursor sits at EOF is a cheap no-op in the poll loop
+        // (readSubTail statSyncs, sees `size === cursor`, returns before any
+        // openSync/sqlite — the skeleton-cue path is gated on `!historical`), so
+        // no poll-loop special-casing is needed; a genuine post-boot resume that
+        // grows the file PAST this EOF is still read on the next poll. No
+        // FSWatcher: a dead prior-session worker has no live transition to
+        // observe. And a stale worker's pre-existing `turn_end` sits BEFORE the
+        // parked cursor, so it is never replayed as a spurious completion (the
+        // v0.14.23 stale-handback regression stays fixed).
+        tails.set(agentId, { cursor: fileSize, pendingPartial: '', hasEmittedStart: false, watcher: null })
+        if (doneAtBoot) {
+          // Mirror the done-at-boot branch of the full path (below), minus the
+          // whole-transcript parse: suppress a spurious completion notification
+          // and schedule the terminal cleanup so the feed row is swept.
+          entry.state = 'done'
+          entry.completionNotified = true
+          log?.(`subagent-watcher: ${agentId} done at boot but stale (last write ${Math.round(fileAgeMs / 1000)}s ago > ${Math.round(inflightPromoteMaxAgeMs / 1000)}s) — historical; scheduling terminal cleanup (bounded tail probe, no whole-transcript parse, no watcher)`)
+          scheduleTerminalCleanup(agentId)
+        } else {
+          log?.(`subagent-watcher: ${agentId} running at boot but stale (last write ${Math.round(fileAgeMs / 1000)}s ago > ${Math.round(inflightPromoteMaxAgeMs / 1000)}s) — leaving historical, skipping reconcile read (dead prior-session worker, not in-flight; no whole-transcript parse, no backfill, no watcher)`)
+        }
+        return
+      }
+    }
+
     // Backfill jsonl_agent_id linkage. The PreToolUse hook inserts the row
     // keyed on tool_use_id and doesn't know the JSONL stem yet (the JSONL
     // doesn't exist when PreToolUse fires). We bridge that gap here: read
@@ -2950,6 +3117,22 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
         terminatedAgentIds.delete(agentId)
         historicalFiles.delete(filePath)
         knownFiles.add(filePath)
+        // Issue #3373: the worker-activity feed latched a terminal `finalized`
+        // gate for this agentId at its genuine completion, so the `onProgress`
+        // cues the re-registration is about to re-fire would be SWALLOWED and no
+        // card would re-surface. Fire onResume FIRST (before registerAgent, whose
+        // initial read can synchronously re-emit onProgress) so the gateway clears
+        // that gate; the subsequent live cue then repaints a fresh row. Fired only
+        // on growth-past-terminal — never for a static leftover (the
+        // `currentSize <= terminalSize` continue above), so the anti-zombie latch
+        // still blocks genuinely-finished workers.
+        if (config.onResume != null) {
+          try {
+            config.onResume(agentId, registry.get(agentId)?.description ?? 'sub-agent')
+          } catch (cbErr) {
+            log?.(`subagent-watcher: onResume callback error ${agentId}: ${(cbErr as Error).message}`)
+          }
+        }
         registerAgent(filePath, agentId, terminalSize)
         continue
       }

package/telegram-plugin/tests/activity-card-wiring.test.ts

@@ -20,6 +20,11 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+// #2996 P4-B: drainActivitySummary (the card-OPEN persist site) and
+// clearActivitySummary (the normal-CLOSE clear site) moved VERBATIM into
+// narrative-lane.ts (bodies indented +2 inside the factory — multi-line
+// markers below use the lane spelling).
+const laneSrc = readFileSync(resolve(__dirname, '..', 'gateway', 'narrative-lane.ts'), 'utf-8')
 
 function between(src: string, startMarker: string, endMarker: string): string {
   const after = src.split(startMarker)[1] ?? ''
@@ -30,7 +35,7 @@ describe('activity-card durability wiring', () => {
   it('the card-OPEN path persists the durable handle (writeActivityCardRecord)', () => {
     // The open branch runs when activityMessageId transitions null → set.
     const openBranch = between(
-      gatewaySrc,
+      laneSrc,
       'if (turn.activityMessageId == null) {',
       'turn.activityLastSentRender = target',
     )
@@ -55,8 +60,8 @@ describe('activity-card durability wiring', () => {
 
   it('the normal-CLOSE path clears the durable handle, id-scoped (reap-race guard)', () => {
     const closeBody = between(
-      gatewaySrc,
-      'const id = turn.activityMessageId\n    turn.activityMessageId = null',
+      laneSrc,
+      'const id = turn.activityMessageId\n      turn.activityMessageId = null',
       'if (CLEAR_STATUS_ON_COMPLETION)',
     )
     expect(closeBody.length).toBeGreaterThan(50)