switchroom 0.19.41 → 0.19.43

package/telegram-plugin/gateway/gateway.ts

@@ -280,10 +280,8 @@ import { REPLY_TOOLS } from '../narrative-dedup.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { createTurnTypingLoop } from './turn-typing-loop.js'
-import {
-  createHandbackPreturnSignal,
-  type PreTurnCardRecord,
-} from './handback-preturn-signal.js'
+import { createHandbackPreturnSignal } from './handback-preturn-signal.js'
+import { createHandbackOrphanRecovery } from './handback-orphan-recovery.js'
 import { deriveTurnId } from './derive-turn-id.js'
 import { createTypingEmitter, TYPING_REFRESH_MS } from '../typing-emitter.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
@@ -457,7 +455,7 @@ import {
   type SendReplyGatewayDeps,
   type DeliverCapturedProseDeps,
 } from './outbound-send-path.js'
-import { handleSessionEvent as handleSessionEventCore } from './stream-render.js'
+import { handleSessionEvent as handleSessionEventCore, drainParkedTurnStartsForChat } from './stream-render.js'
 import { createNarrativeLane } from './narrative-lane.js'
 import {
   parseAgentCallback,
@@ -654,6 +652,7 @@ import { startWebhookIngestServer } from './webhook-ingest-server.js'
 import { recordWebhookEvent } from '../../src/web/webhook-gateway-record.js'
 
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
+import { handleRolloutStatusEdit } from './rollout-status-edit.js'
 import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { handleRequestMs365Approval } from './ms365-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
@@ -667,7 +666,7 @@ import {
 } from './obligation-ledger.js'
 // (#2996 P8 PR-C2: buildObligationRepresentInbound is now imported by
 // obligation-wiring.ts, where the sweep lives.)
-import { loadObligations, persistObligations } from './obligation-store.js'
+import { loadObligations, persistObligations, removeUnmaintainedSnapshot } from './obligation-store.js'
 import { buildCapturedDeliverySnapshot, createCapturedResumeDispatcher } from './captured-answer-resume.js'
 import {
   loadStatusPins,
@@ -2804,7 +2803,7 @@ const obligationStoreFs = {
   writeFileSync: (p: string, d: string) => writeFileSync(p, d),
   renameSync: (a: string, b: string) => renameSync(a, b),
   existsSync: (p: string) => existsSync(p),
-  fsyncFileSync: fsyncPathSync, fsyncDirSync: fsyncPathSync,
+  fsyncFileSync: fsyncPathSync, fsyncDirSync: fsyncPathSync, unlinkSync,
 }
 const obligationLedger = new ObligationLedger(OBLIGATION_REPRESENT_MAX, {
   onChange:
@@ -2822,7 +2821,7 @@ if (isGatewayMain && !STATIC && OBLIGATION_LEDGER_ENABLED) {
       `telegram gateway: obligation-ledger hydrated ${restored.length} open obligation(s) from ${OBLIGATION_STORE_PATH}\n`,
     )
   }
-}
+} else if (isGatewayMain) removeUnmaintainedSnapshot(OBLIGATION_STORE_PATH, obligationStoreFs, `static=${STATIC} enabled=${OBLIGATION_LEDGER_ENABLED}`) // #4146: persistence is off, so a leftover snapshot must not read as "nobody is waiting" to the W1-d audience classifier (logic in obligation-store.ts)
 // Origin ids with an escalation send IN FLIGHT — prevents the 5s sweep from
 // firing a second concurrent send for the same obligation while the first is
 // still awaiting (an escalation that takes >5s, or repeated failures).
@@ -9669,14 +9668,14 @@ function gatewayLivenessWiringDeps() {
     turnLiveForItsTopic,
     endCurrentTurnForKey,
     // Getter, not an eager read: `pendingInboundBuffer` (const) is declared
-    // LATER in this module (~9863) than the module-load `startTimer` call that
-    // invokes this builder (isGatewayMain path). A by-value capture here is a
-    // temporal-dead-zone ReferenceError that crash-loops every gateway boot
-    // (#3392 regression). Deferring to a getter — matching getInboundSpool /
-    // getTurnsDb / ipcServer — means the binding is only read when the
-    // fallback actually fires, well after module eval.
+    // LATER than the module-load `startTimer` call that invokes this builder,
+    // so a by-value capture is a temporal-dead-zone ReferenceError that
+    // crash-loops boot (#3392). A getter (matching getInboundSpool / getTurnsDb
+    // / ipcServer) is read only when the fallback fires, well after module eval.
     getPendingInboundBuffer: () => pendingInboundBuffer,
     trackRedeliveredInbound,
+    // Two-state desync unwedge (#3927): drain the parked store the fallback else leaves latched — see liveness-wiring + stream-render drainParkedTurnStartsForChat.
+    drainParkedTurnStarts: (chatId: string, threadId: number | null): number => drainParkedTurnStartsForChat(gatewayStreamRenderDeps(), chatId, threadId != null ? String(threadId) : null).length,
     closeActivityLane,
     closeProgressLane,
     // Stage B: escalate a mid-tool + marker-stale fallback to a real restart.
@@ -10052,7 +10051,7 @@ async function deliverCapturedProse(args: {
   originTurnId: string
   text: string
   /** Turn elapsed for the honest "(waited Ns)" apology clause; optional. */
-  turnDurationMs?: number
+  turnDurationMs?: number; replyToolThrewThisTurn?: boolean // #4141: label prose recovered from a turn whose reply tool threw (see outbound-send-path.ts)
 }): Promise<void> {
   // #2996 P2: body moved VERBATIM to outbound-send-path.ts (single tested
   // send module). Injects the ONE `outboundDedup` instance (Amendment 1/9).
@@ -11447,28 +11446,31 @@ if (isGatewayMain) ipcServer = createIpcServer({
     }
   },
 
-  // #2726 Part 2 — edit the previously-posted rollout status message in place as
-  // later phases arrive. Fire-and-forget: an edit failure (incl. Telegram 429)
-  // is swallowed here and NEVER surfaced back toward the roll. hostd owns the
-  // debounce + 429 retry cadence; this handler is a thin edit relay.
-  onRolloutStatusEdit(_client: IpcClient, msg: RolloutStatusEditMessage) {
-    const self = process.env.SWITCHROOM_AGENT_NAME
-    if (self && msg.agentName !== self) {
-      process.stderr.write(
-        `telegram gateway: rollout_status_edit rejected — agent mismatch (${msg.agentName} != ${self})\n`,
-      )
-      return
-    }
-    const operator = loadAccess().allowFrom[0]
-    if (operator === undefined) {
-      process.stderr.write(`telegram gateway: rollout_status_edit — no operator chat (allowFrom empty)\n`)
-      return
-    }
-    void swallowingApiCall(
-      () =>
-        // allow-raw-bot-api: in-place edit of the ordinary status message.
-        bot.api.editMessageText(operator, msg.messageId, richMessage(msg.text), {}),
-      { chat_id: String(operator), verb: 'rollout-status-edit' },
+  // #2726 Part 2 / #4065 — edit the previously-posted rollout status message in
+  // place as later phases arrive, and REPLY with the outcome so hostd can tell
+  // an applied edit from an edit into a deleted card (see rollout-status-edit.ts).
+  // Still fire-and-forget toward the roll: hostd never blocks on the reply.
+  onRolloutStatusEdit(client: IpcClient, msg: RolloutStatusEditMessage) {
+    return handleRolloutStatusEdit(
+      {
+        selfAgentName: process.env.SWITCHROOM_AGENT_NAME,
+        operatorChatId: () => loadAccess().allowFrom[0],
+        editMessage: (chatId, messageId, text) =>
+          robustApiCall(
+            () =>
+              // allow-raw-bot-api: in-place edit of the ordinary status message.
+              bot.api.editMessageText(chatId, messageId, richMessage(text), {}),
+            // BOTH opt-outs are load-bearing — see "TWO swallows" in
+            // rollout-status-edit.ts. A SHED edit and a SWALLOWED benign
+            // `400 message to edit not found` each resolve WITHOUT throwing,
+            // and the handler reads success from the absence of a throw.
+            { chat_id: String(chatId), verb: 'rollout-status-edit',
+              priorityClass: 'critical', rethrowBenign400: true },
+          ),
+        log: (m) => process.stderr.write(`telegram gateway: ${m}\n`),
+      },
+      client,
+      msg,
     )
   },
 
@@ -13743,8 +13745,6 @@ if (isGatewayMain && !STATIC && FEED_HEARTBEAT_ENABLED) {
 // closes. Kill switch: SWITCHROOM_HANDBACK_PRETURN=0.
 const HANDBACK_PRETURN_ENABLED = !STATIC && process.env.SWITCHROOM_HANDBACK_PRETURN !== '0'
 const HANDBACK_PRETURN_HTML = '🤝 Reading the worker’s results…'
-const HANDBACK_PRETURN_ORPHAN_HTML =
-  '🤝 A background worker finished, but the handback never started — it may need a nudge.'
 
 async function openHandbackPreTurnCard(
   chatId: string,
@@ -13774,24 +13774,20 @@ async function openHandbackPreTurnCard(
   }
 }
 
-function finalizeHandbackPreTurnCard(record: PreTurnCardRecord): Promise<void> {
-  return robustApiCall(
-    () =>
-      bot.api.editMessageText(
-        record.chatId,
-        record.activityMessageId,
-        richMessage(HANDBACK_PRETURN_ORPHAN_HTML),
-        {},
-      ),
-    {
-      chat_id: record.chatId,
-      ...(record.threadId != null ? { threadId: record.threadId } : {}),
-      verb: 'handback-preturn.orphan-finalize',
-    },
-  )
-    .then(() => undefined)
-    .catch(() => undefined)
-}
+// Deterministic recovery for a genuinely-orphaned handback: delete the frozen
+// pre-turn card, re-inject the handback through the pending-inbound buffer, and
+// past the retry cap emit fleet-health telemetry — never an operator-facing
+// "needs a nudge" card. See handback-orphan-recovery.ts.
+const handbackOrphanRecovery = createHandbackOrphanRecovery({
+  deleteMessage: (chatId, messageId, threadId) =>
+    robustApiCall(() => bot.api.deleteMessage(chatId, messageId), {
+      chat_id: chatId,
+      ...(threadId != null ? { threadId } : {}),
+      verb: 'handback-preturn.orphan-delete',
+    }),
+  pushInbound: (inbound) =>
+    pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? '', inbound),
+})
 
 const handbackPreturnSignal = createHandbackPreturnSignal({
   chatKey: (chatId, threadId) => chatKey(chatId, threadId) as string,
@@ -13799,7 +13795,9 @@ const handbackPreturnSignal = createHandbackPreturnSignal({
   startTypingLoop: (chatId, threadId) => startTurnTypingLoop(chatId, threadId),
   stopTypingLoop: (chatId, threadId) => stopTurnTypingLoop(chatId, threadId),
   openCard: openHandbackPreTurnCard,
-  finalizeCard: finalizeHandbackPreTurnCard,
+  deleteCard: handbackOrphanRecovery.deleteCard,
+  reinjectHandback: handbackOrphanRecovery.reinjectHandback,
+  escalateOrphan: handbackOrphanRecovery.escalateOrphan,
   writeCardRecord: (record) => {
     if (!activityCardPersistEnabled) return
     writeActivityCardRecord(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs, record)

package/telegram-plugin/gateway/handback-orphan-recovery.ts

@@ -0,0 +1,69 @@
+/**
+ * handback-orphan-recovery.ts — the gateway-side EFFECTS for deterministic
+ * recovery of a genuinely-orphaned sub-agent handback.
+ *
+ * The decision ("is this an orphan, should it be re-injected, has it exhausted
+ * its retries") lives in `handback-preturn-signal.ts`. This module owns only the
+ * three side effects that decision drives, so they live in a module instead of
+ * inline in gateway.ts (switchroom#2996 anti-inflation ratchet — new logic goes
+ * into a seam, not into the 24k-line gateway):
+ *
+ *   1. `deleteCard`       — DELETE (never edit) the frozen pre-turn card. The
+ *      old behaviour rewrote it to an operator-facing string asking a human to
+ *      manually nudge a system that must recover itself. That string is gone
+ *      from the codebase; the card is removed outright.
+ *   2. `reinjectHandback` — push the handback back through the pending-inbound
+ *      buffer (the same path live synthesis + boot replay use) so the idle drain
+ *      re-delivers it and the machine re-processes it. The seam stamps the retry
+ *      counter on `inbound.meta` before calling this, so the cap survives the
+ *      round trip.
+ *   3. `escalateOrphan`   — retries exhausted → fleet-health TELEMETRY, never a
+ *      chat card. A structured line on the gateway log that the nightly
+ *      fleet-health sensor (`src/fleet-health/scan.ts`) reads; the
+ *      `handback orphan escalation` marker is greppable and carries the join key.
+ *
+ * Every effect is injected, so the contract is asserted by a unit test with spy
+ * transports (`tests/handback-orphan-recovery.test.ts`) rather than by reading
+ * gateway.ts.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+import type { HandbackOrphanEscalation, PreTurnCardRecord } from './handback-preturn-signal.js'
+
+export interface HandbackOrphanRecoveryDeps {
+  /** Delete a message. The gateway supplies its `robustApiCall`-wrapped
+   *  `bot.api.deleteMessage`; rejections are swallowed here (best-effort). */
+  deleteMessage: (chatId: string, messageId: number, threadId: number | null) => Promise<unknown>
+  /** The gateway's `pendingInboundBuffer.push`, pre-bound to this agent. */
+  pushInbound: (inbound: InboundMessage) => void
+  /** Telemetry sink. Defaults to the gateway log (stderr). */
+  writeLog?: (line: string) => void
+}
+
+/** Structured, greppable telemetry line for an exhausted-retry orphan. Exported
+ *  so the test asserts the exact marker + join keys the fleet-health sensor
+ *  greps for, not just that "something was logged". */
+export function formatOrphanEscalation(esc: HandbackOrphanEscalation): string {
+  return (
+    `telegram gateway: handback orphan escalation key=${esc.statusKey} ` +
+    `turnId=${esc.adoptTurnId} reinjects=${esc.reinjectCount} ageMs=${esc.ageMs} ` +
+    `— deterministic recovery exhausted, no operator nudge issued\n`
+  )
+}
+
+export function createHandbackOrphanRecovery(deps: HandbackOrphanRecoveryDeps): {
+  deleteCard: (record: PreTurnCardRecord) => Promise<void>
+  reinjectHandback: (inbound: InboundMessage) => void
+  escalateOrphan: (escalation: HandbackOrphanEscalation) => void
+} {
+  const writeLog = deps.writeLog ?? ((line: string) => void process.stderr.write(line))
+  return {
+    deleteCard: (record) =>
+      deps
+        .deleteMessage(record.chatId, record.activityMessageId, record.threadId)
+        .then(() => undefined)
+        .catch(() => undefined),
+    reinjectHandback: (inbound) => deps.pushInbound(inbound),
+    escalateOrphan: (esc) => writeLog(formatOrphanEscalation(esc)),
+  }
+}

package/telegram-plugin/gateway/handback-preturn-signal.ts

@@ -105,6 +105,29 @@ import type { InboundMessage } from './ipc-protocol.js'
  *  the seam's `handleReaped` hook (stop typing loop + drop map entry). */
 export const PRETURN_TURNKEY_PREFIX = 'preturn:'
 
+/** `meta` key carrying the deterministic-recovery re-injection counter across a
+ *  re-injected handback's round trip through the pending-inbound buffer. Stamped
+ *  on the inbound just before it is re-injected on a genuine orphan; read back
+ *  when that same inbound is released again, so the retry cap survives the
+ *  drop-and-recreate of the per-topic pre-turn entry. `meta` is
+ *  `Record<string,string>`, so the count is stored as a decimal string. */
+export const HANDBACK_REINJECT_COUNT_META_KEY = 'handbackReinjectCount'
+
+/** Emitted (NOT to chat) when a genuine orphan has exhausted its re-injection
+ *  retries — the deterministic-recovery escalation surface. The gateway routes
+ *  this to fleet-health telemetry (a structured log line the nightly sensor
+ *  reads), never to an operator-facing card: the system must recover itself, not
+ *  ask a human to nudge it. */
+export interface HandbackOrphanEscalation {
+  statusKey: string
+  chatId: string
+  threadId: number | null
+  adoptTurnId: string
+  reinjectCount: number
+  /** Age (ms) of the handback at escalation — release → escalation. */
+  ageMs: number
+}
+
 /** True IFF `source` is the load-bearing subagent-handback source string. Kept
  *  here next to the seam so a source-string regression is caught by this
  *  module's own test, not only the inbound-builder's. */
@@ -162,9 +185,21 @@ export interface HandbackPreturnSignalDeps {
    *  when the send failed / was suppressed (best-effort — a null just means no
    *  card was painted, so nothing to adopt or reap). */
   openCard: (chatId: string, threadId: number | null) => Promise<number | null>
-  /** Finalize (single honest edit) a frozen never-adopted pre-turn card on
-   *  orphan self-reap. Best-effort; failures swallowed by the caller. */
-  finalizeCard: (record: PreTurnCardRecord) => void | Promise<void>
+  /** DELETE (not edit) a never-adopted pre-turn card. Used on the genuine-orphan
+   *  reap so the frozen card is removed rather than rewritten to a stale
+   *  user-facing "needs a nudge" message, and on the rare emit-race teardown of a
+   *  card the adopting turn already owns. Best-effort; failures swallowed by the
+   *  caller. */
+  deleteCard: (record: PreTurnCardRecord) => void | Promise<void>
+  /** Re-inject a genuinely-orphaned handback back through the pending-inbound
+   *  buffer so the machine recovers itself — the deterministic alternative to
+   *  asking the operator to nudge. The gateway's `pendingInboundBuffer.push`. The
+   *  seam stamps `HANDBACK_REINJECT_COUNT_META_KEY` on `inbound.meta` first so the
+   *  retry cap survives the round trip. */
+  reinjectHandback: (inbound: InboundMessage) => void
+  /** Escalate a genuine orphan that has exhausted its re-injection retries to
+   *  fleet-health telemetry (NOT a chat card). */
+  escalateOrphan: (escalation: HandbackOrphanEscalation) => void
   /** Persist the durable card record (the gateway's `writeActivityCardRecord`,
    *  scoped by `turnKey`). */
   writeCardRecord: (record: PreTurnCardRecord) => void
@@ -190,16 +225,18 @@ export interface HandbackPreturnSignalDeps {
    *  handback is delivered into that single queue and only mints its adopting
    *  turn when claude next goes idle, so while claude is busy the handback is
    *  NOT orphaned — it is correctly enqueued BEHIND the in-flight turn (a long
-   *  parent turn can run many minutes). Finalizing it as an orphan in that
-   *  window posts a false "never started — needs a nudge" card. The reap
-   *  therefore DEFERS (re-arms) while this is true and finalizes only once
-   *  claude is idle and the handback still has not been adopted — the genuine
-   *  bridge-death / dropped-inbound degenerate case the reap exists for.
-   *  Distinct from `hasLiveTurn`, which is PER-KEY and only governs the
-   *  typing-loop stop; this is the GLOBAL busy signal because the handback
-   *  queues behind whatever turn is running, regardless of topic. Optional;
-   *  defaults to "not busy" (immediate reap — the pre-fix behaviour), so the
-   *  genuine-orphan path is unchanged. */
+   *  parent turn can run many minutes). Reaping it as an orphan in that window
+   *  used to post a false "never started — needs a nudge" card (the 3-cards-in-
+   *  4-min incident). The reap therefore DEFERS (re-arms) while this is true —
+   *  and, complementarily, while the handback was delivered but its turn has not
+   *  started streaming yet (`deliveredAwaitingTurnStart`, the #4027 coverage
+   *  gap) — recovering only once claude is idle AND the delivered window has
+   *  elapsed AND the handback still has not been adopted (the genuine bridge-
+   *  death / dropped-inbound case). Recovery is deterministic (delete the frozen
+   *  card + re-inject, then escalate), never an operator nudge. Distinct from
+   *  `hasLiveTurn`, which is PER-KEY and only governs the typing-loop stop; this
+   *  is the GLOBAL busy signal because the handback queues behind whatever turn
+   *  is running, regardless of topic. Optional; defaults to "not busy". */
   isClaudeBusy?: () => boolean
   now?: () => number
   /** Debounce before painting the pre-turn card (kills sub-second flicker). */
@@ -207,6 +244,17 @@ export interface HandbackPreturnSignalDeps {
   /** Age after emit at which a never-adopted card self-reaps. Independent of
    *  topic liveness. */
   adoptTimeoutMs?: number
+  /** TTL (ms) for the delivered-but-not-yet-streaming window. A released
+   *  handback has been DELIVERED into claude's queue but its adopting turn may
+   *  not have started streaming yet — the false-orphan window #4027 left open
+   *  (idle machine + un-adopted = looked like an orphan). While within this TTL
+   *  the reap DEFERS (`deliveredAwaitingTurnStart`); past it a truly-stuck
+   *  delivery finally reaps for deterministic recovery rather than hanging
+   *  forever. Defaults to 5 min. */
+  deliveredTtlMs?: number
+  /** Max deterministic re-injections of a genuine orphan before escalating to
+   *  fleet-health telemetry. Defaults to 2. */
+  maxReinjects?: number
   /** Injected scheduler (mirrors bridge-dead-watchdog.ts): defaults to
    *  setTimeout/clearTimeout. Injected so a runner-agnostic test can drive the
    *  debounce + self-reap deterministically WITHOUT any vitest-only fake-timer
@@ -224,6 +272,18 @@ interface PreTurnEntry {
   adoptTurnId: string
   syntheticTurnKey: string
   startedAt: number
+  /** When the handback was RELEASED/DELIVERED for delivery (stamped at
+   *  `noteHandbackRelease`). Drives `deliveredAwaitingTurnStart`: the reap must
+   *  not treat a delivered-but-not-yet-streaming handback as an orphan within
+   *  the delivered TTL. Equal to `startedAt` (release is the delivery point). */
+  deliveredAt: number
+  /** How many times this handback has already been deterministically re-injected
+   *  (carried across the buffer round trip via `HANDBACK_REINJECT_COUNT_META_KEY`
+   *  on the inbound). Governs the retry cap before fleet-health escalation. */
+  reinjectCount: number
+  /** The released handback inbound itself — retained so a genuine orphan can be
+   *  re-injected through the pending-inbound buffer (deterministic recovery). */
+  inbound: InboundMessage
   pinned: boolean
   debounceTimer: unknown | null
   reapTimer: unknown | null
@@ -273,6 +333,8 @@ export function createHandbackPreturnSignal(
   const now = deps.now ?? (() => Date.now())
   const debounceMs = deps.debounceMs ?? 700
   const adoptTimeoutMs = deps.adoptTimeoutMs ?? 30_000
+  const deliveredTtlMs = deps.deliveredTtlMs ?? 300_000
+  const maxReinjects = deps.maxReinjects ?? 2
   const setTimer =
     deps.setTimer ??
     ((fn: () => void, ms: number) => {
@@ -333,9 +395,9 @@ export function createHandbackPreturnSignal(
         if (messageId == null) return // no card painted; the reap timer cleans up
         if (entry.consumed) {
           // Adopted/reaped while the send was in flight: the card is now the
-          // turn's (adoption seeds a null id it can't use) — finalize+clear so
-          // it never dangles. Rare; the debounce makes it unlikely.
-          void deps.finalizeCard({
+          // turn's (adoption seeds a null id it can't use) — DELETE it so it
+          // never dangles. Rare; the debounce makes it unlikely.
+          void deps.deleteCard({
             turnKey: entry.syntheticTurnKey,
             chatId: entry.chatId,
             threadId: entry.threadId,
@@ -385,30 +447,52 @@ export function createHandbackPreturnSignal(
     deps.stopTypingLoop(entry.chatId, entry.threadId)
   }
 
+  /**
+   * The delivered-but-not-yet-streaming window (#4027 coverage gap). A released
+   * handback has been DELIVERED into claude's single input queue, but its
+   * adopting turn may not have started streaming yet — and in that stretch the
+   * machine reads as idle (`isClaudeBusy()` false) with the entry un-adopted,
+   * which looked exactly like a genuine orphan and produced the false "needs a
+   * nudge" card even after #4027 gated on `isMachineInTurn`. While the handback
+   * is within the delivered TTL and its turn has not started (we are in `reap`,
+   * so the entry is un-consumed = no adopting turn minted), it is NOT orphaned —
+   * defer. Past the TTL a truly-stuck delivery finally reaps rather than hanging
+   * forever, handing off to deterministic recovery.
+   */
+  function deliveredAwaitingTurnStart(entry: PreTurnEntry): boolean {
+    return now() - entry.deliveredAt < deliveredTtlMs
+  }
+
   function reap(entry: PreTurnEntry): void {
     entry.reapTimer = null
     if (entry.consumed) return
     // PRIMARY GATE (queue state, not a flat timeout): a released handback is
     // delivered into claude's SINGLE input queue and mints its adopting turn
-    // only when claude next goes idle. If claude is STILL in a turn, this
-    // handback is not orphaned — it is correctly enqueued behind the in-flight
-    // turn (a long parent turn can run many minutes). Finalizing now would post
-    // a false "never started — needs a nudge" card (the 3-cards-in-4-min
-    // incident). Defer: re-arm and re-check. We finalize only once claude is
-    // idle AND the handback still has not been adopted (the genuine bridge-
-    // death / dropped-inbound case). This cannot loop forever on a healthy
-    // agent: claude processes its queue FIFO, so the handback is either adopted
-    // (cancelling the reap) or claude eventually goes idle (letting it fire).
-    if (deps.isClaudeBusy?.() === true) {
+    // only when claude next goes idle. If claude is STILL in a turn, OR the
+    // handback was delivered and its turn has simply not started streaming yet
+    // (within the delivered TTL — the #4027 coverage gap), the handback is NOT
+    // orphaned. Reaping now would have posted a false "never started — needs a
+    // nudge" card (the 3-cards-in-4-min incident). Defer: re-arm and re-check.
+    // We proceed to recovery only once claude is idle AND the delivered window
+    // has elapsed AND the handback still has not been adopted (the genuine
+    // bridge-death / dropped-inbound case). This cannot loop forever: claude
+    // processes its queue FIFO (adoption cancels the reap), and the delivered
+    // TTL is bounded, so a stuck delivery eventually recovers deterministically.
+    if (deps.isClaudeBusy?.() === true || deliveredAwaitingTurnStart(entry)) {
       log(
         `handback-preturn-signal: reap deferred key=${entry.statusKey} ` +
-          `(claude busy — handback enqueued behind an in-flight turn, not orphaned)\n`,
+          `(${deps.isClaudeBusy?.() === true ? 'claude busy' : 'delivered, turn not yet streaming'}` +
+          ` — not orphaned)\n`,
       )
       entry.reapTimer = setTimer(() => reap(entry), adoptTimeoutMs)
       return
     }
     entry.consumed = true
-    // Stop the forever-running typing loop and finalize the frozen card.
+    // GENUINE ORPHAN. Recover DETERMINISTICALLY — never ask the operator to
+    // nudge. Stop the forever-running typing loop, DELETE the frozen card (do
+    // not leave a stale "needs a nudge" message), then re-inject the handback so
+    // the machine re-processes it itself. Cap the re-injections; past the cap
+    // escalate to fleet-health telemetry (NOT a chat card).
     stopTypingUnlessTurnLive(entry, 'orphan reap')
     if (entry.activityMessageId != null) {
       const record: PreTurnCardRecord = {
@@ -419,17 +503,61 @@ export function createHandbackPreturnSignal(
         startedAt: entry.startedAt,
         pinned: entry.pinned,
       }
-      // Clear the durable record BEFORE the finalizing edit (at-most-once
-      // idempotency guard, mirroring the activity-card-store reapers).
+      // Clear the durable record BEFORE the delete (at-most-once idempotency
+      // guard, mirroring the activity-card-store reapers).
       deps.clearCardRecord(entry.syntheticTurnKey, entry.activityMessageId)
-      void Promise.resolve(deps.finalizeCard(record)).catch((err) => {
+      void Promise.resolve(deps.deleteCard(record)).catch((err) => {
         log(
-          `handback-preturn-signal: orphan finalize failed key=${entry.statusKey}: ` +
+          `handback-preturn-signal: orphan card delete failed key=${entry.statusKey}: ` +
             `${err instanceof Error ? err.message : String(err)}\n`,
         )
       })
     }
+    // Drop the entry from the topic map BEFORE re-injecting so a redelivery that
+    // re-enters `noteHandbackRelease` (production: async buffer drain; possible
+    // synchronously) is not swallowed by the per-topic dedupe guard. The entry
+    // object stays valid for the captured re-inject below.
     dropEntry(entry)
+    if (entry.reinjectCount < maxReinjects) {
+      const nextCount = entry.reinjectCount + 1
+      // Stamp the counter on the inbound so it survives the buffer round trip
+      // (the re-injected inbound re-enters `noteHandbackRelease`, which reads it
+      // back — the retry cap outlives the drop-and-recreate of this entry).
+      entry.inbound.meta[HANDBACK_REINJECT_COUNT_META_KEY] = String(nextCount)
+      log(
+        `handback-preturn-signal: orphan reap key=${entry.statusKey} ` +
+          `turnId=${entry.adoptTurnId} — re-injecting handback (attempt ${nextCount}/${maxReinjects})\n`,
+      )
+      try {
+        deps.reinjectHandback(entry.inbound)
+      } catch (err) {
+        log(
+          `handback-preturn-signal: orphan re-inject failed key=${entry.statusKey}: ` +
+            `${err instanceof Error ? err.message : String(err)}\n`,
+        )
+      }
+    } else {
+      log(
+        `handback-preturn-signal: orphan reap key=${entry.statusKey} ` +
+          `turnId=${entry.adoptTurnId} — re-injection cap (${maxReinjects}) exhausted, ` +
+          `escalating to fleet-health telemetry\n`,
+      )
+      try {
+        deps.escalateOrphan({
+          statusKey: entry.statusKey,
+          chatId: entry.chatId,
+          threadId: entry.threadId,
+          adoptTurnId: entry.adoptTurnId,
+          reinjectCount: entry.reinjectCount,
+          ageMs: now() - entry.deliveredAt,
+        })
+      } catch (err) {
+        log(
+          `handback-preturn-signal: orphan escalation failed key=${entry.statusKey}: ` +
+            `${err instanceof Error ? err.message : String(err)}\n`,
+        )
+      }
+    }
   }
 
   return {
@@ -466,6 +594,12 @@ export function createHandbackPreturnSignal(
       )
       const startedAt = now()
       const syntheticTurnKey = `${PRETURN_TURNKEY_PREFIX}${statusKey}:${startedAt}`
+      // Carry the re-injection counter across the buffer round trip: a genuine
+      // orphan re-injects this inbound, which re-enters here with the counter
+      // stamped on `meta`, so the retry cap survives the entry's recreate.
+      const rawReinject = inbound.meta?.[HANDBACK_REINJECT_COUNT_META_KEY]
+      const parsedReinject = rawReinject != null ? Number.parseInt(rawReinject, 10) : 0
+      const reinjectCount = Number.isFinite(parsedReinject) && parsedReinject > 0 ? parsedReinject : 0
       const entry: PreTurnEntry = {
         statusKey,
         chatId,
@@ -473,6 +607,10 @@ export function createHandbackPreturnSignal(
         adoptTurnId,
         syntheticTurnKey,
         startedAt,
+        // Release IS the delivery point (this is the buffer-drain chokepoint).
+        deliveredAt: startedAt,
+        reinjectCount,
+        inbound,
         pinned: false,
         debounceTimer: null,
         reapTimer: null,

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -179,6 +179,7 @@ export type GatewayToClient =
   | Ms365ApprovalPostedEvent
   | ConfigApprovalResolvedEvent
   | RolloutStatusPostedEvent
+  | RolloutStatusEditedEvent
   | PendingPermissionStatusEvent
   | PreApprovedResultEvent;
 
@@ -567,9 +568,13 @@ export interface RolloutStatusPostMessage {
 /**
  * #2726 Part 2 — hostd asks the gateway to EDIT the rollout status message it
  * previously posted (identified by `messageId`, returned in the
- * `rollout_status_posted` reply). Best-effort, fire-and-forget: an edit failure
- * (incl. Telegram 429) is handled gateway-side and never surfaced back toward
- * the roll.
+ * `rollout_status_posted` reply). Best-effort toward the ROLL: hostd never
+ * blocks on it and Telegram 429s are retried gateway-side.
+ *
+ * #4065 — the gateway now replies with `rollout_status_edited` so hostd can
+ * tell "edited" from "edited into the void". A seeded-resume narrator holds a
+ * message_id it never posted itself; without the reply a stale id means the
+ * operator sees a frozen card for the rest of the roll.
  */
 export interface RolloutStatusEditMessage {
   type: "rollout_status_edit";
@@ -597,6 +602,29 @@ export interface RolloutStatusPostedEvent {
   reason?: string;
 }
 
+/**
+ * #4065 — gateway → hostd reply after a `rollout_status_edit`, so a narrator
+ * editing a card it did NOT post (the seeded post-self-bump resume) can tell
+ * that the card is gone instead of editing into the void for the rest of the
+ * roll. Advisory only: hostd never blocks a roll on it, and a gateway that
+ * predates this event simply never sends one (hostd times out and behaves as
+ * before).
+ */
+export interface RolloutStatusEditedEvent {
+  type: "rollout_status_edited";
+  requestId: string;
+  /** True when the live card now carries the requested body. */
+  ok: boolean;
+  /**
+   * True IFF the failure means the target message no longer exists / can no
+   * longer be edited. ONLY this justifies a re-post — a transient failure
+   * (429 past retries, network) leaves a perfectly good card in the chat.
+   */
+  gone?: boolean;
+  /** Diagnostic detail on failure. */
+  reason?: string;
+}
+
 /**
  * Issue #2971 — sent by the wedge-watchdog (autoaccept-poll sidecar) over
  * the gateway UDS, BEFORE it would otherwise Esc a shape-persistent