switchroom 0.19.4 → 0.19.6

package/telegram-plugin/gateway/gateway.ts

@@ -243,6 +243,7 @@ import {
   distinctRequestIds,
 } from './permission-rearm.js'
 import { sweepPermissionTtl } from './permission-ttl-sweep.js'
+import { hangStalenessMs } from './hang-restart-decision.js'
 import { createMissedApprovalsStore, type MissedApproval } from './missed-approvals-store.js'
 import {
   createAlwaysAllowPersistQueue,
@@ -437,6 +438,7 @@ const REPLY_TO_TEXT_MAX = 200
 // (`silentEndFallbackText`, imported above) so the transport-boundary
 // tests exercise the real string — see PR #2892.
 import { splitMarkdownChunks, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { formatSwitchroomOutput, stripAnsi, escapeHtmlForTg, preBlock, getCommandArgs, hasDemoFlag, assertSafeAgentName, formatAuthOutputForTelegram, buildAuthUrlKeyboard, buildDeferredSecretKeyboard, renderVaultOpFailure, statusIcon, renderAuthCodeOutcome, buildDoctorScopeKeyboard, formatDoctorReport } from './command-format.js'
 import { richMessage } from '../rich-send.js'
 import { decideRedeliver, decideRedeliverCapture } from './redelivery-decision.js'
 import { scrubVoice } from '../text-voice-scrub.js'
@@ -483,8 +485,11 @@ import {
 } from '../turn-flush-safety.js'
 import {
   resolveReplyOwnerTurnId,
+  resolveReplyOwnerTier,
+  type ReplyOwnerTier,
   type AnswerDeliveredLatch,
 } from '../reply-owner-resolve.js'
+import { SubagentHandbackMarker } from './subagent-handback-marker.js'
 // PR A — deterministic answer-ready quiescence flush (late-delivery fix).
 import {
   AnswerReadyFlushController,
@@ -898,6 +903,7 @@ import {
   TURN_ACTIVE_HARD_TTL_MS,
   TURN_ACTIVE_IDLE_SWEEP_MS,
 } from './turn-active-marker.js'
+import { startGatewayHeartbeat } from './gateway-heartbeat.js'
 import {
   VERSION,
   COMMIT_SHA,
@@ -953,7 +959,7 @@ import {
 import { findAgentProcessInContainer } from './boot-probes.js'
 import { applySubagentsSchema, getSubagentByJsonlId, resolveSubagentOriginTurnKey, listNonTerminalSubagentsForTurn } from '../registry/subagents-schema.js'
 import type { InterruptedSubagent } from './resume-inbound-builder.js'
-import { resolveWorkerFeedDispatch, handleWorkerResume, type WorkerFeedDispatch } from './worker-feed-dispatch.js'
+import { resolveWorkerFeedDispatch, decideWorkerFeedDestination, handleWorkerResume, type WorkerFeedDispatch } from './worker-feed-dispatch.js'
 import {
   resolveSubagentStatusSurface,
   isOrphanSubagentStatusEnabled,
@@ -2180,6 +2186,29 @@ const WORKER_FEED_GROUP_MESSAGE_LIFETIME_CAP_MS = (() => {
 })()
 const workerFeedOwnerDmFallbackLogged = new Set<string>()
 
+// Once-per-agent owner-DM-fallback routing line (bounded FIFO set). Shared by
+// `resolveWorkerFeedChat` and the origin-defer paint path so both log alike.
+function noteWorkerFeedOwnerDmFallback(agentId: string): void {
+  if (workerFeedOwnerDmFallbackLogged.has(agentId)) return
+  workerFeedOwnerDmFallbackLogged.add(agentId)
+  if (workerFeedOwnerDmFallbackLogged.size > WORKER_FEED_FALLBACK_LOG_CAP) {
+    const oldest = workerFeedOwnerDmFallbackLogged.values().next().value
+    if (oldest != null) workerFeedOwnerDmFallbackLogged.delete(oldest)
+  }
+  process.stderr.write(
+    `telegram gateway: worker-feed origin unresolved agent=${agentId} — routing card to owner DM\n`,
+  )
+}
+
+// Per-agent consecutive origin-race deferrals (rationale in
+// `decideWorkerFeedOriginDefer`, worker-feed-dispatch.ts). Bounds the wait for
+// the `jsonl_agent_id` backfill; deleted on link, card-exists, and finish/drop
+// so the map stays bounded.
+const workerFeedOriginDeferrals = new Map<string, number>()
+// Watcher ticks ~1/s and the backfill retries ~every 3s, so ~10 ticks is a
+// comfortable ceiling on the race window before painting anyway.
+const WORKER_FEED_ORIGIN_DEFER_MAX = 10
+
 /**
  * Resolve a worker-feed destination chat with a guaranteed last resort.
  *
@@ -2202,28 +2231,20 @@ const workerFeedOwnerDmFallbackLogged = new Set<string>()
 function resolveWorkerFeedChat(
   agentId: string,
   fleetChatId: string,
+  // Origin sources threadId; when origin is null the caller can pass the
+  // fallback chat's sibling forum-topic id so a misrouted card still lands
+  // in the origin topic instead of General (#3458 exhausted-defer paint).
+  fallbackThreadId?: number,
 ): { chatId: string; threadId?: number } {
   const origin = resolveSubagentOriginChat(agentId)
   if (origin != null && origin.chatId.length > 0) return origin
-  if (fleetChatId.length > 0) return { chatId: fleetChatId }
+  if (fleetChatId.length > 0) return { chatId: fleetChatId, threadId: fallbackThreadId }
   const ownerDm = loadAccess().allowFrom[0] ?? ''
   if (origin == null && fleetChatId.length === 0 && ownerDm.length > 0) {
-    // Routing decision, not a warning: origin resolution failed and no
-    // fleet chat is configured, so the nested worker's card lands in the
-    // owner DM. Logged ONCE per agent so the misroute is auditable
-    // without spamming every tick (the watcher drives onProgress ~1/s).
-    if (!workerFeedOwnerDmFallbackLogged.has(agentId)) {
-      workerFeedOwnerDmFallbackLogged.add(agentId)
-      if (workerFeedOwnerDmFallbackLogged.size > WORKER_FEED_FALLBACK_LOG_CAP) {
-        const oldest = workerFeedOwnerDmFallbackLogged.values().next().value
-        if (oldest != null) workerFeedOwnerDmFallbackLogged.delete(oldest)
-      }
-      process.stderr.write(
-        `telegram gateway: worker-feed origin unresolved agent=${agentId} — routing card to owner DM\n`,
-      )
-    }
+    // Origin unresolved and no fleet chat — the card lands in the owner DM.
+    noteWorkerFeedOwnerDmFallback(agentId)
   }
-  return { chatId: ownerDm, threadId: origin?.threadId }
+  return { chatId: ownerDm, threadId: origin?.threadId ?? fallbackThreadId }
 }
 
 // ─── Periodic history reaper (#1073) ──────────────────────────────────────
@@ -2311,6 +2332,13 @@ function checkApprovals(): void {
   }
 }
 if (isGatewayMain && !STATIC) setInterval(checkApprovals, 5000).unref()
+// Gateway liveness heartbeat — touches `<STATE_DIR>/gateway-heartbeat` while
+// the gateway lives so the silent-end Stop hook's single-writer election can
+// confirm the gateway is alive (and WILL run its turn_end delivery) before
+// electing to allow a turn to end without re-prompting. Allowing into a dead
+// gateway would drop the answer — the one outcome worse than a duplicate. See
+// gateway/gateway-heartbeat.ts + hooks/silent-end-scan.mjs.
+if (isGatewayMain && !STATIC) startGatewayHeartbeat(STATE_DIR)
 // Idle auto-clear: check wall-clock idle every minute; maybeIdleClear no-ops
 // when disabled ('0s'), mid-turn, or already cleared this idle period. The
 // `let` state + maybeIdleClear are hoisted/initialized before this fires.
@@ -3860,6 +3888,14 @@ const recentTurnsById = new Map<string, CurrentTurn>()
 // real message_id the framework stamped, never a model-asserted thread.
 // Evicted in lock-step with recentTurnsById so it can't outgrow it.
 const recentTurnIdBySourceMessageId = new Map<number, string>()
+
+// fix/backstop-duplicate-reply — per-chat marker of the most recent
+// gateway-synthesized `subagent_handback` enqueue (logic in
+// subagent-handback-marker.ts; extracted per the gateway anti-inflation ratchet).
+const subagentHandbackMarker = new SubagentHandbackMarker()
+const getLastSubagentHandbackAt = (chatId: string): number | null =>
+  subagentHandbackMarker.lastAt(chatId)
+
 function rememberRecentTurn(turn: CurrentTurn): void {
   recentTurnsById.set(turn.turnId, turn)
   if (turn.sourceMessageId != null) {
@@ -3984,7 +4020,7 @@ function resolveReplyOwnerTurn(
   liveTurn: CurrentTurn | null,
   chatId: string,
   args: Record<string, unknown>,
-): CurrentTurn | null {
+): { turn: CurrentTurn | null; tier: ReplyOwnerTier } {
   const origin = findTurnByOriginId(args.origin_turn_id as string | undefined)
   const quoted = findTurnByQuotedMessageId(chatId, args.reply_to)
   const latestEnded = findLatestEndedTurnForChat(chatId)
@@ -4001,15 +4037,23 @@ function resolveReplyOwnerTurn(
   // fabricate one.
   const latestEndedAgeMs =
     latestEnded?.endedAt != null ? Date.now() - latestEnded.endedAt : null
-  const winnerId = resolveReplyOwnerTurnId({
+  const candidates = {
     liveTurnId: liveTurn?.turnId ?? null,
     originTurnId: origin?.turnId ?? null,
     quotedTurnId: quoted?.turnId ?? null,
     latestEndedTurnId: latestEnded?.turnId ?? null,
     latestEndedAgeMs,
     latestEndedTtlMs: DEFAULT_SUPERSEDE_TTL_MS,
-  })
-  return winnerId != null ? (byId.get(winnerId) ?? null) : null
+  }
+  // #3429 — the WINNING tier travels with the turn. A positive tier
+  // (live/origin/quoted) means the reply is this turn's own answer and the
+  // supersede fires regardless of text; the ambiguous `latest-ended` fallback
+  // keeps the content gate (it cannot tell a late own-reply from an async
+  // sub-agent handback). Both derive from the SAME candidates, so the id and the
+  // tier can never disagree.
+  const tier = resolveReplyOwnerTier(candidates)
+  const winnerId = resolveReplyOwnerTurnId(candidates)
+  return { turn: winnerId != null ? (byId.get(winnerId) ?? null) : null, tier }
 }
 
 /**
@@ -9674,6 +9718,15 @@ function gatewayLivenessWiringDeps() {
     trackRedeliveredInbound,
     closeActivityLane,
     closeProgressLane,
+    // Stage B: escalate a mid-tool + marker-stale fallback to a real restart.
+    // No cooldown (see hang-restart-decision.ts § STORM GUARD): the ask-first
+    // resume_watchdog_timeout path is the sole, sufficient storm guard.
+    hangRestart: {
+      stalenessThresholdMs: hangStalenessMs(),
+      request: (reason: string, idleMs: number) => {
+        triggerSelfRestart(getMyAgentName(), `hang-watchdog:${reason} idle=${Math.round(idleMs)}ms`)
+      },
+    },
   }
 }
 export type LivenessWiringDeps = ReturnType<typeof gatewayLivenessWiringDeps>
@@ -9928,6 +9981,10 @@ const pendingInboundBuffer = createPendingInboundBuffer({
       { chat_id: chat, verb: 'inbound-buffer-eviction' },
     )
   },
+  // fix/backstop-duplicate-reply MUST-FIX 2 — stamp the handback marker at the
+  // enqueue chokepoint so a boot-replayed handback (not just the live synthesis
+  // push) populates it. Every `subagent_handback` push funnels through here.
+  onHandbackEnqueue: (chatId, ts) => subagentHandbackMarker.record(chatId, ts),
 })
 
 // PR2 obligation-ledger idle sweep. Re-present an OPEN obligation only at a
@@ -12533,6 +12590,7 @@ function gatewaySendReplyDeps(): SendReplyGatewayDeps {
     resolveAnswerThreadWithLog,
     resolveThreadId,
     getLatestInboundMessageId,
+    getLastSubagentHandbackAt,
     recordOutbound,
     emissionAuthorityFor,
     clearActivitySummary,
@@ -15654,25 +15712,6 @@ function switchroomExecCombined(args: string[], timeoutMs = 15000): string {
   })
 }
 
-// Default truncation budget for CLI output bound for Telegram. The rich-message
-// wire cap is RICH_MESSAGE_MAX_CHARS (32768) post-#2669, not the legacy 4096
-// plain-text limit. Mirrors shared/bot-runtime.ts formatSwitchroomOutput.
-function formatSwitchroomOutput(output: string, maxLen = RICH_MESSAGE_MAX_CHARS): string {
-  const trimmed = output.trim()
-  if (trimmed.length <= maxLen) return trimmed
-  return trimmed.slice(0, maxLen - 20) + '\n... (truncated)'
-}
-
-function stripAnsi(text: string): string {
-  return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')
-}
-
-// #2669: escape GFM-markdown specials in dynamic values interpolated into
-// rich-message bodies (kept under the legacy name to avoid churn).
-function escapeHtmlForTg(text: string): string {
-  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
-}
-
 // #789 — button-choice-confirmation ("✅ You chose: X") annotation state.
 //
 // Two once-per-process warning dedupe sets keyed by agent slug: one for the
@@ -15684,11 +15723,6 @@ function escapeHtmlForTg(text: string): string {
 const buttonConfirmParseModeWarned = new Set<string>()
 const buttonConfirmSingleUseWarned = new Set<string>()
 
-// Wrap CLI/command output in a fenced code block (content is literal there).
-function preBlock(text: string): string {
-  return '```\n' + text.replace(/```/g, '`​``') + '\n```'
-}
-
 type SwitchroomReplyMarkup =
   | InlineKeyboard
   | { force_reply: true; input_field_placeholder?: string; selective?: boolean }
@@ -15785,36 +15819,6 @@ async function deleteSensitiveMessage(
   }
 }
 
-function getCommandArgs(ctx: Context): string {
-  const fromMatch = typeof ctx.match === 'string' ? ctx.match.trim() : ''
-  if (fromMatch) return fromMatch
-  const text = (ctx.msg as { text?: string } | undefined)?.text ?? (ctx.message as { text?: string } | undefined)?.text ?? ''
-  const m = text.match(/^\/\S+\s+([\s\S]*)$/)
-  return m ? m[1].trim() : ''
-}
-
-/**
- * True when a slash command's argument string carries a trailing `demo`
- * token — the per-command PII-mask modifier for screen recordings
- * (`/usage demo`, `/auth demo`, `/status demo`, `/whoami demo`). Matches
- * `demo` as the last whitespace-delimited token, case-insensitively, so
- * `/auth show demo` and `/usage demo` both flip the flag while a label
- * literally named `demo-foo` does not.
- */
-function hasDemoFlag(args: string): boolean {
-  return /(?:^|\s)demo$/i.test(args.trim())
-}
-
-/** Validate that a string looks like a safe agent/resource name.
- *  Agent names should be alphanumeric with hyphens/underscores only.
- *  This prevents shell metacharacter injection even though both exec
- *  functions already handle quoting. Defense in depth. */
-function assertSafeAgentName(name: string): void {
-  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name) && name !== 'all') {
-    throw new Error(`invalid agent name: ${name}`)
-  }
-}
-
 /**
  * Expand the special `all` keyword into the real agent list for restart-
  * driving. The CLI handles its own expansion for the YAML mutation; this
@@ -16389,114 +16393,6 @@ function scheduleGrantRestart(
  * if the inline button ever fails to render (old client, unusual scope)
  * the user still has a copy-paste-able URL.
  */
-function formatAuthOutputForTelegram(output: string): { text: string; url: string | null } {
-  const trimmed = stripAnsi(output).trim()
-  const url = trimmed.match(/https:\/\/\S+/)?.[0] ?? null
-  const lines = trimmed.split(/\n+/).map(l => l.trim()).filter(Boolean)
-  if (!url) return { text: preBlock(formatSwitchroomOutput(trimmed)), url: null }
-  // Drop the `switchroom auth code ...` and `switchroom auth cancel ...`
-  // CLI hints. In Telegram the user never types those — they just reply
-  // with the code (intercepted by the pendingReauthFlows flow above) or
-  // tap the inline button. Surfacing shell syntax is confusing noise on
-  // a phone.
-  const body = lines.filter(line => {
-    if (line === url) return false
-    if (line.startsWith('switchroom auth code')) return false
-    if (line.startsWith('switchroom auth cancel')) return false
-    if (line.startsWith("Use 'tmux attach")) return false
-    if (line.startsWith('After Claude shows you a browser code')) return false
-    if (line.startsWith('Then finish with:')) return false
-    if (line.startsWith('Cancel with:')) return false
-    return true
-  })
-  const rendered = body.map(line => {
-    if (line.startsWith('Started Claude auth') || line.startsWith('Auth session already running')) return `**${escapeHtmlForTg(line)}**`
-    if (line.startsWith('Open this URL')) return `_${escapeHtmlForTg(line)}_`
-    return escapeHtmlForTg(line)
-  })
-  // Mobile-native post-script. Two paths depending on which Anthropic
-  // account the user wants to authorize:
-  //
-  //   (a) Button: 🔐 Open Claude auth — opens in Telegram's in-app
-  //       browser (WebView) on most mobile clients. WebView has its
-  //       own cookie jar, separate from the user's main browser. Fine
-  //       when the WebView is already signed into the intended Claude
-  //       account; wrong when it's signed into a different one.
-  //
-  //   (b) Long-press the URL text at the bottom of this message — every
-  //       mobile Telegram client exposes "Copy Link" / "Open in
-  //       Browser" / "Open in Chrome" on long-press. That's the
-  //       escape hatch when you need to land in your main browser
-  //       where you control which account is signed in.
-  //
-  // Why not a copy_text button? We tried. Telegram's CopyTextButton.text
-  // field caps at 256 chars and OAuth URLs run ~320–340 chars. Result
-  // was BUTTON_COPY_TEXT_INVALID. The long-press-the-URL path achieves
-  // the same outcome with no API constraint. See PR #30.
-  rendered.push(
-    '',
-    '👇 Tap **🔐 Open Claude auth** below, then **reply with the browser code**.',
-    '',
-    '_Wrong Anthropic account getting authorized? Long-press the URL below and choose "Copy Link" or "Open in Browser" — lands in your main browser where the right account is signed in, bypassing Telegram\'s in-app browser cookies._',
-    '',
-    url,
-  )
-  return { text: rendered.join('\n'), url }
-}
-
-/**
- * Build the inline keyboard shown under an auth-flow response that has
- * an OAuth URL. Single button:
- *
- *   [🔐 Open Claude auth]   — `url` button. On mobile Telegram clients
- *                             this typically opens in the app's in-app
- *                             browser (WebView).
- *
- * We previously tried adding a `[📋 Copy URL]` button using Telegram's
- * Bot API 7.7 `copy_text` type but it capped at 256 chars for the
- * copyable text. OAuth URLs (~320–340 chars) exceed that and produce
- * `BUTTON_COPY_TEXT_INVALID`. Instead, the message body renders the
- * URL as a tappable link; users long-press the URL text to get native
- * "Copy Link" / "Open in Browser" actions, bypassing the WebView.
- *
- * Defense in depth: this function's output is validated against
- * Telegram's real field-length constraints in
- * `telegram-plugin/tests/auth-url-keyboard-constraints.test.ts` so
- * future changes that breach a limit fail loudly at CI time rather
- * than silently in production.
- */
-function buildAuthUrlKeyboard(authorizeUrl: string): InlineKeyboard {
-  return new InlineKeyboard().url('🔐 Open Claude auth', authorizeUrl)
-}
-
-/**
- * Issue #44: inline keyboard offering a one-tap unlock-and-save flow for
- * a deferred secret. The two buttons fire `vd:` callback_data which the
- * dispatcher in `bot.on('callback_query:data')` routes to
- * `handleVaultDeferCallback`.
- *
- *   `vd:unlock:<deferKey>` → prompt for passphrase, then auto-write the
- *                            held secret. Replaces the legacy six-step
- *                            "/vault list → re-paste" flow.
- *   `vd:cancel:<deferKey>` → discard the deferred secret without saving.
- *
- * `deferKey` is `<chat_id>:<message_id>` (the same key as
- * `deferredSecrets.set()`). Telegram limits callback_data to 64 bytes;
- * the prefix + key fits well within that on any realistic chat id.
- */
-function buildDeferredSecretKeyboard(deferKey: string): InlineKeyboard {
-  const unlockData = `vd:unlock:${deferKey}`
-  const cancelData = `vd:cancel:${deferKey}`
-  if (unlockData.length > 64 || cancelData.length > 64) {
-    process.stderr.write(
-      `telegram gateway: callback_data overflow — deferKey=${deferKey} unlockLen=${unlockData.length} cancelLen=${cancelData.length}\n`,
-    )
-    throw new Error(`callback_data overflow: deferKey too long (${deferKey.length} chars)`)
-  }
-  return new InlineKeyboard()
-    .text('🔓 Unlock vault & save', unlockData)
-    .text('🗑 Discard', cancelData)
-}
 
 async function runSwitchroomAuthCommand(ctx: Context, args: string[], label: string): Promise<void> {
   try {
@@ -16560,27 +16456,6 @@ function runVaultCli(args: string[], passphrase: string, stdinValue?: string): {
   }
 }
 
-/**
- * Render a vault-CLI failure as Telegram HTML. Routes recognised P0a
- * stderr markers (VAULT-SANDBOX-CONTEXT / VAULT-NEEDS-APPROVAL /
- * VAULT-BROKER-UNREACHABLE / VAULT-BROKER-DENIED) through the structured
- * renderer; falls back to a raw pre-block for anything else.
- */
-function renderVaultOpFailure(
-  verbLabel: 'list' | 'get' | 'set' | 'delete',
-  cliOutput: string,
-  key: string | undefined,
-): string {
-  const parsed = parseVaultCliError(cliOutput)
-  // Map the gateway-internal op label onto the renderer's verb. 'delete'
-  // surfaces in the host hint as `switchroom vault remove <key>` (the
-  // canonical CLI name); 'list' has no key.
-  const verb = verbLabel === 'delete' ? 'remove' : verbLabel
-  const rendered = renderVaultCliError(parsed, { verb, key })
-  if (rendered.suppressRaw) return rendered.html
-  return `**vault ${verbLabel} failed:**\n${preBlock(cliOutput)}`
-}
-
 async function executeVaultOp(ctx: Context, chatId: string, op: 'list' | 'get' | 'set' | 'delete', key: string | undefined, passphrase: string, setValue: string | undefined): Promise<void> {
   if (op === 'list') {
     const r = runVaultCli(['list'], passphrase)
@@ -16713,34 +16588,6 @@ function switchroomExecJson<T = unknown>(args: string[]): T | null {
   } catch { return null }
 }
 
-function statusIcon(status: string): string {
-  if (status === 'active' || status === 'running') return '🟢'
-  if (status === 'inactive' || status === 'stopped' || status === 'dead') return '🔴'
-  if (status === 'failed') return '⚠️'
-  return '⚪'
-}
-
-/**
- * Render an `AuthCodeOutcome` as a user-facing Telegram HTML string.
- * Returns null when the outcome is not present or is `success` (caller
- * can handle success via the existing text path).
- */
-function renderAuthCodeOutcome(outcome: AuthCodeOutcome | null | undefined): string | null {
-  if (!outcome || outcome.kind === 'success') return null
-  const tail = outcome.paneTailText
-    ? `\n_${escapeHtmlForTg(outcome.paneTailText)}_`
-    : ''
-  switch (outcome.kind) {
-    case 'invalid-code':
-    case 'expired-code':
-      return `Code rejected by Claude — tap **Restart flow** for a fresh URL.${tail}`
-    case 'pane-not-ready':
-      return `Auth pane not ready — tap **Retry**.`
-    case 'timeout':
-      return `Still waiting after 2 min — tap **Retry** or check \`switchroom auth list\`.${tail}`
-  }
-}
-
 interface AuthCodeJsonResult {
   completed: boolean
   tokenSaved: boolean
@@ -19212,29 +19059,6 @@ let cardToolHandlers!: ReturnType<typeof createCardToolHandlers>
 
 
 
-// Two-button scope picker shown to admin agents (when hostd is
-// reachable) so the operator can run doctor for the WHOLE FLEET
-// (host-side via hostd — has the docker socket) or just THIS agent
-// (in-container, degraded). callback_data is tiny (`dr:fleet` /
-// `dr:self`) — well within Telegram's 64-byte limit.
-function buildDoctorScopeKeyboard(): InlineKeyboard {
-  return new InlineKeyboard()
-    .text('🩺 Whole fleet', 'dr:fleet')
-    .text('🩺 This agent', 'dr:self')
-}
-
-// Shared report prettifier: ANSI-strip + status-glyph swap + pre block.
-// Identical rendering for the in-container and the hostd fleet report.
-function formatDoctorReport(raw: string): string {
-  const trimmed = stripAnsi(raw).trim()
-  if (!trimmed) return 'doctor: no output'
-  const pretty = trimmed
-    .replace(/^( *)✓ /gm, '$1🟢 ')
-    .replace(/^( *)✗ /gm, '$1🔴 ')
-    .replace(/^( *)! /gm, '$1🟡 ')
-  return preBlock(formatSwitchroomOutput(pretty))
-}
-
 // In-container `switchroom doctor` — this agent's own (degraded: no
 // docker socket) view. The original /doctor behaviour, unchanged.
 async function renderSelfDoctor(ctx: Context): Promise<void> {
@@ -24397,6 +24221,9 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
               // live worker, collapses the shared card to its terminal summary
               // and unpins it — closing the immortal/unpinned/buried-card leak.
               onTerminalCleanup: (agentId) => {
+                // A worker that terminated while still unlinked never links —
+                // clear its origin-race defer state so the map can't leak.
+                workerFeedOriginDeferrals.delete(agentId)
                 try {
                   void workerActivityFeed?.terminate(agentId)
                 } catch (err) {
@@ -24406,6 +24233,8 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 }
               },
               onFinish: ({ agentId, outcome, description, resultText, toolCount, totalTokens, durationMs, background: entryBackground }) => {
+                // Clear origin-race defer state — the worker is terminal.
+                workerFeedOriginDeferrals.delete(agentId)
                 // Reaction promotion: if the parent turn already ended
                 // with this (or another) worker still running, its 👍 was
                 // deferred (held on ✍️/⚡). Now that a worker finished,
@@ -24653,6 +24482,9 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // The drain only releases at an idle prompt (no active
                 // turn), so the handback always lands as a clean fresh
                 // turn and never races a turn-in-flight composer (#1556).
+                // The handback marker is stamped inside pendingInboundBuffer.push
+                // (the enqueue chokepoint) so BOTH this live synthesis push and
+                // the boot-replay re-push populate it — see MUST-FIX 2.
                 pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? '', decision.inbound)
                 process.stderr.write(
                   `telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${decision.chatId} resultChars=${resultText.length}\n`,
@@ -24890,11 +24722,48 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // resolved (the pinned-card fleet that used to carry the chat
                 // is gone — see resolveSubagentOriginChat).
                 if (workerFeedEnabled) {
-                  const wk = resolveWorkerFeedChat(agentId, fleetChatId)
-                  const wkChat = wk.chatId
+                  // Origin-race defer + destination (decideWorkerFeedDestination,
+                  // worker-feed-dispatch.ts): the first tick of a fresh sub-agent
+                  // can beat the async jsonl_agent_id backfill that links its row
+                  // to the origin turn — origin resolves null and the card would be
+                  // CREATED in the owner DM, staying visible even after the origin
+                  // (supergroup + forum topic) resolves ~3s later. Defer CARD
+                  // CREATION until linked; the watcher re-fires and paints in the
+                  // right chat+topic. The FULL decision (defer-or-paint AND the
+                  // chat/thread resolution `resolveWorkerFeedChat` did) is now one
+                  // pure, unit-tested function; the gateway keeps only the defer-map
+                  // bookkeeping, the two audit logs, and the feed.update.
+                  const dest = decideWorkerFeedDestination({
+                    origin: resolveSubagentOriginChat(agentId),
+                    cardExists: workerActivityFeed?.has(agentId) === true,
+                    priorDeferrals: workerFeedOriginDeferrals.get(agentId) ?? 0,
+                    maxDeferrals: WORKER_FEED_ORIGIN_DEFER_MAX,
+                    fleetChatId,
+                    stampChatId: stampTurn?.sessionChatId,
+                    stampThreadId: stampTurn?.sessionThreadId,
+                    ownerDm: loadAccess().allowFrom[0] ?? '',
+                  })
+                  if (dest.action === 'defer') {
+                    // No card created this tick; the watcher re-fires and paints
+                    // once the jsonl_agent_id backfill links the row to its origin.
+                    workerFeedOriginDeferrals.set(agentId, dest.deferrals)
+                    return
+                  }
+                  // Painting: clear defer state so the map can't leak.
+                  workerFeedOriginDeferrals.delete(agentId)
+                  if (dest.exhausted) {
+                    // Bounded-defer exhausted — backfill never linked (history
+                    // disabled / row reaped / ancestor never stamped). Paint anyway
+                    // so active work stays visible (universal-liveness contract).
+                    process.stderr.write(
+                      `telegram gateway: worker-feed origin backfill never linked agent=${agentId} after ${dest.deferrals} deferrals — painting card\n`,
+                    )
+                  }
+                  // Card fell to the owner DM — log the misroute once per agent.
+                  if (dest.ownerDmFallback) noteWorkerFeedOwnerDmFallback(agentId)
                   void workerActivityFeed?.update(
                     agentId,
-                    wkChat,
+                    dest.chatId,
                     {
                       description: dispatch.feedDescription,
                       lastTool,
@@ -24908,7 +24777,7 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                       model: feedModel,
                       totalTokens,
                     },
-                    wk.threadId,
+                    dest.threadId,
                   )
                   // #3207: the feed pins the group's shared message itself when
                   // it first paints (reconcilePin → `wk:group:<feedKey>`); no