switchroom 0.19.41 → 0.19.43

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

@@ -26,6 +26,7 @@
  */
 
 import {
+  OUTBOX_MAX_AGE_MS,
   OUTBOX_QUIET_MS,
   appendDelivered,
   claimRecord,
@@ -42,9 +43,16 @@ import {
   sha256Hex,
   type OutboxRecord,
 } from '../outbox.js'
+import {
+  AUDIENCE_INTERNAL,
+  formatInternalSuppression,
+  formatReplyThrowFraming,
+  resolveRecordAudience,
+  shouldSuppressForAudience,
+} from '../hooks/audience-classify.mjs'
 import { isShownBlock } from '../shown-ledger.js'
 import { richMessage, isParseEntitiesError } from '../rich-send.js'
-import { splitMarkdownChunks } from '../format.js'
+import { splitMarkdownChunks, splitPlainTextToCap } from '../format.js'
 import { resolveSubagentOriginTurnKey } from '../registry/subagents-schema.js'
 import { createRetryApiCall, retryWithThreadFallback } from '../retry-api-call.js'
 import {
@@ -124,6 +132,36 @@ export interface OutboxSweepDeps {
    * does: a broken marker file must never permanently strand the outbox.
    */
   floodWaitRemainingMs?: () => number
+  /**
+   * W1-d (#3865) kill switch for the audience gate. Defaults to the env read
+   * `SWITCHROOM_TG_OUTBOX_AUDIENCE_GATE !== '0'` (ON by default; `=0` restores
+   * the pre-change leak). Injected rather than read at module scope so the
+   * revert-check test can flip it deterministically inside one process — a
+   * module-level const would be captured at import and the revert-check could
+   * not run at all.
+   */
+  audienceGateEnabled?: () => boolean
+  /**
+   * W1-d (#3865) structured-telemetry sink for a suppressed `'internal'`
+   * record. Mirrors `escalateOrphan` (#4104): a SEPARATE, non-chat channel, so
+   * the escalation path for internal prose is structurally incapable of
+   * becoming a message. Defaults to `log`.
+   */
+  escalateInternalSuppression?: (line: string) => void
+  /**
+   * W1-d follow-up (#4141) kill switch for the reply-throw provenance banner.
+   * Defaults to `SWITCHROOM_TG_OUTBOX_PROVENANCE_FRAMING !== '0'` (ON). Same
+   * injected-seam reasoning as {@link audienceGateEnabled}: a module-scope env
+   * read would be captured at import and the revert-check could not run.
+   */
+  provenanceFramingEnabled?: () => boolean
+  /**
+   * W1-d follow-up (#4141) telemetry sink for a FRAMED delivery. Separate from
+   * {@link escalateInternalSuppression} because the two outcomes are different
+   * (withheld vs. delivered-with-provenance) and must be greppable apart.
+   * Defaults to `log`.
+   */
+  logProvenanceFraming?: (line: string) => void
 }
 
 export interface OutboxSweepSummary {
@@ -140,6 +178,18 @@ export interface OutboxSweepSummary {
   floodDeferred?: boolean
   /** Remaining ms of the window that caused `floodDeferred`. */
   floodRemainingMs?: number
+  /**
+   * W1-d (#3865): records withheld from the chat this sweep because their
+   * audience is `'internal'`. Counted separately from `skipped` so "we
+   * suppressed a leak" is never confused with "we deferred a delivery".
+   */
+  audienceSuppressed?: number
+  /**
+   * W1-d follow-up (#4141): deliveries this sweep that carried the reply-throw
+   * provenance banner. These ARE counted in `delivered` — framing is a
+   * delivery, not a skip.
+   */
+  provenanceFramed?: number
 }
 
 /**
@@ -190,9 +240,66 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
             : 0,
     )
 
+  const audienceGateEnabled = deps.audienceGateEnabled?.() ??
+    process.env.SWITCHROOM_TG_OUTBOX_AUDIENCE_GATE !== '0'
+  const escalateInternalSuppression = deps.escalateInternalSuppression ?? log
+  const provenanceFramingEnabled = deps.provenanceFramingEnabled?.() ??
+    process.env.SWITCHROOM_TG_OUTBOX_PROVENANCE_FRAMING !== '0'
+  const logProvenanceFraming = deps.logProvenanceFraming ?? log
+
   for (const record of records) {
     summary.scanned++
 
+    // ── W1-d (#3865): AUDIENCE GATE ─────────────────────────────────────────
+    //
+    // Placed at ENTRY SELECTION — before routing, before the claim, before any
+    // adapter is consulted — and NOT inside the send adapter. That placement is
+    // the whole design: W1-b replaces the send adapter wholesale, and a gate
+    // living inside the adapter would leave with it. Here, an `'internal'`
+    // record simply never becomes a send candidate, whatever is wired below.
+    //
+    // Terminal, not deferred: we journal the nonce and delete the record, so a
+    // second tick has nothing to look at and the decision survives a restart.
+    // The escalation is STRUCTURED TELEMETRY on a non-chat channel — internal
+    // prose has exactly one exit from this pipeline, and it is not Telegram.
+    if (shouldSuppressForAudience(record, { gateEnabled: audienceGateEnabled })) {
+      summary.skipped++
+      summary.audienceSuppressed = (summary.audienceSuppressed ?? 0) + 1
+      const ageMs = now - record.createdAt
+      appendDelivered(
+        {
+          turnNonce: record.turnNonce,
+          textSha256: record.textSha256,
+          ts: now,
+          // The record is TERMINALLY resolved by the sweep machine — the same
+          // provenance a delivery would carry, so every exactly-once guard
+          // (`backstopAlreadyDelivered`, the turn-flush backstop) also treats
+          // this turn as settled and no other machine re-delivers the prose.
+          deliverySource: 'sweep',
+          replyAlreadyDeliveredThisTurn: record.replyAlreadyDeliveredThisTurn === true,
+          audience: AUDIENCE_INTERNAL,
+          // The honest terminal state: withheld by design. Recorded as an
+          // explicit named outcome rather than as an absence, so suppression
+          // reads as telemetry and never as a delivery failure.
+          suppressedAudience: AUDIENCE_INTERNAL,
+        },
+        deps.stateDir,
+      )
+      clearOutboxRecord(record.turnNonce, deps.stateDir)
+      escalateInternalSuppression(
+        formatInternalSuppression({
+          turnNonce: record.turnNonce,
+          turnId: turnIdFromNonce(record.turnNonce),
+          chatId: record.chatId,
+          textSha256: record.textSha256,
+          ageMs,
+          source: record.source,
+          pastWindow: ageMs > OUTBOX_MAX_AGE_MS,
+        }),
+      )
+      continue
+    }
+
     // Resolve destination (anchor → registry chain → per-session origin). Fails
     // CLOSED (null → held) rather than routing to an arbitrary chat (F2).
     const resolved = resolveOutboxChat(record, {
@@ -218,6 +325,22 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
       // 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),
+      // ── W1-d follow-up (#4141): PROVENANCE FRAMING ───────────────────────
+      //
+      // The residual case #4140 deliberately leaves open: the reply tool threw
+      // on a FOREGROUND turn, so the inbound obligation is still OPEN, the
+      // record classifies `'user'`, and the captured trailing prose delivers
+      // presented as if it were the answer.
+      //
+      // We do NOT suppress here, and that is the design, not a compromise.
+      // Someone is provably still waiting; there is no deterministic signal
+      // that separates "working notes" from "the answer re-written as plain
+      // prose after the tool errored" (see `audience-classify.mjs`). Dropping
+      // the text would trade a visible wrong-content failure for an invisible
+      // no-answer one — the exact severity-3 class this whole line of work
+      // exists to prevent. So we state the provenance instead, and the human
+      // (who can tell the difference, unlike any classifier here) decides.
+      provenanceFraming: provenanceFramingEnabled,
     })
 
     if (decision.action !== 'send' && decision.action !== 'send-delayed') {
@@ -293,9 +416,28 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
           // turn) is provable from the journal alone.
           deliverySource: 'sweep',
           replyAlreadyDeliveredThisTurn: record.replyAlreadyDeliveredThisTurn === true,
+          // #4141: the durable terminal stamp for a framed delivery. Written on
+          // the same line as the delivery it describes, so "what did the user
+          // actually see" is answerable from the journal alone after the logs
+          // have rotated.
+          ...(decision.framedProvenance != null
+            ? { framedProvenance: decision.framedProvenance }
+            : {}),
         },
         deps.stateDir,
       )
+      if (decision.framedProvenance != null) {
+        summary.provenanceFramed = (summary.provenanceFramed ?? 0) + 1
+        logProvenanceFraming(
+          formatReplyThrowFraming({
+            turnNonce: record.turnNonce,
+            turnId: turnIdFromNonce(record.turnNonce),
+            chatId: resolvedChat.chatId,
+            textSha256: record.textSha256,
+            source: record.source,
+          }),
+        )
+      }
       // Persist parity (mirrors outbound-send-path.ts + backstop-delivery.ts):
       // record the delivered chunk ids + texts to history so a net-delivered
       // answer is not silently absent from history.db. Best-effort — a missing
@@ -330,6 +472,20 @@ export async function sweepOutbox(deps: OutboxSweepDeps): Promise<OutboxSweepSum
   return summary
 }
 
+/**
+ * W1-d (#3865): recover the gateway `turnId` from an envelope-derived nonce.
+ *
+ * `deriveTurnNonce` builds `${chatId}:${threadId||'_'}#${messageId}` — byte-
+ * identical to the gateway's `deriveTurnId` — so an envelope-bearing nonce IS
+ * the turn id and `extractTurnId` in `src/fleet-health/detect.ts` can join the
+ * suppression telemetry back to the turn record. The sha256 fallback nonce
+ * (envelope-less anchors) carries no turn id; return null rather than emit a
+ * hash that looks like one.
+ */
+export function turnIdFromNonce(nonce: string): string | null {
+  return /^-?\d+:[^#]*#\d+$/.test(nonce) ? nonce : null
+}
+
 /** Read the flood probe, failing OPEN on any throw. */
 function probeFloodWindow(probe: (() => number) | undefined): number {
   if (probe == null) return 0
@@ -460,22 +616,91 @@ type OutboxSendBot = {
  * caught here — it propagates so `retryWithThreadFallback` and the sweep's
  * claim-release retry handle it, exactly as before.
  */
+/**
+ * #4043: the plain fallback is RE-CAPPED to `PLAIN_TEXT_MAX_CHARS` (4096). The
+ * caller splits at the RICH cap (32768 — `splitMarkdownChunks`' default), so an
+ * oversized chunk that parse-rejected used to be re-sent to the plain endpoint
+ * whole, get `message is too long`, throw, release the claim, and retry on the
+ * NEXT tick forever: the record could never be delivered and never cleared.
+ * Returns one entry per message actually landed (the plain fallback can land
+ * several) so the caller's history / journal bookkeeping stays aligned with the
+ * wire. A trailing `reply_markup` (the Listen button) rides the FINAL piece
+ * only, exactly as it rides the final chunk.
+ */
+/**
+ * Resume state for ONE chunk, owned by the caller and therefore SURVIVING a
+ * re-invocation of the send closure.
+ *
+ * The caller wraps this whole function — the multi-send plain-fallback loop
+ * included — in `retryWithThreadFallback(deps.retry, …)`, and
+ * `createRetryApiCall` re-invokes the closure it was given after a flood wait
+ * (`../retry-api-call.ts`). Without resume state, a 429 on plain piece 4 of 5
+ * meant the retry re-ran the closure from the top: the rich send
+ * DETERMINISTICALLY parse-rejects again and pieces 1-3 are re-delivered to the
+ * user's chat — repeating every attempt until the whole loop happens to
+ * succeed. A mid-loop 429 is likely precisely in the flood conditions the
+ * sweep runs under, so this is the common case, not the exotic one.
+ *
+ * Carrying landed-piece state (rather than wrapping each `sendMessage` in its
+ * own nested `deps.retry`) is what makes the send IDEMPOTENT under ANY
+ * re-invocation — the retry policy's flood re-drive AND
+ * `retryWithThreadFallback`'s thread-drop re-drive — instead of only the one
+ * we thought of. Nesting a retry inside the outer retry would instead multiply
+ * the attempt and flood-sleep budgets (maxRetries²) at exactly the moment the
+ * policy exists to issue LESS, and would still re-send pieces 1-3 whenever the
+ * inner budget was exhausted and the error bubbled to the outer wrapper.
+ */
+interface ChunkSendState {
+  /** The rich send already parse-rejected — skip straight to the plain loop. */
+  parseRejected: boolean
+  /** Plain pieces already ON THE WIRE, in order. Never re-sent. */
+  landed: Array<{ message_id?: number; text: string }>
+}
+
+function newChunkSendState(): ChunkSendState {
+  return { parseRejected: false, landed: [] }
+}
+
 async function sendChunkRich(
   bot: OutboxSendBot,
   chatId: string,
   chunk: string,
   opts: object,
-): Promise<{ message_id?: number }> {
-  try {
-    // allow-raw-bot-api: caller (createOutboxSend) invokes this inside retryWithThreadFallback + createRetryApiCall
-    return await bot.api.sendRichMessage(chatId, richMessage(chunk), opts)
-  } catch (err) {
-    if (isParseEntitiesError(err)) {
-      // allow-raw-bot-api: parse-reject plain fallback, still inside the sweep's retryWithThreadFallback wrapper
-      return await bot.api.sendMessage(chatId, chunk, opts)
+  state: ChunkSendState = newChunkSendState(),
+): Promise<Array<{ message_id?: number; text: string }>> {
+  // A re-invocation after the rich send already parse-rejected must NOT
+  // re-issue it: the reject is deterministic (same body, same renderer), so
+  // the only thing another attempt buys is one more 400 against a
+  // flood-sensitive endpoint.
+  if (!state.parseRejected) {
+    try {
+      // allow-raw-bot-api: caller (createOutboxSend) invokes this inside retryWithThreadFallback + createRetryApiCall
+      const sent = await bot.api.sendRichMessage(chatId, richMessage(chunk), opts)
+      return [{ message_id: sent?.message_id, text: chunk }]
+    } catch (err) {
+      if (!isParseEntitiesError(err)) throw err
+      state.parseRejected = true
     }
-    throw err
   }
+
+  const pieces = splitPlainTextToCap(chunk)
+  const withoutMarkup = { ...(opts as Record<string, unknown>) }
+  delete withoutMarkup.reply_markup
+  // Resume at the first piece that has NOT landed. On a first invocation
+  // `landed` is empty and this is the plain 0..n loop.
+  for (let p = state.landed.length; p < pieces.length; p++) {
+    const isFinalPiece = p === pieces.length - 1
+    // allow-raw-bot-api: parse-reject plain fallback, still inside the sweep's retryWithThreadFallback wrapper
+    const sent = await bot.api.sendMessage(
+      chatId,
+      pieces[p],
+      isFinalPiece ? opts : withoutMarkup,
+    )
+    // Recorded BEFORE the next iteration can throw, so a mid-loop failure
+    // leaves the state pointing at the first UNSENT piece.
+    state.landed.push({ message_id: sent?.message_id, text: pieces[p] })
+  }
+  return state.landed
 }
 
 /**
@@ -521,6 +746,10 @@ export function createOutboxSend(deps: {
     for (let idx = 0; idx < chunks.length; idx++) {
       const chunk = chunks[idx]
       const isLast = idx === chunks.length - 1
+      // Per-chunk resume state, OUTSIDE the closure the retry policy
+      // re-invokes: a flood wait mid plain-fallback loop must resume at the
+      // first unsent piece, not re-deliver the ones already in the chat.
+      const chunkState = newChunkSendState()
       const res = await retryWithThreadFallback(
         deps.retry,
         (tid) => {
@@ -528,12 +757,17 @@ export function createOutboxSend(deps: {
           // Button on the LAST chunk only (final visible message).
           const opts =
             isLast && replyMarkup != null ? { ...base, reply_markup: replyMarkup } : base
-          return sendChunkRich(bot, chatId, chunk, opts)
+          return sendChunkRich(bot, chatId, chunk, opts, chunkState)
         },
         { threadId: threadId ?? undefined, chat_id: chatId, verb: 'outbox-sweep.sendMessage' },
       )
-      const id = res?.message_id
-      if (id != null) landed.push({ messageId: id, text: chunk })
+      // One entry per message that actually landed — the #4043 plain fallback
+      // can split ONE rich chunk into several 4096-capped plain messages, and
+      // history/backstop bookkeeping must reflect the wire, not the pre-split
+      // chunk.
+      for (const sent of res ?? []) {
+        if (sent.message_id != null) landed.push({ messageId: sent.message_id, text: sent.text })
+      }
     }
     return {
       messageId: landed.length > 0 ? landed[landed.length - 1]!.messageId : undefined,
@@ -542,6 +776,98 @@ export function createOutboxSend(deps: {
   }
 }
 
+/**
+ * Build the heartbeat tick that {@link startOutboxSweep} hands to `setInterval`,
+ * with the SINGLE-FLIGHT guard (#3864).
+ *
+ * The tick fires every `OUTBOX_SWEEP_INTERVAL_MS` and the sweep it starts is
+ * `void`-ed, so a sweep that outlives its interval used to have the NEXT tick
+ * start a second, concurrent sweep body against the same outbox directory. The
+ * per-record rename mutex (`claimRecord`, `../outbox.ts`) keeps that from
+ * double-sending a single record, but it is the only thing that does: the two
+ * bodies still race the same journal / dedup / backoff state, and every
+ * additional overlapping tick multiplies the wire pressure at exactly the
+ * moment (a slow or flood-throttled Telegram) when the sweep must issue LESS.
+ * `inFlight` makes overlap unrepresentable rather than merely survivable.
+ *
+ * Extracted + exported so the guard is unit-testable without a live gateway,
+ * a timer, or the filesystem: pass a `runSweep` you control and drive `tick()`
+ * directly.
+ */
+export function createOutboxSweepTick(deps: {
+  /** Nothing to sweep until the bot exists (unchanged pre-guard behaviour). */
+  getBot: () => unknown
+  backoff: ReturnType<typeof createSweepBackoff>
+  /** Run ONE sweep body. Wired by {@link startOutboxSweep} to {@link sweepOutbox}. */
+  runSweep: () => Promise<OutboxSweepSummary>
+  log?: (line: string) => void
+  /** Test seam — clock used for the backoff gate and the defer-log throttle. */
+  now?: () => number
+}): (() => void) & { inFlight: () => boolean } {
+  const now = deps.now ?? (() => Date.now())
+  let lastDeferLogAt = 0
+  let inFlight = false
+  let overlapSkips = 0
+  const tick = () => {
+    if (deps.getBot() == null) return
+    if (!deps.backoff.ready(now())) return
+    // #3864 — a sweep is still running; skip this tick entirely rather than
+    // starting a second concurrent body. Skipping is free: the outbox is a
+    // durable safety net with no latency SLA, and the in-flight sweep will
+    // pick up anything this tick would have.
+    if (inFlight) {
+      overlapSkips++
+      if (overlapSkips === 1) {
+        deps.log?.(
+          `outbox-sweep: tick skipped — the previous sweep is still in flight ` +
+            `(single-flight guard; no concurrent sweep started)\n`,
+        )
+      }
+      return
+    }
+    inFlight = true
+    void deps
+      .runSweep()
+      .then((summary) => {
+        // A flood-deferred sweep is neither success nor failure: it never
+        // reached the wire, so it must not clear a backoff earned by real
+        // failures, and it must not deepen one either.
+        if (summary.floodDeferred === true) {
+          const at = now()
+          if (at - lastDeferLogAt >= OUTBOX_SWEEP_DEFER_LOG_INTERVAL_MS) {
+            lastDeferLogAt = at
+            deps.log?.(
+              `outbox-sweep: deferred — Telegram flood window still open for ` +
+                `${Math.ceil((summary.floodRemainingMs ?? 0) / 1000)}s; not issuing any ` +
+                `send (would feed the ban)\n`,
+            )
+          }
+          return
+        }
+        if (summary.sendFailures > 0) {
+          const delay = deps.backoff.noteFailure(now())
+          deps.log?.(
+            `outbox-sweep: ${summary.sendFailures} send failure(s) — backing off ` +
+              `${Math.round(delay / 1000)}s before the next sweep (attempt ${deps.backoff.failures()})\n`,
+          )
+        } else {
+          deps.backoff.noteSuccess()
+        }
+      })
+      .catch((err) => deps.log?.(`outbox-sweep: tick failed: ${(err as Error).message}\n`))
+      .finally(() => {
+        inFlight = false
+        if (overlapSkips > 0) {
+          deps.log?.(
+            `outbox-sweep: sweep finished; ${overlapSkips} tick(s) were skipped while it ran\n`,
+          )
+          overlapSkips = 0
+        }
+      })
+  }
+  return Object.assign(tick, { inFlight: () => inFlight })
+}
+
 export function startOutboxSweep(deps: {
   isGatewayMain: boolean
   stateDir: string
@@ -587,54 +913,26 @@ export function startOutboxSweep(deps: {
     ...(deps.resolveReplyMarkup != null ? { resolveReplyMarkup: deps.resolveReplyMarkup } : {}),
   })
   const backoff = deps.backoff ?? createSweepBackoff()
-  let lastDeferLogAt = 0
-  const tick = () => {
-    const bot = deps.getBot()
-    if (bot == null) return
-    const now = Date.now()
-    if (!backoff.ready(now)) return
-    void sweepOutbox({
-      stateDir: deps.stateDir,
-      log: deps.log,
-      send,
-      ...(deps.recordOutbound != null ? { recordOutbound: deps.recordOutbound } : {}),
-      floodWaitRemainingMs: floodProbe,
-      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)
-      },
-    })
-      .then((summary) => {
-        // A flood-deferred sweep is neither success nor failure: it never
-        // reached the wire, so it must not clear a backoff earned by real
-        // failures, and it must not deepen one either.
-        if (summary.floodDeferred === true) {
-          const at = Date.now()
-          if (at - lastDeferLogAt >= OUTBOX_SWEEP_DEFER_LOG_INTERVAL_MS) {
-            lastDeferLogAt = at
-            deps.log?.(
-              `outbox-sweep: deferred — Telegram flood window still open for ` +
-                `${Math.ceil((summary.floodRemainingMs ?? 0) / 1000)}s; not issuing any ` +
-                `send (would feed the ban)\n`,
-            )
-          }
-          return
-        }
-        if (summary.sendFailures > 0) {
-          const delay = backoff.noteFailure(Date.now())
-          deps.log?.(
-            `outbox-sweep: ${summary.sendFailures} send failure(s) — backing off ` +
-              `${Math.round(delay / 1000)}s before the next sweep (attempt ${backoff.failures()})\n`,
-          )
-        } else {
-          backoff.noteSuccess()
-        }
-      })
-      .catch((err) => deps.log?.(`outbox-sweep: tick failed: ${(err as Error).message}\n`))
-  }
+  const tick = createOutboxSweepTick({
+    getBot: deps.getBot,
+    backoff,
+    log: deps.log,
+    runSweep: () =>
+      sweepOutbox({
+        stateDir: deps.stateDir,
+        log: deps.log,
+        send,
+        ...(deps.recordOutbound != null ? { recordOutbound: deps.recordOutbound } : {}),
+        floodWaitRemainingMs: floodProbe,
+        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)
+        },
+      }),
+  })
   const timer = setInterval(tick, OUTBOX_SWEEP_INTERVAL_MS)
   timer.unref?.()
   return timer
@@ -674,6 +972,14 @@ export function journalExternalDelivery(
      * the flush send and its journal write), not just via the in-memory dedup.
      */
     deliverySource?: 'sweep' | 'reply-tool' | 'flush'
+    /**
+     * #4141: this delivery carried the reply-throw provenance banner. Durable
+     * terminal stamp mirroring the sweep's own `DeliveredEntry.framedProvenance`,
+     * so "was the recipient told where this text came from?" is answerable from
+     * the journal alone — on EITHER delivery path (sweep or captured-prose
+     * bridge), hours later.
+     */
+    framedProvenance?: 'reply-throw'
   },
   stateDir?: string,
   now: number = Date.now(),
@@ -683,6 +989,9 @@ export function journalExternalDelivery(
   appendDelivered(
     {
       turnNonce: nonce,
+      // Hashed on the RAW text, deliberately: the banner is presentation, and
+      // the journal key must stay stable across framed/unframed so
+      // exactly-once-among-backstops keeps working (#4141).
       textSha256: sha256Hex(args.text),
       tgMessageId: args.tgMessageId,
       ts: now,
@@ -690,6 +999,7 @@ export function journalExternalDelivery(
       ...(args.replyAlreadyDeliveredThisTurn == null
         ? {}
         : { replyAlreadyDeliveredThisTurn: args.replyAlreadyDeliveredThisTurn }),
+      ...(args.framedProvenance == null ? {} : { framedProvenance: args.framedProvenance }),
     },
     stateDir,
   )