switchroom 0.19.14 → 0.19.16

package/telegram-plugin/dist/server.js

@@ -17365,6 +17365,29 @@ function extractToolResultErrorText(content) {
   }
   return "";
 }
+function parseBackgroundTaskId(obj) {
+  const tur = obj.toolUseResult;
+  if (typeof tur === "object" && tur != null) {
+    const id = tur.backgroundTaskId;
+    if (typeof id === "string" && id.length > 0)
+      return id;
+  }
+  return null;
+}
+function parseBackgroundLaunchString(content) {
+  const text = typeof content === "string" ? content : extractToolResultErrorText(content);
+  const m = text.match(/Command running in background with ID: (\w+)/);
+  return m != null ? m[1] : null;
+}
+function parseTaskNotification(content) {
+  if (!content.includes("<task-notification>"))
+    return null;
+  const idM = content.match(/<task-id>([^<]+)<\/task-id>/);
+  const stM = content.match(/<status>([^<]+)<\/status>/);
+  if (idM == null || stM == null)
+    return null;
+  return { taskId: idM[1].trim(), status: stM[1].trim() };
+}
 function projectAssistantTextBlocks(content, make) {
   const out = new Map;
   let lastToolUseIdx = -1;
@@ -17422,6 +17445,10 @@ function projectTranscriptLine(line) {
     const op = obj.operation;
     if (op === "enqueue") {
       const content = obj.content ?? "";
+      const notif = parseTaskNotification(content);
+      if (notif != null) {
+        return [{ kind: "task_notification", taskId: notif.taskId, status: notif.status }];
+      }
       const { chatId, messageId, threadId } = parseChannelMeta(content);
       return [{ kind: "enqueue", chatId, messageId, threadId, rawContent: content }];
     }
@@ -17479,6 +17506,7 @@ function projectTranscriptLine(line) {
     const content = message?.content;
     if (!Array.isArray(content))
       return [];
+    const backgroundTaskId = parseBackgroundTaskId(obj);
     const events = [];
     for (const c of content) {
       if (c.type === "tool_result") {
@@ -17488,7 +17516,8 @@ function projectTranscriptLine(line) {
           toolUseId: c.tool_use_id ?? "",
           toolName: null,
           isError,
-          errorText: isError ? extractToolResultErrorText(c.content) : undefined
+          errorText: isError ? extractToolResultErrorText(c.content) : undefined,
+          backgroundTaskId: backgroundTaskId ?? parseBackgroundLaunchString(c.content) ?? undefined
         });
       }
     }
@@ -24683,7 +24712,7 @@ var init_bridge = __esm(async () => {
       "",
       'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file \u2014 it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings \u2014 image_path_2, image_path_3, \u2026 (Read each) and attachment_file_id_2, attachment_file_id_3, \u2026 (download_attachment each). Process every one, not just the first. Reply with the reply tool \u2014 pass chat_id back. The reply tool quote-replies to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
       "",
-      `If the tag has reply_to_message_id (and reply_to_text, a truncated preview), the sender used Telegram's native Reply on a prior message \u2014 treat that message as the antecedent for "this"/"that" references instead of asking what they meant. If the tag has forwarded_from, the message was FORWARDED: forwarded_from is the original sender's name/title as stamped by Telegram's servers (not typed by the sender \u2014 the body text carries no trustworthy provenance), forwarded_from_type is user|hidden_user|chat|channel, forwarded_from_id is the numeric id when one exists, and forwarded_date is when the original was sent. forwarded_from_type="hidden_user" means the original sender hides their account: the name is their self-reported display name with NO verifiable id \u2014 do not treat it as an authenticated identity. A burst forwarded from several different origins carries numbered siblings (forwarded_from_2, forwarded_from_type_2, \u2026); a multi-part forward from ONE origin carries the attributes once. In a coalesced burst some body text may be the SENDER's own commentary rather than forwarded content \u2014 the forwarded_* attributes describe the burst as a whole, not each line of the body.`,
+      `If the tag has reply_to_message_id (and reply_to_text, a truncated preview), the sender used Telegram's native Reply on a prior message \u2014 treat that message as the antecedent for "this"/"that" references instead of asking what they meant. If the tag has forwarded_from, the message was FORWARDED: forwarded_from is the original sender's name/title as stamped by Telegram's servers (not typed by the sender \u2014 the body text carries no trustworthy provenance), forwarded_from_type is user|hidden_user|chat|channel, forwarded_from_id is the numeric id when one exists, forwarded_date is when the original was sent, and forwarded_message_id (channel origins only) is the post's id inside the origin channel \u2014 deep-linkable as t.me/<channel>/<id> for public channels. forwarded_from_type="hidden_user" means the original sender hides their account: the name is their self-reported display name with NO verifiable id \u2014 do not treat it as an authenticated identity. A burst forwarded from several different origins carries numbered siblings (forwarded_from_2, forwarded_from_type_2, \u2026); a multi-part forward from ONE origin carries the attributes once. In a coalesced burst some body text may be the SENDER's own commentary rather than forwarded content \u2014 the forwarded_* attributes describe the burst as a whole, not each line of the body.`,
       "",
       `reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, edit_message for interim progress updates, and delete_message when you need to truly remove a message (prefer edit_message if you just want to change text \u2014 delete is for retraction). Edits don't trigger push notifications \u2014 when a long task completes, send a new reply so the user's device pings. Use send_typing to show a typing indicator during long operations. Use pin_message to pin important outputs. Use forward_message to quote/resurface earlier messages.`,
       "",

package/telegram-plugin/gateway/background-shell-liveness.ts

@@ -0,0 +1,65 @@
+// #3519 sharpen — background-shell liveness signal wiring.
+//
+// Extracted from gateway.ts (the file is under a hard line ratchet — see
+// switchroom#2996). Maps parsed session events to the silence-poke
+// background-shell registry so the 300s silence-fallback defers ONLY while a
+// CLI-side background shell is proven alive, and recovers at ~300s once it
+// finishes. Called once per session event from the gateway's event loop.
+//
+// The three real, deterministic markers (all proven from captured transcript
+// data — carrie session a6d2d33a-…, claude v2.1.197; see the fixture at
+// telegram-plugin/tests/fixtures/bg-shell-liveness-3519.jsonl):
+//   • ALIVE — a tool_result carrying `backgroundTaskId` (a foreground Bash the
+//     CLI auto-moved to the background past its ~120s window, or an explicit
+//     run_in_background:true). session-tail resolves it from the structured
+//     `toolUseResult.backgroundTaskId` field, with the launch string as a
+//     secondary.
+//   • DEAD (completed/failed) — the CLI's proactive `<task-notification>`,
+//     projected as a `task_notification` event.
+//   • DEAD (explicit) — a `KillShell` tool_use naming the shell via
+//     `input.shell_id`.
+import type { SessionEvent } from '../session-tail.js'
+
+/** The subset of silence-poke this wiring drives (kept narrow for testability). */
+export interface BackgroundShellRegistry {
+  noteBackgroundShellAlive(key: string, shellId: string): void
+  noteBackgroundShellDead(key: string, shellId: string): void
+}
+
+/** Terminal `<task-notification>` statuses that genuinely mean the shell ended. */
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'killed'])
+
+/**
+ * Apply the background-shell liveness signal carried by `ev` (if any) to the
+ * registry for `key`. A no-op for events that carry no marker, so the caller
+ * can invoke it unconditionally on every session event.
+ */
+export function applyBackgroundShellLiveness(
+  registry: BackgroundShellRegistry,
+  key: string,
+  ev: SessionEvent,
+): void {
+  if (ev.kind === 'tool_result') {
+    if (ev.backgroundTaskId != null && ev.backgroundTaskId.length > 0) {
+      registry.noteBackgroundShellAlive(key, ev.backgroundTaskId)
+    }
+    return
+  }
+  if (ev.kind === 'task_notification') {
+    // Defensive terminal-status gate: real captured data proves every genuine
+    // parseable <task-notification> carries a terminal status, so today ANY
+    // parsed notification is safe to treat as DEAD. This guards a hypothetical
+    // FUTURE CLI that emits an interim (non-terminal) notification for a still-
+    // running shell — we must not drop such a shell from the alive-set early.
+    if (ev.taskId.length > 0 && TERMINAL_STATUSES.has(ev.status)) {
+      registry.noteBackgroundShellDead(key, ev.taskId)
+    }
+    return
+  }
+  if (ev.kind === 'tool_use' && ev.toolName === 'KillShell') {
+    const killId = (ev.input as { shell_id?: string } | undefined)?.shell_id
+    if (typeof killId === 'string' && killId.length > 0) {
+      registry.noteBackgroundShellDead(key, killId)
+    }
+  }
+}

package/telegram-plugin/gateway/forward-origin.ts

@@ -204,7 +204,8 @@ export function dedupeForwardOrigins(
 /**
  * Build the `forwarded_*` channel-meta fields. Fixed per-origin attribute
  * order (documented here, tested in forward-origin.test.ts):
- *   forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date
+ *   forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date,
+ *   forwarded_message_id (channel origins only)
  * The primary field is the human-readable NAME; the numeric id is
  * supplementary and follows it. The first origin gets the bare keys;
  * subsequent distinct origins get `_2`, `_3`, … suffixes — the same
@@ -232,6 +233,10 @@ export function buildForwardOriginMeta(
         resolveEnvTimezone(),
       )
     }
+    // Channel origins only: the message id inside the origin channel, so the
+    // agent can deep-link the source post (t.me/<channel>/<id>). Server-
+    // stamped numeric — no escaping surface.
+    if (o.messageId != null) out[`forwarded_message_id${suffix}`] = String(o.messageId)
   })
   return out
 }

package/telegram-plugin/gateway/gateway.ts

@@ -60,6 +60,7 @@ import {
 import {
   VoiceOnDemandCache,
 } from '../voice-ondemand.js'
+import { makeOutboxListenMarkupResolver } from './outbox-listen-markup.js'
 import {
   PreSynthQueue,
   sweepVoiceCacheDir,
@@ -116,6 +117,7 @@ import {
   handlePaidMediaMessage,
   type MediaEnvelopeDeps,
 } from './media-message-handlers.js'
+import { handleRichMessageMessage } from './rich-message-handler.js'
 import {
   routeInbound,
   admitInbound,
@@ -274,7 +276,6 @@ import { createSessionModelSource } from './session-model-source.js'
 import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
 import { REPLY_TOOLS } from '../narrative-dedup.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
-import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { createTurnTypingLoop } from './turn-typing-loop.js'
 import {
@@ -750,6 +751,7 @@ import { createDeliveryConfirmWiring } from './delivery-confirm-wiring.js'
 import { createObligationWiring } from './obligation-wiring.js'
 // #2996 P8 PR-C3 — the extracted silence-poke wiring.
 import { buildSilencePokeOptions } from './liveness-wiring.js'
+import { applySilencePokeSessionEvent } from './silence-poke-session-event.js'
 import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import { dispatchEffects } from './inbound-delivery-machine-dispatch.js'
 import { maybeFireWarmup } from './prefix-warmup.js'
@@ -9849,7 +9851,7 @@ function runDeliveryConfirmSweep(): void {
 const _deliveryConfirmSweep = isGatewayMain ? setInterval(runDeliveryConfirmSweep, DELIVERY_CONFIRM_SWEEP_MS) : undefined
 _deliveryConfirmSweep?.unref?.()
 
-startOutboxSweep({ isGatewayMain, stateDir: STATE_DIR, getBot: () => bot, getTurnsDb: () => turnsDb, dedupCheck: (c, t, x) => outboundDedup.check(c, t, x, Date.now()) != null, log: (l) => process.stderr.write(l) }) // outbox: single deliverer for Stop-hook-captured prose (../outbox.ts)
+startOutboxSweep({ isGatewayMain, stateDir: STATE_DIR, getBot: () => bot, getTurnsDb: () => turnsDb, dedupCheck: (c, t, x) => outboundDedup.check(c, t, x, Date.now()) != null, resolveReplyMarkup: makeOutboxListenMarkupResolver({ resolveVoiceOutPlan: (t) => resolveVoiceOutPlan(loadAccess().voice_out, t), cachePut: (token, payload) => voiceOnDemandCache.put(token, payload), eagerVoiceEnabled, enqueuePreSynth: (j) => voicePreSynthQueue.enqueue(j) }), log: (l) => process.stderr.write(l) }) // outbox: single deliverer for Stop-hook prose; resolveReplyMarkup keeps the #3502 Listen button on net-delivered answers (../outbox.ts)
 
 // #1445 cross-turn pending-async ambient. When a turn ends after the
 // model dispatched background async work (Agent / Task / Bash run-in-
@@ -10870,61 +10872,7 @@ if (isGatewayMain) ipcServer = createIpcServer({
     // (thinking vs working, plus the longest-running in-flight tool).
     if (currentTurn != null) {
       const key = statusKey(currentTurn.sessionChatId, currentTurn.sessionThreadId)
-      if (ev.kind === 'thinking') {
-        silencePoke.noteThinking(key, Date.now())
-      } else if (ev.kind === 'tool_use') {
-        // #1292: track in-flight tool calls so the 300s framework
-        // fallback message can name the actual observable (e.g.
-        // "running Grep \"foo\" for 4m") instead of the dishonest
-        // generic "still working… no update in 5 min" when the agent
-        // is clearly busy on tool calls. Telegram-surface tools are
-        // excluded — their job IS the outbound message, the silence
-        // clock resets via noteOutbound when they fire. Sub-agent
-        // tool_use events (kind='sub_agent_tool_use') intentionally
-        // NOT tracked: the parent's Task tool_use is already on the
-        // map and represents the user-observable wait.
-        if (
-          ev.toolUseId != null
-          && ev.toolUseId.length > 0
-          && !isTelegramSurfaceTool(ev.toolName)
-        ) {
-          const label = toolLabel(
-            ev.toolName,
-            ev.input,
-            /*preamble*/ undefined,
-            ev.precomputedLabel,
-          )
-          silencePoke.noteToolStart(
-            key,
-            ev.toolUseId,
-            ev.toolName,
-            label.length > 0 ? label : null,
-            Date.now(),
-          )
-          // #1445 cross-turn pending-async ambient. Mark the chat as
-          // having dispatched background work this turn so a turn_end
-          // that follows activates the edit-in-place ambient line.
-          // Covers `Agent` / `Task` (the harness-managed async path
-          // — handback channel turn clears it) and `Bash` with
-          // run_in_background:true (model is expected to poll
-          // BashOutput; the ambient ticks until next inbound or the
-          // 30-min budget cap).
-          const evInput = ev.input as { run_in_background?: boolean } | undefined
-          if (
-            ev.toolName === 'Agent'
-            || ev.toolName === 'Task'
-            || (ev.toolName === 'Bash' && evInput?.run_in_background === true)
-          ) {
-            pendingProgress.noteAsyncDispatch(key)
-          }
-        }
-      } else if (ev.kind === 'tool_result') {
-        // #1292: drain the in-flight entry. Idempotent on unknown ids
-        // (covers Telegram-surface tools we skipped at start time).
-        if (ev.toolUseId != null && ev.toolUseId.length > 0) {
-          silencePoke.noteToolEnd(key, ev.toolUseId, Date.now())
-        }
-      }
+      applySilencePokeSessionEvent(silencePoke, pendingProgress, key, ev)
     }
   },
 
@@ -22495,6 +22443,11 @@ bot.on('message:checklist_tasks_added' as Parameters<typeof bot.on>[0], (ctx) =>
   handleChecklistUpdate(ctx as unknown as Context, 'checklist_tasks_added', checklistHandlerDeps)
 })
 bot.on('message:pinned_message', ctx => handlePinnedMessage(ctx, pinnedMessageHandlerDeps))
+// Bot API 10.1 rich messages (forwarded bot messages carry these with NO
+// text/caption — see rich-message-handler.ts; MUST precede the catch-all).
+// Pure forwarded body text, no attachment → coalesce like `message:text`:
+// bind `handleInbound` to `handleInboundCoalesced`, not the bare one (#3516).
+bot.on('message:rich_message', ctx => handleRichMessageMessage(ctx, { ...mediaEnvelopeDeps, handleInbound: handleInboundCoalesced }))
 installUnhandledMessageCatchAll(
   bot,
   (ctx, text) => routeInbound(ctx, text, undefined, undefined, inboundRouterDeps),

package/telegram-plugin/gateway/narrative-lane.ts

@@ -49,6 +49,7 @@
 import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
 import { richMessage } from '../rich-send.js'
+import { appendShownBlock } from '../shown-ledger.js'
 import {
   appendActivityLabel, clipNarrative, formatStepSuffix, renderActivityFeedWithNested,
 } from '../tool-activity-summary.js'
@@ -186,6 +187,16 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
       {
         show: (text) => showNarrativeStep(turn, text),
         retractShown: (text) => retractNarrativeLine(turn, text),
+        // #3513 (correction 4): persist the ephemeral-shown mark keyed by the
+        // per-turn nonce so the out-of-process backstops (E3/E4) refuse to
+        // re-deliver this card-only narration. Envelope-bearing turns only —
+        // `turnId` is null for handback/background/cron, where the structural
+        // rule in the shared classifier is the sole guard (should-fix noted in
+        // shown-ledger.ts). Skip when null.
+        markDurableNarration: (text) => {
+          if (turn.turnId == null) return
+          appendShownBlock(turn.turnId, text)
+        },
       },
       {
         arm: (fn, ms) => {

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -65,9 +65,8 @@ import {
 import { decideAnswerLatchSuppression, type ReplyOwnerTier } from '../reply-owner-resolve.js'
 import { deriveTelegraphTitle } from '../telegraph.js'
 import {
-  mintVoiceOnDemandToken,
-  buildListenKeyboard,
   mayInjectListenButton,
+  planListenButton,
   type VoiceOnDemandCache,
 } from '../voice-ondemand.js'
 import { eagerVoiceEnabled, type PreSynthQueue } from '../voice-presynth.js'
@@ -1495,31 +1494,34 @@ export async function sendReply(
   // config never reaches here (it synthesized immediately above), so a Listen
   // button is never minted for an engine whose taps would dead-end on the
   // local sidecar.
-  if (
-    useOnDemandButton &&
-    voiceOutPlan!.ttsChunks.length > 0 &&
-    voiceOutPlan!.ttsChunks[0]!.length > 0
-  ) {
-    if (!mayInjectListenButton(rawKeyboard)) {
-      process.stderr.write(
-        'telegram gateway: voice-out on-demand: agent supplied inline_keyboard — skipping Listen button (single_use collision gate)\n',
-      )
+  if (useOnDemandButton) {
+    // planListenButton is the SHARED decision (also used by the durable-outbox
+    // safety net, outbox-sweep.ts) — it enforces the empty-TTS guard and the
+    // agent-keyboard collision gate. Null = don't inject.
+    const listenPlan = planListenButton({ voiceOutPlan, rawKeyboard })
+    if (listenPlan == null) {
+      // Log the collision gate ONLY when the agent keyboard is the ACTUAL
+      // reason we skipped — i.e. there IS speakable text. When ttsChunks is
+      // empty the empty-TTS guard is what returned null (there was nothing to
+      // speak), so a "skipping — agent supplied inline_keyboard" line would
+      // misattribute the reason.
+      const hasSpeakableText =
+        voiceOutPlan!.ttsChunks.length > 0 && voiceOutPlan!.ttsChunks[0]!.length > 0
+      if (hasSpeakableText && !mayInjectListenButton(rawKeyboard)) {
+        process.stderr.write(
+          'telegram gateway: voice-out on-demand: agent supplied inline_keyboard — skipping Listen button (single_use collision gate)\n',
+        )
+      }
     } else {
       // Token is intentionally GLOBAL (not chat-keyed): under the single-tenant
       // invariant the operator is the only authorized sender across all chats,
       // and the tap handler re-checks access.allowFrom before synthesizing, so
       // a token needs no per-chat scoping to be safe.
-      const token = mintVoiceOnDemandToken()
-      voiceOnDemandCache.put(token, {
-        // ttsChunks[0] is already normalizeForSpeech(reply) (kokoro path).
-        text: voiceOutPlan.ttsChunks[0]!,
-        ...(voiceOutPlan.voice != null ? { voice: voiceOutPlan.voice } : {}),
-        speed: voiceOutPlan.speed,
-      })
+      voiceOnDemandCache.put(listenPlan.token, listenPlan.payload)
       // The keyboard stays after the tap (never stripped) so it can be
       // replayed. The gate above guarantees this is the ONLY button on the
       // message, so keeping it is safe (no agent buttons to protect).
-      replyMarkup = buildListenKeyboard(token)
+      replyMarkup = listenPlan.replyMarkup
       // #2763 eager pre-synthesis: kick a background synth of the same
       // payload so the Listen tap attaches the pre-made file instantly.
       // Local-engine only (useOnDemandButton already gates engine==='kokoro'
@@ -1530,10 +1532,10 @@ export async function sendReply(
       // to the lazy path).
       if (eagerVoiceEnabled()) {
         voicePreSynthQueue.enqueue({
-          token,
-          text: voiceOutPlan.ttsChunks[0]!,
-          ...(voiceOutPlan.voice != null ? { voice: voiceOutPlan.voice } : {}),
-          speed: voiceOutPlan.speed,
+          token: listenPlan.token,
+          text: listenPlan.payload.text,
+          ...(listenPlan.payload.voice != null ? { voice: listenPlan.payload.voice } : {}),
+          speed: listenPlan.payload.speed,
         })
       }
     }

package/telegram-plugin/gateway/outbox-listen-markup.ts

@@ -0,0 +1,67 @@
+/**
+ * outbox-listen-markup.ts — wires the shared `planListenButton` decision into
+ * the durable-outbox safety-net delivery (outbox-sweep.ts), so a net-delivered
+ * final answer carries the SAME 🔊 Listen button / voice-out keyboard the normal
+ * `sendReply` path injects (switchroom #3502 regression: the sweep sent captured
+ * prose via a RAW `bot.api.sendMessage` with no voice-out resolution, dropping
+ * the button).
+ *
+ * Extracted from gateway.ts so the wiring lives in a module (the #2996 gateway
+ * anti-inflation ratchet) and is independently testable.
+ */
+
+import {
+  planListenButton,
+  type ListenButtonVoiceOutPlan,
+  type VoiceOnDemandPayload,
+} from '../voice-ondemand.js'
+import type { OutboxDeliveryMarkup } from './outbox-sweep.js'
+
+/** The minimal side-effecting deps the resolver needs — mirrors what `sendReply`
+ *  does on the normal path (cache put + eager pre-synth), kept as an injected
+ *  surface so gateway.ts passes its own singletons and this stays unit-testable. */
+export interface OutboxListenMarkupDeps {
+  /** Resolve the agent's voice-out plan for a reply body (loadAccess().voice_out
+   *  → resolveVoiceOutPlan). Returns null when voice-out is off / not applicable. */
+  resolveVoiceOutPlan: (replyText: string) => ListenButtonVoiceOutPlan | null
+  /** Persist a minted token so a Listen tap can resynthesize. A thin closure
+   *  (not the cache instance) so the gateway can pass it before its module-scope
+   *  `voiceOnDemandCache` const is initialized (this factory runs at wiring time,
+   *  earlier in gateway.ts than the cache declaration). */
+  cachePut: (token: string, payload: VoiceOnDemandPayload) => void
+  /** True when eager pre-synth is enabled (kill switch off). */
+  eagerVoiceEnabled: () => boolean
+  /** Enqueue an eager pre-synth job (best-effort, off the critical path). */
+  enqueuePreSynth: (job: { token: string; text: string; voice?: string; speed: number }) => void
+}
+
+/**
+ * Build the `resolveReplyMarkup` callback for `startOutboxSweep`. Returns the
+ * Listen keyboard (and persists the token + eager-synth job) when kokoro
+ * on-demand voice-out is enabled and the empty-TTS / collision gates pass;
+ * otherwise undefined → the sweep delivers plain.
+ *
+ * A net-delivered captured-prose answer never carries an agent keyboard, so
+ * `rawKeyboard` is always undefined here; `planListenButton` still enforces the
+ * empty-TTS guard and the kokoro-on-demand gate.
+ */
+export function makeOutboxListenMarkupResolver(
+  deps: OutboxListenMarkupDeps,
+): (chatId: string, threadId: number | null, text: string) => OutboxDeliveryMarkup | undefined {
+  return (_chatId, _threadId, text) => {
+    const voiceOutPlan = deps.resolveVoiceOutPlan(text)
+    const listenPlan = planListenButton({ voiceOutPlan, rawKeyboard: undefined })
+    if (listenPlan == null) return undefined
+    const payload: VoiceOnDemandPayload = listenPlan.payload
+    deps.cachePut(listenPlan.token, payload)
+    if (deps.eagerVoiceEnabled()) {
+      deps.enqueuePreSynth({
+        token: listenPlan.token,
+        text: payload.text,
+        ...(payload.voice != null ? { voice: payload.voice } : {}),
+        speed: payload.speed,
+      })
+    }
+    return listenPlan.replyMarkup
+  }
+}

package/telegram-plugin/gateway/outbox-sweep.ts

@@ -42,6 +42,7 @@ import {
   sha256Hex,
   type OutboxRecord,
 } from '../outbox.js'
+import { isShownBlock } from '../shown-ledger.js'
 import { resolveSubagentOriginTurnKey } from '../registry/subagents-schema.js'
 import { createRetryApiCall, retryWithThreadFallback } from '../retry-api-call.js'
 
@@ -115,11 +116,32 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
       routable: resolved != null,
       routePrefix,
       quietMs: deps.quietMs ?? OUTBOX_QUIET_MS,
+      // #3513: suppress a record whose text was already surfaced on the ephemeral
+      // progress card for this turn (durable shown-ledger). The invariant forbids
+      // a second, out-of-process delivery of an ephemeral-shown block.
+      shownLedgerHit: isShownBlock(record.turnNonce, record.text, deps.stateDir),
     })
 
     if (decision.action !== 'send' && decision.action !== 'send-delayed') {
       summary.skipped++
-      if (decision.action === 'skip-journaled') {
+      if (decision.action === 'skip-ephemeral-shown') {
+        // Ephemeral-shown (#3513): the block already lives on the progress card.
+        // Journal the nonce and drop the record so the sweep never re-scans it
+        // and a racing machine also skips — same terminal bookkeeping as a dedup
+        // hit, but the reason is "assigned to the ephemeral surface".
+        appendDelivered(
+          {
+            turnNonce: record.turnNonce,
+            textSha256: record.textSha256,
+            ts: now,
+            deliverySource: 'sweep',
+            replyAlreadyDeliveredThisTurn: record.replyAlreadyDeliveredThisTurn === true,
+          },
+          deps.stateDir,
+        )
+        clearOutboxRecord(record.turnNonce, deps.stateDir)
+        log(`outbox-sweep: suppressed ephemeral-shown nonce=${record.turnNonce}\n`)
+      } else if (decision.action === 'skip-journaled') {
         // Already delivered under this nonce by another machine → drop the
         // pending record. clearOutboxRecord unlinks the `.json` (the pending
         // file) AND any `.sending` — the pre-fix `removeClaimed` only unlinked
@@ -222,39 +244,113 @@ export const OUTBOX_SWEEP_INTERVAL_MS = 5_000
  * (`resolveSubagentOriginTurnKey`) then the last-real-inbound fallback (H3).
  * Kill switch: `SWITCHROOM_TG_OUTBOX_DELIVERY=0`.
  */
+/** A Telegram inline keyboard the sweep attaches to the FINAL delivered chunk
+ *  (the 🔊 Listen button / voice-out keyboard — switchroom #3502 regression fix,
+ *  so a net-delivered answer keeps the same button a `sendReply` answer gets).
+ *  Shaped to match `planListenButton().replyMarkup`. */
+export type OutboxDeliveryMarkup = {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>
+}
+
+/** Minimal bot-api surface the sweep needs to deliver text. */
+type OutboxSendBot = {
+  api: {
+    sendMessage: (
+      chatId: string,
+      text: string,
+      opts: object,
+    ) => Promise<{ message_id?: number }>
+  }
+}
+
+/**
+ * Build the chunked `send` the sweep hands to {@link sweepOutbox}. Extracted +
+ * exported so the reply-markup attachment (the #3502 fix) is unit-testable
+ * without a live gateway or timer.
+ *
+ * `resolveReplyMarkup` resolves the voice-out Listen button / keyboard for a
+ * delivery (null/undefined → no button). It is applied to the FINAL chunk ONLY
+ * so the button lands on the last visible message, exactly like the normal
+ * `sendReply` path (buttons attach to the last chunk there too). This makes a
+ * safety-net-delivered final answer indistinguishable from a normally-delivered
+ * one instead of silently dropping the button.
+ */
+export function createOutboxSend(deps: {
+  getBot: () => OutboxSendBot | undefined
+  retry: Parameters<typeof retryWithThreadFallback>[0]
+  resolveReplyMarkup?: (
+    chatId: string,
+    threadId: number | null,
+    text: string,
+  ) => OutboxDeliveryMarkup | undefined
+}): OutboxSweepDeps['send'] {
+  return async (chatId, threadId, text) => {
+    const bot = deps.getBot()
+    if (bot == null) throw new Error('outbox-sweep: bot unavailable')
+    // Empty text → nothing to deliver. Telegram rejects an empty message body,
+    // so sending one chunk of '' would throw every tick and wedge the sweep in
+    // a permanent retry (the record never journals → never clears). Return
+    // early, matching the pre-refactor loop's zero-chunk behaviour.
+    if (text.length === 0) return undefined
+    // Resolve the Listen button / keyboard ONCE from the full answer text; it
+    // rides only on the final chunk below.
+    const replyMarkup = deps.resolveReplyMarkup?.(chatId, threadId, text)
+    // Chunk to Telegram's 4096-char ceiling; each chunk goes through the
+    // standard retry / flood-wait / thread-fallback wrapper. A thrown send
+    // propagates so the sweep releases the claim and retries next tick (the
+    // record is never journaled → never lost).
+    let lastId: number | undefined
+    const chunkCount = Math.ceil(text.length / 4000)
+    for (let i = 0, idx = 0; i < text.length; i += 4000, idx++) {
+      const chunk = text.slice(i, i + 4000)
+      const isLast = idx === chunkCount - 1
+      const res = await retryWithThreadFallback(
+        deps.retry,
+        (tid) => {
+          const base = tid != null ? { message_thread_id: tid } : {}
+          // Button on the LAST chunk only (final visible message).
+          const opts =
+            isLast && replyMarkup != null ? { ...base, reply_markup: replyMarkup } : base
+          return bot.api.sendMessage(chatId, chunk, opts)
+        },
+        { threadId: threadId ?? undefined, chat_id: chatId, verb: 'outbox-sweep.sendMessage' },
+      )
+      lastId = res?.message_id
+    }
+    return lastId
+  }
+}
+
 export function startOutboxSweep(deps: {
   isGatewayMain: boolean
   stateDir: string
-  getBot: () => { api: { sendMessage: (chatId: string, text: string, opts: object) => Promise<{ message_id?: number }> } } | undefined
+  getBot: () => OutboxSendBot | undefined
   getTurnsDb: () => Parameters<typeof resolveSubagentOriginTurnKey>[0] | null
   dedupCheck: (chatId: string, threadId: number | undefined, text: string) => boolean
+  /** Resolve the voice-out Listen button / keyboard for a net delivery. Wired
+   *  by the gateway (loadAccess → resolveVoiceOutPlan → planListenButton +
+   *  cache put + eager pre-synth). Absent → deliver plain (legacy behaviour). */
+  resolveReplyMarkup?: (
+    chatId: string,
+    threadId: number | null,
+    text: string,
+  ) => OutboxDeliveryMarkup | undefined
   log?: (line: string) => void
 }): ReturnType<typeof setInterval> | undefined {
   if (!deps.isGatewayMain || process.env.SWITCHROOM_TG_OUTBOX_DELIVERY === '0') return undefined
   const retry = createRetryApiCall({ log: deps.log })
+  const send = createOutboxSend({
+    getBot: deps.getBot,
+    retry,
+    ...(deps.resolveReplyMarkup != null ? { resolveReplyMarkup: deps.resolveReplyMarkup } : {}),
+  })
   const tick = () => {
     const bot = deps.getBot()
     if (bot == null) return
     void sweepOutbox({
       stateDir: deps.stateDir,
       log: deps.log,
-      send: async (chatId, threadId, text) => {
-        // Chunk to Telegram's 4096-char ceiling; each chunk goes through the
-        // standard retry / flood-wait / thread-fallback wrapper. A thrown send
-        // propagates so the sweep releases the claim and retries next tick (the
-        // record is never journaled → never lost).
-        let lastId: number | undefined
-        for (let i = 0; i < text.length; i += 4000) {
-          const chunk = text.slice(i, i + 4000)
-          const res = await retryWithThreadFallback(
-            retry,
-            (tid) => bot.api.sendMessage(chatId, chunk, tid != null ? { message_thread_id: tid } : {}),
-            { threadId: threadId ?? undefined, chat_id: chatId, verb: 'outbox-sweep.sendMessage' },
-          )
-          lastId = res?.message_id
-        }
-        return lastId
-      },
+      send,
       textAlreadyDelivered: (chatId, threadId, text) => deps.dedupCheck(chatId, threadId ?? undefined, text),
       registryChainLookup: (taskId) => {
         const db = deps.getTurnsDb()
@@ -295,6 +391,14 @@ export function journalExternalDelivery(
      * same nonce is provably a double-send from the journal alone.
      */
     replyAlreadyDeliveredThisTurn?: boolean
+    /**
+     * #3513 follow-up: which backstop/machine delivered. Defaults to
+     * `'reply-tool'` (the E0/E3 reply-path callers). The turn-flush backstop
+     * (E1/E2) passes `'flush'` so `backstopAlreadyDelivered` recognises it as a
+     * prior backstop and E3/E4 skip a duplicate durably (across a crash between
+     * the flush send and its journal write), not just via the in-memory dedup.
+     */
+    deliverySource?: 'sweep' | 'reply-tool' | 'flush'
   },
   stateDir?: string,
   now: number = Date.now(),
@@ -307,7 +411,7 @@ export function journalExternalDelivery(
       textSha256: sha256Hex(args.text),
       tgMessageId: args.tgMessageId,
       ts: now,
-      deliverySource: 'reply-tool',
+      deliverySource: args.deliverySource ?? 'reply-tool',
       ...(args.replyAlreadyDeliveredThisTurn == null
         ? {}
         : { replyAlreadyDeliveredThisTurn: args.replyAlreadyDeliveredThisTurn }),