switchroom 0.19.42 → 0.19.43

package/telegram-plugin/dist/server.js

@@ -16996,7 +16996,10 @@ var init_plugin_logger = __esm(() => {
 });
 
 // format.ts
-var init_format = () => {};
+var DELIMITER_RUN_CHARS;
+var init_format = __esm(() => {
+  DELIMITER_RUN_CHARS = new Set(["*", "_", "`", "~", "|"]);
+});
 
 // raw-error-scrub.ts
 function extractRequestId(raw) {
@@ -24849,7 +24852,7 @@ var init_bridge = __esm(async () => {
           format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path \u2014 no separate HTML engine, no auto-escaping." },
           disable_web_page_preview: { type: "boolean", description: "Disable link preview thumbnails. Default: true." },
           protect_content: { type: "boolean", description: "When true, Telegram prevents the message from being forwarded or saved." },
-          quote_text: { type: "string", description: "Surgical quote: specific text to highlight from the reply_to message. Requires reply_to." },
+          quote_text: { type: "string", description: "Surgical quote: specific text to highlight from the reply_to message. Must be an EXACT substring of that message (copy it verbatim, do not paraphrase; max 1024 chars) \u2014 a quote Telegram cannot find is dropped and the reply lands unquoted. Requires reply_to." },
           disable_notification: { type: "boolean", description: 'When true, Telegram delivers the message silently \u2014 no device ping for this user. Default false (pings). Use true for mid-turn updates ("still working through X") so only the final answer pings. Always omit (or pass false) on the final answer of a turn.' },
           inline_keyboard: {
             type: "array",

package/telegram-plugin/flood-429-ledger.ts

@@ -362,9 +362,11 @@ export function writeFlood429Ledger(
  * call at the ~5s cadence a long ban produces, because the fold collapses
  * those into a single episode instead of growing the file.
  *
- * Read-fold-write is not atomic across processes: the gateway and the MCP
- * server's `createRobustApiCall` share one state dir, so a simultaneous 429 in
- * both could drop one episode. That is deliberate — the alternative is a lock
+ * Read-fold-write is not atomic across processes. Today every writer lives in
+ * the gateway process (its two `createRetryApiCall` wirings plus the outbox
+ * sweep's, all on one event loop), but the ledger is keyed by state DIR, so a
+ * second process wiring the breaker could drop one episode on a simultaneous
+ * 429. That is deliberate — the alternative is a lock
  * on the send path's error handler, and the cost of losing an episode is
  * nil: a penalty stays on the ledger for seven days and is re-recorded by the
  * next 429, so no verdict tier turns on a single write landing.

package/telegram-plugin/flood-circuit-breaker.ts

@@ -235,9 +235,17 @@ export function writeFloodState(
  * classifies it (`src/cli/doctor-flood-pressure.ts`).
  *
  * Recording here rather than at the gateway callsites is deliberate: this is
- * the one function EVERY `onFloodWait` wiring goes through (gateway.ts's two
- * hooks and `shared/bot-runtime.ts`'s `createRobustApiCall`), so no future
- * callsite can record a window without also recording its history.
+ * the one function EVERY `onFloodWait` wiring goes through, so no future
+ * callsite can record a window without also recording its history. The live
+ * wirings are `gateway/gateway.ts:5715` (`robustApiCall`) and `:5849`
+ * (`nonEssentialApiCall`), plus `gateway/outbox-sweep.ts:582` — and
+ * `scripts/check-retry-flood-hooks.mjs` fails the build if a new
+ * `createRetryApiCall` site omits either breaker hook.
+ *
+ * (Until #3863 this docblock also cited `shared/bot-runtime.ts`'s
+ * `createRobustApiCall` as a live wiring. It had zero production callers and
+ * its breaker hooks were OPTIONAL, so it was deleted rather than counted.
+ * Cite only wirings the lint gate can see.)
  */
 export function makeFloodWaitRecorder(
   path: string,

package/telegram-plugin/format.ts

@@ -30,6 +30,20 @@
  */
 export const RICH_MESSAGE_MAX_CHARS = 32768
 
+/**
+ * The legacy plain-text `sendMessage` / `editMessageText` wire cap (4096
+ * UTF-16 units). It does NOT apply to the rich path (`sendRichMessage`, up to
+ * {@link RICH_MESSAGE_MAX_CHARS}), but it DOES apply the moment a send path
+ * DEGRADES to the plain endpoint — the parse-reject fallbacks that resend a
+ * rich chunk as plain text, and `renderSafe`'s `mode: "plain"` results.
+ *
+ * Lives here (next to the rich cap and the splitters) rather than in
+ * `render/rich-render.ts` so every plain-degradation site can re-cap without
+ * importing the renderer; `render/rich-render.ts` re-exports it for its
+ * existing importers.
+ */
+export const PLAIN_TEXT_MAX_CHARS = 4096
+
 /**
  * Escape the GFM-markdown special characters so a dynamic value
  * (a filename, an id, arbitrary user text) renders LITERALLY inside a
@@ -782,8 +796,16 @@ function isFullyBolded(fragment: string): boolean {
  * treated as a legitimate pseudo-heading (`**Section**`) rather than an
  * over-bolded paragraph. Single source of truth for BOTH the per-block rule
  * and the global-ratio heading exemption.
+ *
+ * 64, not 48: at 48 a legitimate long section label
+ * (`**Deployment status across all three regions:**` — 50 chars with markers)
+ * was read as an over-bolded paragraph and flattened. 64 still bounds the
+ * exemption to something that reads as a label on a phone; the alternative of
+ * exempting any fully-bold line ending in `:` regardless of length was
+ * rejected because an arbitrarily long bolded paragraph that happens to end
+ * in a colon would then escape the tripwire entirely.
  */
-const PSEUDO_HEADING_MAX_CHARS = 48
+const PSEUDO_HEADING_MAX_CHARS = 64
 
 /**
  * True when a blank-line-delimited block is a single-line pseudo-heading: one
@@ -828,7 +850,12 @@ function unbold(fragment: string): string {
  *     encourages) and is NOT stripped — neither by the per-block rule NOR by
  *     the global-ratio rule (it still counts toward the global ratio, so a
  *     genuinely over-bolded message still trips, but its section headings
- *     survive instead of the whole reply going plain).
+ *     survive instead of the whole reply going plain). The one exception:
+ *     when EVERY block of the message is such a heading there is no body to
+ *     preserve contrast against, so the global rule strips them all rather
+ *     than leaving a 100%-bold message untouched. A block that is nothing but
+ *     masked code (a bare fence, a lone inline span) does NOT count as body
+ *     for that test — see the note at the call site.
  *   - A list with any non-fully-bolded item is left alone.
  *
  * Code spans/fences are masked (maskCodeRegions) and never counted or
@@ -862,8 +889,33 @@ export function stripExcessBold(
     // Clearly over-bolded — strip every bold span, keeping the text, EXCEPT
     // standalone short pseudo-heading blocks (`**Section**`), which stay bold
     // so a bold-dense digest keeps its section headings.
+    //
+    // The exemption only makes sense when there is body text for the headings
+    // to stand out FROM. A message whose every block is a pseudo-heading has
+    // no body: exempting all of them leaves a 100%-bold message untouched and
+    // unlogged. In that case the exemption is dropped and the whole message is
+    // stripped, which is what the ratio rule says.
+    //
+    // "Body" here means VISIBLE (non-code) text, so a block that is nothing but
+    // masked code is skipped rather than counted as body (#4114). Masked code
+    // is invisible to every other measurement in this function — it is stripped
+    // out of `visible` before the ratio is taken — so counting a bare fence as
+    // body would be the one place code influences the bold decision, and it
+    // would do so by RESTORING the exact #4017 symptom: a headings-plus-one-
+    // snippet digest (a very ordinary agent status report) stayed 100% bold
+    // with no onStrip line, because the code block broke `every(...)`. The
+    // contrast a code block provides is real but partial, and it does not make
+    // every remaining visible character being bold the right render.
+    //
+    // Filtering with `stripPlaceholders` (the masker's own "remove EVERY mask"
+    // primitive) rather than a fence-specific test means all mask kinds — the
+    // FENCE and INLINE prefixes today, anything maskCodeRegions adds later —
+    // are handled by construction instead of by enumeration.
+    const contentBlocks = blocks.filter((b) => stripPlaceholders(b).trim() !== '')
+    const allHeadings =
+      contentBlocks.length > 0 && contentBlocks.every(isPseudoHeadingBlock)
     const rebuilt = blocks.map((block) =>
-      isPseudoHeadingBlock(block) ? block : unbold(block),
+      !allHeadings && isPseudoHeadingBlock(block) ? block : unbold(block),
     )
     const out = rejoinBlocks(masked, rebuilt)
     if (out !== masked) onStrip?.({ rule: 'global', ratio })
@@ -1160,6 +1212,41 @@ export function hardSliceToCap(text: string, cap = RICH_MESSAGE_MAX_CHARS): stri
   return out
 }
 
+/**
+ * Re-cap a body that is about to be sent through the PLAIN `sendMessage` /
+ * `editMessageText` endpoint (switchroom #4043).
+ *
+ * Every plain-text FALLBACK in the send path inherits a chunk that was split
+ * for the RICH cap ({@link RICH_MESSAGE_MAX_CHARS} = 32768). Handing such a
+ * chunk to the plain endpoint (which caps at {@link PLAIN_TEXT_MAX_CHARS} =
+ * 4096) makes Telegram reject it with `message is too long` — so the fallback
+ * that exists precisely to rescue a failed send fails too, and the user never
+ * receives the message (in the outbox sweep it retries forever).
+ *
+ * Cuts at `splitMarkdownChunks`' safe boundaries first (never bisecting a
+ * fenced block or a table row) and hard-slices any residual indivisible region,
+ * so EVERY returned piece is guaranteed `<= cap`. Returns the input as a
+ * single-element array when it already fits (the overwhelmingly common case,
+ * byte-identical to the pre-fix behaviour).
+ */
+export function splitPlainTextToCap(text: string, cap = PLAIN_TEXT_MAX_CHARS): string[] {
+  if (cap <= 0) return [text]
+  if (text.length <= cap) return [text]
+  const out: string[] = []
+  for (const piece of splitMarkdownChunks(text, cap)) {
+    if (piece.length <= cap) {
+      if (piece.length > 0) out.push(piece)
+      continue
+    }
+    // `splitMarkdownChunks` emits an unsplittable region whole; hard-cut it so
+    // the plain endpoint can actually accept it.
+    for (const slice of hardSliceToCap(piece, cap)) {
+      if (slice.length > 0) out.push(slice)
+    }
+  }
+  return out.length > 0 ? out : [text]
+}
+
 // ---------------------------------------------------------------------------
 // Markdown-aware chunking — never bisects a code fence or a table row
 // ---------------------------------------------------------------------------
@@ -1208,16 +1295,10 @@ export function splitMarkdownChunks(text: string, maxLen = RICH_MESSAGE_MAX_CHAR
       cut = spaceIdx
     }
 
-    // Back off so the cut doesn't fall inside an open ``` fence.
-    cut = backOffOpenFence(rest, cut)
-    // Back off so the cut doesn't bisect a table row (a line with `|`).
-    cut = backOffTableRow(rest, cut)
-    // Back off so the cut doesn't bisect an inline entity (`**bold**`,
-    // `` `code` ``, `_italic_`, `[label](href)`), which would leave an unclosed
-    // delimiter in the emitted chunk (Telegram then parse-rejects it to
-    // plaintext, or mis-renders the continuation). Runs LAST so it also cleans
-    // up a boundary the fence/table back-offs landed on.
-    cut = backOffOpenInline(rest, cut)
+    // Back the cut off any markdown entity it would bisect — fenced block,
+    // table row, inline span. One shared mechanism (`safeMarkdownCut`), also
+    // used by the card fitter's last-resort clip (#4116).
+    cut = safeMarkdownCut(rest, cut)
 
     if (cut <= 0) {
       // Could not find a safe boundary below maxLen — the region is one
@@ -1334,8 +1415,137 @@ const INLINE_SPAN_PATTERNS: readonly RegExp[] = [
   /__[^_\n]+__/g, // underline
   /(?<![\w*])_[^_\n]+_(?![\w*])/g, // italic (snake_case-guarded)
   /\[[^\]\n]*\]\([^)\n]*\)/g, // link [label](href)
+  /~~[^~\n]+~~/g, // strikethrough
+  /\|\|[^|\n]+\|\|/g, // spoiler
 ]
 
+/** Characters that form multi-character markdown delimiter runs (`**`, `~~`, `||`, ` ``` `). */
+const DELIMITER_RUN_CHARS = new Set(['*', '_', '`', '~', '|'])
+
+/**
+ * The opening delimiter of every entity kind {@link safeMarkdownCut} can
+ * retreat past, anchored at the head of a string. Used ONLY by
+ * {@link truncateMarkdownSafe}'s repair step — see the doc there for why
+ * dropping an opener is the right repair. Kept adjacent to
+ * `INLINE_SPAN_PATTERNS` so the two marker vocabularies stay in step.
+ */
+const FENCE_OPENER_AT_HEAD = /^(\n?)(?:`{3,}|~{3,})[^\n]*/
+const INLINE_OPENER_AT_HEAD = /^(?:\*{1,3}|_{1,3}|`+|~~|\|\||\[)/
+const TABLE_ROW_OPENER_AT_HEAD = /^(\n?[ \t]*)\|/
+
+/**
+ * Bound on {@link truncateMarkdownSafe}'s opener-drop repair loop. Each pass
+ * removes at least one character, so this only caps a pathologically nested
+ * head (`***` + `` ` `` + `[` …); eight is far past anything a card produces.
+ */
+const MAX_OPENER_REPAIRS = 8
+
+/**
+ * The largest index `<= cut` at which `text` can be split without bisecting a
+ * markdown entity — the ONE place "where is it safe to cut markdown?" is
+ * answered.
+ *
+ * Composes the three back-offs in the order the chunker has always applied
+ * them (fenced block → table row → inline span; the inline pass runs last so
+ * it also cleans a boundary the first two landed on), then refuses to split a
+ * surrogate pair so the result is always valid UTF-16 as well as valid
+ * markdown.
+ *
+ * Returns `0` when NO safe boundary exists at or below `cut` — i.e. an entity
+ * that starts at index 0 swallows the whole window. Callers must handle that
+ * case; see {@link truncateMarkdownSafe}.
+ */
+export function safeMarkdownCut(text: string, cut: number): number {
+  if (cut <= 0) return 0
+  if (cut >= text.length) return text.length
+  let safe = backOffOpenFence(text, cut)
+  safe = backOffTableRow(text, safe)
+  safe = backOffOpenInline(text, safe)
+  // Never cut INSIDE a delimiter run: `**bold**` cut between the two closing
+  // stars emits one lone `*` (odd marker count → parse-reject), and the span
+  // back-off above cannot see it because the run's first half is a complete
+  // span's tail, not a straddle. Retreat to the run's start.
+  while (safe > 0 && DELIMITER_RUN_CHARS.has(text[safe]) && text[safe - 1] === text[safe]) safe--
+  if (safe <= 0) return 0
+  // Never leave a lone high surrogate by cutting through an astral character.
+  const prev = text.charCodeAt(safe - 1)
+  const here = text.charCodeAt(safe)
+  if (prev >= 0xd800 && prev <= 0xdbff && here >= 0xdc00 && here <= 0xdfff) safe -= 1
+  return safe
+}
+
+/**
+ * Truncate `text` to at most `budget` characters such that the RESULT IS
+ * ALWAYS PARSEABLE MARKDOWN — no half-open `**`/`_`/`` ` ``/`~~`/`||` run, no
+ * unclosed fence, no bisected link or table row, no split surrogate pair.
+ *
+ * Why this exists (#4116): the card fitter's last-resort clip used to slice
+ * the raw markdown by character count. A cut landing between a `**` pair
+ * yields a body Telegram parse-REJECTS — so the code path that exists
+ * specifically to guarantee delivery within the char budget could itself make
+ * the send fail. A clipped card beats no card, but only if it can be sent.
+ *
+ * Two steps, in order:
+ *
+ *  1. **Back off** to the nearest safe boundary ({@link safeMarkdownCut}).
+ *     This is the normal case and it preserves formatting exactly: an entity
+ *     that straddles the limit simply doesn't make the cut.
+ *
+ *  2. **Drop the opener** when backing off would keep less than HALF the
+ *     window. That happens when a single entity is longer than the window —
+ *     `**<40k-char description>**`, the #3682 repro — and a back-off would
+ *     return a near-empty card, which is no better than the dropped card the
+ *     clip exists to prevent. The entity cannot render anyway (its closing
+ *     delimiter is past the window), so we drop its OPENING delimiter and ask
+ *     again: the text survives as literal prose, the markdown stays balanced,
+ *     and the card is delivered.
+ *
+ * The window END IS HELD FIXED IN SOURCE TERMS across a repair (`end` shrinks
+ * by exactly the characters removed). Letting the window slide forward by the
+ * dropped opener's width would pull the entity's CLOSING delimiter into the
+ * output — an orphan closer, unbalanced again. That is a real defect this
+ * function had before its property test swept every offset.
+ *
+ * The repair loop is bounded (each pass removes at least one character; at
+ * most `MAX_OPENER_REPAIRS` passes) so a pathological body cannot spin.
+ */
+export function truncateMarkdownSafe(text: string, budget: number): string {
+  if (budget <= 0) return ''
+  if (text.length <= budget) return text
+  let t = text
+  let end = budget
+  for (let pass = 0; pass <= MAX_OPENER_REPAIRS; pass++) {
+    const safe = safeMarkdownCut(t, end)
+    // A back-off that keeps at least half the window is the good outcome: the
+    // straddling entity is dropped whole and everything before it renders as
+    // authored.
+    if (safe * 2 >= end) return t.slice(0, safe)
+    const repaired = dropLeadingOpener(t.slice(safe))
+    // No opener to drop (unreachable in principle — every back-off above
+    // retreats TO one). Prefer the short-but-valid back-off over a slice that
+    // cannot be parsed.
+    if (repaired == null) return t.slice(0, safe)
+    end -= t.length - safe - repaired.length
+    t = t.slice(0, safe) + repaired
+  }
+  return t.slice(0, Math.max(0, safeMarkdownCut(t, end)))
+}
+
+/**
+ * Remove the opening delimiter of the entity that begins at the head of
+ * `rest`, preserving any leading newline so line structure survives. Returns
+ * `null` when the head is not an entity opener.
+ */
+function dropLeadingOpener(rest: string): string | null {
+  const fence = FENCE_OPENER_AT_HEAD.exec(rest)
+  if (fence != null) return fence[1] + rest.slice(fence[0].length)
+  const inline = INLINE_OPENER_AT_HEAD.exec(rest)
+  if (inline != null) return rest.slice(inline[0].length)
+  const row = TABLE_ROW_OPENER_AT_HEAD.exec(rest)
+  if (row != null) return row[1] + rest.slice(row[0].length)
+  return null
+}
+
 function backOffOpenInline(text: string, cut: number): number {
   if (cut <= 0 || cut >= text.length) return cut
   let earliest = cut

package/telegram-plugin/gateway/boot-card.ts

@@ -53,6 +53,7 @@ import {
   AGENT_LIVE_POLL_INTERVAL_MS,
 } from './boot-probes.js'
 import { escapeMarkdown, stackCardLines } from '../card-format.js'
+import { NESTED_PREFIX } from '../status-no-truncate.js'
 import {
   loadCache as loadBootIssueCache,
   diffProbes as diffBootProbes,
@@ -540,7 +541,11 @@ export function renderBootCard(opts: RenderBootCardOpts): string {
     const tailCmd = process.env.SWITCHROOM_RUNTIME === 'docker'
       ? `docker logs --tail 100 switchroom-${agentSlug}`
       : `journalctl --user -u switchroom-${agentSlug} -n 100`
-    degradedRows.push(`    ↳ Tail logs: \`${tailCmd}\``)
+    // One indent idiom, repo-wide (#4115): NESTED_PREFIX, not ASCII spaces.
+    // Telegram left-trims a leading ASCII-whitespace run off a content line,
+    // so the ASCII-space indent this row used to carry rendered FLAT on a
+    // phone — the #3668 failure, live-verified 2026-07-26.
+    degradedRows.push(`${NESTED_PREFIX}Tail logs: \`${tailCmd}\``)
   }
 
   // Probe rows — only those that surfaced as degraded/fail. Healthy
@@ -569,7 +574,7 @@ export function renderBootCard(opts: RenderBootCardOpts): string {
       // user does or doesn't see across consecutive boots.
       degradedRows.push(`${dot} **${PROBE_LABELS[key]}**  ${escapeMarkdown(r.detail)}`)
       if (r.nextStep) {
-        degradedRows.push(`    ↳ ${renderNextStep(r.nextStep)}`)
+        degradedRows.push(`${NESTED_PREFIX}${renderNextStep(r.nextStep)}`)
       }
     }
   }

package/telegram-plugin/gateway/flood-reply-queue.ts

@@ -145,6 +145,11 @@ export function queueFloodBlockedReply(input: FloodQueueInput): FloodQueueResult
     textSha256: sha256Hex(text),
     createdAt,
     source: FLOOD_QUEUED_SOURCE,
+    // W1-d (#3865): a flood-deferred record is a reply the agent ALREADY chose
+    // to send to this chat — its audience is never in question. Stamped
+    // explicitly rather than relying on the legacy default, so this producer
+    // stays correct if that default is ever revisited.
+    audience: 'user',
     ...(input.originChatId != null ? { originChatId: input.originChatId } : {}),
     ...(input.originThreadId != null ? { originThreadId: input.originThreadId } : {}),
   }

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'
@@ -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).
@@ -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)),
+  }
+}