switchroom 0.19.12 → 0.19.13

package/telegram-plugin/final-answer-detect.ts

@@ -120,3 +120,26 @@ export function isSubstantiveFinalReply(input: FinalAnswerReplyInput): boolean {
   if (input.text.length >= FINAL_ANSWER_MIN_CHARS) return true
   return false
 }
+
+/**
+ * F3 gate: should the legacy reply-site (`outbound-send-path.ts` sendReply)
+ * journal THIS reply's delivery under the turn nonce for the outbox sweep?
+ *
+ * This is deliberately `isSubstantiveFinalReply`, NOT `isFinalAnswerReply`.
+ * At the reply site the journaled text is the REPLY text — a DIFFERENT string
+ * from the trailing prose the Stop hook may capture under the SAME turn nonce
+ * (unlike the silent-anchor flush / captured-prose bridge, where the journaled
+ * text IS the turn's trailing content and a loose gate is loss-safe).
+ *
+ * `isFinalAnswerReply`'s ping clause classifies a short pinging interim ack
+ * ("On it — digging in", `disable_notification` omitted) as final. If such an
+ * ack journaled the turn nonce, and the model then ended the turn with
+ * gateway-invisible trailing prose (the real answer) captured under that same
+ * nonce, the sweep would hit `skip-journaled` and delete the real answer —
+ * silent loss, the exact incident this outbox exists to prevent. Requiring a
+ * SUBSTANTIVE reply (`done` or ≥200 chars) to journal keeps the double-post
+ * guard for genuine answers while never letting a pinging ack poison the nonce.
+ */
+export function shouldJournalReplySiteDelivery(input: FinalAnswerReplyInput): boolean {
+  return isSubstantiveFinalReply(input)
+}

package/telegram-plugin/gateway/gateway.ts

@@ -443,6 +443,7 @@ import { richMessage } from '../rich-send.js'
 import { decideRedeliver, decideRedeliverCapture } from './redelivery-decision.js'
 import { scrubVoice } from '../text-voice-scrub.js'
 import {
+  normalizeOutboundBody,
   sendReplyChunks,
   sendReply,
   deliverCapturedProse as deliverCapturedProseCore,
@@ -904,6 +905,7 @@ import {
   TURN_ACTIVE_IDLE_SWEEP_MS,
 } from './turn-active-marker.js'
 import { startGatewayHeartbeat } from './gateway-heartbeat.js'
+import { startOutboxSweep } from './outbox-sweep.js'
 import {
   VERSION,
   COMMIT_SHA,
@@ -9822,20 +9824,15 @@ function trackRedeliveredInbound(merged: InboundMessage): void {
 // `runDeliveryConfirmSweep` / `redeliverStrandedInbound` / `sweepSuspendedTargets`
 // moved VERBATIM; the gateway keeps the deps builder, thin wrappers, and the
 // `setInterval` registration below (P0c: modules export the tick body; the
-// gateway owns the timer). The idle gate crosses as `getCurrentTurnNull` ONLY
-// (the design's C1 deps shape — never the machine's eager in-turn state).
+// gateway owns the timer). Idle gate crosses as `getCurrentTurnNull` ONLY.
 
 /** Live gateway deps for the extracted delivery-confirm sweep wiring. */
 function gatewayDeliveryConfirmDeps() {
   return {
-    DELIVERY_CONFIRM_ENABLED,
-    DELIVERY_CONFIRM_TIMEOUT_MS,
+    DELIVERY_CONFIRM_ENABLED, DELIVERY_CONFIRM_TIMEOUT_MS,
     getCurrentTurnNull: (): boolean => currentTurn == null,
     sendToAgent: (agent: string, m: InboundMessage): boolean => ipcServer.sendToAgent(agent, m),
-    deliveryQueue,
-    pendingInboundBuffer,
-    pendingPermissions,
-    pendingAskUser,
+    deliveryQueue, pendingInboundBuffer, pendingPermissions, pendingAskUser,
   }
 }
 export type DeliveryConfirmWiringDeps = ReturnType<typeof gatewayDeliveryConfirmDeps>
@@ -9852,6 +9849,8 @@ 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)
+
 // #1445 cross-turn pending-async ambient. When a turn ends after the
 // model dispatched background async work (Agent / Task / Bash run-in-
 // background) and the model has stopped speaking, keep editing the
@@ -13303,34 +13302,26 @@ async function executeEditMessage(args: Record<string, unknown>): Promise<unknow
   // Single rich-markdown path (#2669): `format:'text'` edits as a literal
   // plain string; everything else edits via the rich-markdown path.
   const editLiteralText = editFormat === 'text'
-  // Match the reply path: repair JSON-escape bungles, then promote lone prose
-  // paragraph breaks for the rich path. A literal-text edit (`format:'text'`)
-  // skips paragraph normalization — it must edit byte-for-byte as given.
-  let editRawText = repairEscapedWhitespace(args.text as string)
-  if (!editLiteralText) editRawText = normalizeParagraphBreaks(editRawText)
-  // Outbound secret scrub (#2044): an edit must not re-introduce a raw
-  // secret into a live bubble or the history row. Mask before scrub/send.
-  editRawText = redactOutboundText(editRawText, 'edit_message')
-  // Fleet-wide consistent formatting (same order as the reply path: redact
-  // first so secrets are matched literally, then normalize, then spacers on
-  // the rich path only — the rich GFM renderer renders `\n\n` tight, so the
-  // idempotent U+00A0 spacer restores a visible gap without double-spacing).
-  if (!editLiteralText) editRawText = addParagraphSpacers(stripExcessBold(normalizePunctuation(editRawText)))
-  // Voice scrub (#1683): same em-dash scrub as the reply path. Edits
-  // are how silent-anchor and progress-update mutate already-sent
-  // bubbles, so without this an edit can re-introduce dashes the
-  // original send had scrubbed out.
-  {
-    const scrub = scrubVoice(editRawText)
-    if (scrub.replaced > 0) {
-      editRawText = scrub.scrubbed
-      emitRuntimeMetric({
-        kind: 'voice_scrub_applied',
-        chatKey: statusKey(String(args.chat_id ?? ''), undefined),
-        replaced: scrub.replaced,
-        site: 'edit_message',
-      })
-    }
+  // #3501: route through the single shared outbound seam (repair → paragraph-
+  // break → redact → punctuation/bold → temporal → voice scrub) instead of the
+  // former hand-mirrored inline pipeline. The edit path's deviations are options:
+  // literalText skips paragraph/punctuation/bold/spacers + temporal (a literal
+  // edit lands byte-for-byte); addSpacers folds the idempotent U+00A0 paragraph
+  // spacer into the rich formatting step. tz/nowMs drive the temporal pass.
+  const _editNorm = normalizeOutboundBody(args.text as string, 'edit_message', redactOutboundText, {
+    literalText: editLiteralText,
+    addSpacers: !editLiteralText,
+    tz: resolveEnvTimezone(),
+    nowMs: Date.now(),
+  })
+  let editRawText = _editNorm.text
+  if (_editNorm.voiceReplaced > 0) {
+    emitRuntimeMetric({
+      kind: 'voice_scrub_applied',
+      chatKey: statusKey(String(args.chat_id ?? ''), undefined),
+      replaced: _editNorm.voiceReplaced,
+      site: 'edit_message',
+    })
   }
   const edited = await robustApiCall(
     () => lockedBot.api.editMessageText(
@@ -14795,6 +14786,8 @@ export async function handleInbound(
   {
     const inboundChatId = ctx.chat?.id
     if (inboundChatId != null) void dmPinSweeper.sweep(String(inboundChatId))
+    // Outbox envelope-less routing (F2) is scoped to each record's OWN stamped
+    // per-session origin chat (captured at Stop), not a gateway-global stamp.
   }
 
   // Capture wall-clock receive time for inbound_ack metric (#203).

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

@@ -33,6 +33,8 @@ import {
   RICH_MESSAGE_MAX_CHARS,
 } from '../format.js'
 import { scrubVoice } from '../text-voice-scrub.js'
+import { normalizeTemporal } from '../temporal-normalize.js'
+import { resolveEnvTimezone } from '../shared/local-time.js'
 import { isMessageTooLongError, isHtmlParseRejectError } from '../retry-api-call.js'
 
 // ── send-orchestration façade imports (#2996 P2) ──
@@ -49,8 +51,9 @@ import {
   escapeMarkdown,
 } from '../format.js'
 import { richMessage } from '../rich-send.js'
+import { journalExternalDelivery } from './outbox-sweep.js'
 import { resolveChatIdFallback } from './chat-id-fallback.js'
-import { isFinalAnswerReply, isSubstantiveFinalReply } from '../final-answer-detect.js'
+import { isFinalAnswerReply, isSubstantiveFinalReply, shouldJournalReplySiteDelivery } from '../final-answer-detect.js'
 import { decideOverPing, type OverPingDecision } from '../over-ping-safety-net.js'
 import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
 import {
@@ -114,16 +117,59 @@ export interface NormalizeOutboundResult {
 }
 
 /**
- * Stage 1 — the deterministic outbound text transform, byte-identical to the
- * inline pipeline at the entry of executeReply (and mirrored on the
- * answer-stream + turn-flush paths):
+ * Per-site shape knobs for {@link normalizeOutboundBody}. The reply path (the
+ * canonical caller) passes none — the defaults reproduce its exact pre-#3501
+ * byte output. The edit_message and turn-flush sites, which used to hand-mirror
+ * this pipeline inline, pass these to reproduce their two small deviations:
+ *
+ *   - `literalText` (edit_message `format:'text'`): a literal edit must land
+ *     byte-for-byte as authored, so it SKIPS paragraph-break promotion and the
+ *     punctuation/bold/spacer formatting entirely — only the whitespace repair,
+ *     the secret redact, and the voice scrub still run (they are safety
+ *     transforms that must apply even to literal edits, matching the former
+ *     inline `executeEditMessage` order).
+ *   - `addSpacers` (edit_message non-literal): the edit path folds the
+ *     idempotent U+00A0 paragraph spacer INTO this transform
+ *     (`addParagraphSpacers(stripExcessBold(normalizePunctuation(…)))`),
+ *     whereas the reply/turn-flush paths add spacers separately downstream (or
+ *     not at all). Setting this reproduces that inline behaviour exactly.
+ */
+export interface NormalizeOutboundOptions {
+  /** Literal edit: skip paragraph-break + punctuation/bold/spacer formatting. */
+  literalText?: boolean
+  /** Fold `addParagraphSpacers` into the formatting step (edit_message path). */
+  addSpacers?: boolean
+  /**
+   * Agent-configured IANA timezone for the temporal-normalization pass (#3501).
+   * When BOTH `tz` and `nowMs` are supplied (callers pass `resolveEnvTimezone()`
+   * and `Date.now()`), the seam rewrites UTC/Zulu datetimes to local wall clock
+   * and corrects relative-day words against the current date in `tz`. Omitted →
+   * the temporal pass is a no-op (keeps the module pure/clock-free by default).
+   * NEVER fires on a literal edit (`literalText`) — a literal edit lands
+   * byte-for-byte as authored.
+   */
+  tz?: string
+  /** Epoch-ms "now" for the temporal pass. Required alongside `tz` to fire. */
+  nowMs?: number
+}
+
+/**
+ * Stage 1 — the deterministic outbound text transform. This is the SINGLE
+ * shared seam for every outbound prose send (#3501): the reply path, the
+ * edit_message path, and the turn-flush backstop all route through it instead
+ * of hand-mirroring the pipeline inline, so a new outbound transform is added
+ * in exactly one place.
  *
  *   1. repairEscapedWhitespace  — undo LLM JSON-escape bungles
  *   2. normalizeParagraphBreaks — promote lone prose breaks to GFM hard breaks
+ *                                 (skipped for a literal edit)
  *   3. redact (injected)        — outbound secret scrub (#2044), BEFORE the
  *                                 punctuation/bold normalizers so a secret with
  *                                 an em-dash or `**` is matched literally
  *   4. stripExcessBold∘normalizePunctuation — fleet-consistent formatting
+ *                                 (optionally wrapped in addParagraphSpacers for
+ *                                 the edit path; skipped entirely for a literal
+ *                                 edit)
  *   5. scrubVoice               — em/en dash → comma/period (#1683)
  *
  * The order is load-bearing and MUST NOT change (each step's comment in the
@@ -133,10 +179,25 @@ export function normalizeOutboundBody(
   rawText: string,
   site: string,
   redact: RedactFn,
+  opts: NormalizeOutboundOptions = {},
 ): NormalizeOutboundResult {
-  let text = normalizeParagraphBreaks(repairEscapedWhitespace(rawText))
+  const { literalText = false, addSpacers = false, tz, nowMs } = opts
+  let text = repairEscapedWhitespace(rawText)
+  if (!literalText) text = normalizeParagraphBreaks(text)
   text = redact(text, site)
-  text = stripExcessBold(normalizePunctuation(text))
+  if (!literalText) {
+    let formatted = stripExcessBold(normalizePunctuation(text))
+    if (addSpacers) formatted = addParagraphSpacers(formatted)
+    text = formatted
+    // Temporal normalization (#3501): UTC/Zulu → local wall clock, then
+    // relative-day accuracy, resolved in the agent's configured tz. Runs AFTER
+    // punctuation/bold (so masking sees final markdown) and BEFORE the voice
+    // scrub (so a freshly-rewritten "Thu 23 Jul 7:15 pm AEST" is never mangled
+    // by the em/en-dash scrub). Never on a literal edit. Pure / never-throws.
+    if (tz != null && nowMs != null) {
+      text = normalizeTemporal(text, tz, nowMs)
+    }
+  }
   let voiceReplaced = 0
   const scrub = scrubVoice(text)
   if (scrub.replaced > 0) {
@@ -793,7 +854,10 @@ export async function sendReply(
   // retries see the scrubbed dedup key). The metric side effect (fired on a
   // non-zero voice-scrub replacement) stays here — the pure module returns the
   // replacement count and the gateway emits.
-  const _normalized = normalizeOutboundBody(rawText, 'reply', redactOutboundText)
+  const _normalized = normalizeOutboundBody(rawText, 'reply', redactOutboundText, {
+    tz: resolveEnvTimezone(),
+    nowMs: Date.now(),
+  })
   let text = _normalized.text
   if (_normalized.voiceReplaced > 0) {
     emitRuntimeMetric({
@@ -1733,6 +1797,16 @@ export async function sendReply(
             Date.now(),
             turn?.registryKey ?? null,
           )
+          // F1: a FINAL-answer silent-anchor edit journals this legacy delivery
+          // under the shared nonce (turn.turnId === deriveTurnId === the hook's
+          // deriveTurnNonce `${chatKey}#${messageId}` for a gateway-visible turn)
+          // and drops any hook-captured record, so the sweep never re-sends after
+          // the in-memory dedup TTL evicts / a restart clears it / the captured
+          // text differs. Gated so an interim-ack edit never journals the turn
+          // nonce (which would suppress a later genuine answer for the turn).
+          if (isFinalAnswerReply({ text: decision.mergedText, disableNotification: modelDisableNotification })) {
+            journalExternalDelivery({ turnNonce: turn?.turnId ?? null, text: decision.mergedText, tgMessageId: decision.messageId })
+          }
 
           silentAnchorEditDone = true
         } catch (err) {
@@ -2275,7 +2349,31 @@ export async function sendReply(
   // calls with this same content within DEFAULT_DEDUP_TTL_MS will
   // be suppressed.
   if (sentIds.length > 0) {
-    outboundDedup.record(chat_id, threadId, text, Date.now(), getCurrentTurn()?.registryKey ?? null)
+    const t = getCurrentTurn()
+    outboundDedup.record(chat_id, threadId, text, Date.now(), t?.registryKey ?? null)
+    // F1: a SUBSTANTIVE-final reply journals + clears under the shared nonce
+    // (turn.turnId === deriveTurnId, the hook's deriveTurnNonce), so the sweep
+    // never re-posts this turn's answer.
+    //
+    // F3: gate on `isSubstantiveFinalReply`, NOT `isFinalAnswerReply`. Unlike
+    // the flush site (~1741) and the captured-prose bridge (~2407) — where the
+    // journaled text IS this turn's trailing content, so a loose gate is
+    // loss-safe — here the journaled text is the REPLY text, a DIFFERENT string
+    // from the trailing prose the hook captures under the same turn nonce.
+    // `isFinalAnswerReply`'s ping clause (`disableNotification` falsy — the
+    // tool's default, routinely omitted by models) classifies a short pinging
+    // interim ack ("On it — digging in") as final. Journaling on that ack would
+    // poison the turn nonce: the model then ends the turn with gateway-invisible
+    // trailing prose (the real answer), the Stop hook captures it under the SAME
+    // nonce, and the sweep hits `skip-journaled` → `clearOutboxRecord` → the
+    // real answer is silently destroyed — the exact incident class this outbox
+    // exists to prevent. `isSubstantiveFinalReply` (`done === true ||
+    // length ≥ 200`, no ping path) still journals a genuine answer (so the sweep
+    // won't double-post it) while an interim ack never journals (so a later
+    // genuinely-undelivered final answer is delivered by the sweep).
+    if (shouldJournalReplySiteDelivery({ text: rawText, disableNotification: modelDisableNotification })) {
+      journalExternalDelivery({ turnNonce: t?.turnId ?? null, text, tgMessageId: sentIds[sentIds.length - 1] })
+    }
   }
   return { content: [{ type: 'text', text: result }] }
 }
@@ -2383,6 +2481,9 @@ export async function deliverCapturedProse(
       // Record what we just sent so a late reply / stream_reply retry with the
       // same content is deduped at its send site (the #546 dedup cache).
       outboundDedup.record(chatId, threadId, text, now, registryKey)
+      // F1: captured-prose delivery journals + clears under the shared nonce
+      // (`originTurnId` === turn.turnId === deriveTurnId, the hook's nonce).
+      journalExternalDelivery({ turnNonce: originTurnId, text, tgMessageId: sentIds[sentIds.length - 1] })
       process.stderr.write(
         `telegram gateway: captured-prose delivery — sent ${out.length} chars recovered from ` +
           `transcript scan (chat=${chatId} origin=${originTurnId})\n`,

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

@@ -0,0 +1,282 @@
+/**
+ * outbox-sweep.ts — the single deliverer for the guaranteed-final-message
+ * outbox. Runs on the gateway heartbeat tick, independent of turn lifecycle,
+ * so it covers turn CLASSES the gateway never sees a CurrentTurn for
+ * (`<task-notification>` handbacks, background-worker completions, unknown
+ * future wake shapes). See `../outbox.ts` for the record/nonce/journal model.
+ *
+ * Exactly-once (H1): every record is claimed with a rename-mutex, guarded by the
+ * shared delivered-keys journal (same turnNonce every delivering machine uses),
+ * and by the in-memory text `outboundDedup` cache. Delivered nonce is journaled
+ * AFTER a successful send. When a legacy machine (turn-flush / reply / captured
+ * prose) delivered the same turn's answer first, its journal write under the
+ * SAME nonce makes the sweep skip-journaled; and the sweep's own skip-dedup
+ * branch JOURNALS the nonce and DELETES the record (see below) so a text-dedup
+ * hit can never re-fire after the in-memory cache's TTL evicts. A crash between
+ * send and journal is caught next boot by the journal + text-dedup (never a
+ * loss, at most one duplicate).
+ *
+ * Routing (H3/F2): `resolveOutboxChat` runs the injected transitive registry-chain
+ * lookup then the record's OWN stamped per-session origin chat for envelope-less
+ * records — never a gateway-global last-inbound fallback (cross-chat leak). It
+ * FAILS CLOSED (holds the record) when neither resolves.
+ *
+ * The orchestration takes injected IO deps so it is unit-testable without a live
+ * gateway; `gateway.ts` wires the real send / dedup / registry lookups.
+ */
+
+import {
+  OUTBOX_QUIET_MS,
+  appendDelivered,
+  claimRecord,
+  clearOutboxRecord,
+  decideOutboxSweep,
+  extractTaskId,
+  listPendingRecords,
+  readDeliveredNonces,
+  readOutboxRecord,
+  reclaimStaleSending,
+  releaseClaim,
+  removeClaimed,
+  resolveOutboxChat,
+  sha256Hex,
+  type OutboxRecord,
+} from '../outbox.js'
+import { resolveSubagentOriginTurnKey } from '../registry/subagents-schema.js'
+import { createRetryApiCall, retryWithThreadFallback } from '../retry-api-call.js'
+
+export interface OutboxSweepDeps {
+  /** Deliver `text` to the chat. Resolves to the primary message id (best-effort). */
+  send: (
+    chatId: string,
+    threadId: number | null,
+    text: string,
+  ) => Promise<number | undefined>
+  /** Has this exact text already been delivered to this chat/thread recently? */
+  textAlreadyDelivered: (chatId: string, threadId: number | null, text: string) => boolean
+  /**
+   * Transitive registry-chain lookup (H3): resolve the originating chat for a
+   * task-notification / chained-dispatch anchor from its `<task-id>`. Null when
+   * the chain doesn't resolve.
+   */
+  registryChainLookup?: (
+    taskId: string,
+  ) => { chatId: string; threadId: number | null } | null
+  stateDir?: string
+  now?: () => number
+  log?: (line: string) => void
+  quietMs?: number
+}
+
+export interface OutboxSweepSummary {
+  scanned: number
+  delivered: number
+  skipped: number
+}
+
+/**
+ * Sweep the outbox once. Idempotent; safe to call every heartbeat tick.
+ */
+export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSummary> {
+  const now = deps.now?.() ?? Date.now()
+  const log = deps.log ?? (() => {})
+  const summary: OutboxSweepSummary = { scanned: 0, delivered: 0, skipped: 0 }
+
+  // Re-queue crashed claims first (claim-then-crash before send).
+  reclaimStaleSending(deps.stateDir, now)
+
+  const pending = listPendingRecords(deps.stateDir)
+  if (pending.length === 0) return summary
+  const deliveredNonces = readDeliveredNonces(deps.stateDir)
+
+  for (const fileName of pending) {
+    const record = readOutboxRecord(fileName, deps.stateDir)
+    if (record == null) continue
+    summary.scanned++
+
+    // Resolve destination (anchor → registry chain → per-session origin). Fails
+    // CLOSED (null → held) rather than routing to an arbitrary chat (F2).
+    const resolved = resolveOutboxChat(record, {
+      registryChainLookup: (anchorContent) => {
+        const taskId = extractTaskId(anchorContent)
+        if (taskId == null || deps.registryChainLookup == null) return null
+        return deps.registryChainLookup(taskId)
+      },
+    })
+
+    const routePrefix = resolved?.via === 'origin' ? '(from background task) ' : ''
+    const decision = decideOutboxSweep({
+      record,
+      now,
+      deliveredNonces,
+      textAlreadyDelivered:
+        resolved != null &&
+        deps.textAlreadyDelivered(resolved.chatId, resolved.threadId, record.text),
+      routable: resolved != null,
+      routePrefix,
+      quietMs: deps.quietMs ?? OUTBOX_QUIET_MS,
+    })
+
+    if (decision.action !== 'send' && decision.action !== 'send-delayed') {
+      summary.skipped++
+      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
+        // `.sending`, leaking the `.json` to be rescanned forever (S4).
+        clearOutboxRecord(record.turnNonce, deps.stateDir)
+      } else if (decision.action === 'skip-dedup') {
+        // F1: the identical text was already delivered by the legacy flush/reply
+        // (in-memory `outboundDedup` hit). JOURNAL the nonce and DELETE the
+        // record NOW, so once that in-memory cache's TTL evicts (~60s) the sweep
+        // cannot resurrect and re-send this turn's answer. Deterministic
+        // exactly-once, independent of cache lifetime and surviving a restart
+        // (the record is gone from disk, the nonce is durably journaled).
+        appendDelivered(
+          { turnNonce: record.turnNonce, textSha256: record.textSha256, ts: now },
+          deps.stateDir,
+        )
+        clearOutboxRecord(record.turnNonce, deps.stateDir)
+      }
+      continue
+    }
+
+    // Claim (rename mutex). If lost, another sweep/machine has it.
+    const claimed = claimRecord(record.turnNonce, deps.stateDir)
+    if (claimed == null) {
+      summary.skipped++
+      continue
+    }
+    const resolvedChat = resolved! // routable implies non-null
+
+    try {
+      const messageId = await deps.send(
+        resolvedChat.chatId,
+        resolvedChat.threadId,
+        decision.text ?? record.text,
+      )
+      appendDelivered(
+        { turnNonce: record.turnNonce, textSha256: record.textSha256, tgMessageId: messageId, ts: now },
+        deps.stateDir,
+      )
+      removeClaimed(record.turnNonce, deps.stateDir)
+      summary.delivered++
+      log(
+        `outbox-sweep: delivered nonce=${record.turnNonce} via=${resolvedChat.via} ` +
+          `source=${record.source} chars=${record.text.length}${decision.action === 'send-delayed' ? ' (delayed)' : ''}\n`,
+      )
+    } catch (err) {
+      // Send failed — release the claim so the next tick retries. The record is
+      // preserved on disk; no loss.
+      releaseClaim(record.turnNonce, deps.stateDir)
+      summary.skipped++
+      log(`outbox-sweep: send failed nonce=${record.turnNonce}: ${(err as Error).message} — will retry\n`)
+    }
+  }
+  return summary
+}
+
+/**
+ * Parse a registry `turn_key` (`chatId:threadId`, `_` → null thread) into a
+ * routable chat. Exported for the gateway wiring + tests.
+ */
+export function chatFromTurnKey(turnKey: string): { chatId: string; threadId: number | null } {
+  const idx = turnKey.indexOf(':')
+  const chatId = idx === -1 ? turnKey : turnKey.slice(0, idx)
+  const tRaw = idx === -1 ? '_' : turnKey.slice(idx + 1)
+  const t = tRaw === '_' || tRaw === '' ? null : Number(tRaw)
+  return { chatId, threadId: Number.isFinite(t as number) ? t : null }
+}
+
+/** How often the sweep ticks (aligned with the delivery-confirm sweep cadence). */
+export const OUTBOX_SWEEP_INTERVAL_MS = 5_000
+
+/**
+ * Own the heartbeat-tick outbox sweep entirely, keeping the timer / chunking /
+ * turn-key parse / dedup / registry-chain wiring OUT of `gateway.ts` (the line
+ * ratchet). The gateway passes only the primitives that must come from its
+ * scope: lazy getters for `bot` / `turnsDb` (both assigned late), its live
+ * `OutboundDedupCache`, and the state dir. Returns the interval handle (unref'd)
+ * or `undefined` when disabled / not the main process.
+ *
+ * Delivery reuses `bot.api.sendMessage` and chunks to Telegram's 4096-char
+ * ceiling so an oversized record can never wedge the sweep in a permanent
+ * retry loop. Routing runs the transitive registry chain
+ * (`resolveSubagentOriginTurnKey`) then the last-real-inbound fallback (H3).
+ * Kill switch: `SWITCHROOM_TG_OUTBOX_DELIVERY=0`.
+ */
+export function startOutboxSweep(deps: {
+  isGatewayMain: boolean
+  stateDir: string
+  getBot: () => { api: { sendMessage: (chatId: string, text: string, opts: object) => Promise<{ message_id?: number }> } } | undefined
+  getTurnsDb: () => Parameters<typeof resolveSubagentOriginTurnKey>[0] | null
+  dedupCheck: (chatId: string, threadId: number | undefined, text: string) => boolean
+  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 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
+      },
+      textAlreadyDelivered: (chatId, threadId, text) => deps.dedupCheck(chatId, threadId ?? undefined, text),
+      registryChainLookup: (taskId) => {
+        const db = deps.getTurnsDb()
+        if (db == null) return null
+        const turnKey = resolveSubagentOriginTurnKey(db, taskId)
+        return turnKey == null ? null : chatFromTurnKey(turnKey)
+      },
+    }).catch((err) => deps.log?.(`outbox-sweep: tick failed: ${(err as Error).message}\n`))
+  }
+  const timer = setInterval(tick, OUTBOX_SWEEP_INTERVAL_MS)
+  timer.unref?.()
+  return timer
+}
+
+/**
+ * Journal a delivery made by a NON-sweep machine (legacy turn-flush /
+ * captured-prose bridge / exhausted fallback / final-answer reply send) under
+ * the shared nonce, AND drop any pending outbox record for it — the reply-path
+ * clear-by-nonce (H1/F1). Wired at every legacy delivery site with the gateway's
+ * own `deriveTurnId` nonce (`turn.turnId`), which is byte-identical to the
+ * hook's `deriveTurnNonce` `${chatKey}#${messageId}` for a gateway-visible turn, so:
+ *   - the journal write makes a later sweep skip-journaled even after the
+ *     in-memory `outboundDedup` TTL has evicted or the gateway restarted, and
+ *   - `clearOutboxRecord` removes the hook's captured record immediately when
+ *     the flush text differs from the captured text (text-dedup would miss).
+ * Best-effort; never throws. A null/empty nonce is ignored (nothing to journal).
+ */
+export function journalExternalDelivery(
+  args: { turnNonce: string | null; text: string; tgMessageId?: number },
+  stateDir?: string,
+  now: number = Date.now(),
+): void {
+  const nonce = args.turnNonce
+  if (nonce == null || nonce === '') return
+  appendDelivered(
+    { turnNonce: nonce, textSha256: sha256Hex(args.text), tgMessageId: args.tgMessageId, ts: now },
+    stateDir,
+  )
+  clearOutboxRecord(nonce, stateDir)
+}
+
+export type { OutboxRecord }