switchroom 0.18.18 → 0.18.20

package/telegram-plugin/llm-error-present.ts

@@ -34,7 +34,6 @@ import {
 } from './model-unavailable.js'
 import { classify429Detail } from './throttle-tier.js'
 import { classifyClaudeError } from './operator-events.js'
-import type { InlineKeyboardMarkup } from './operator-events.js'
 import { stripRawErrorBytes, extractRequestId } from './raw-error-scrub.js'
 import { fmtLocalClock, tzAbbrev } from './shared/local-time.js'
 
@@ -226,7 +225,6 @@ function buildCoreText(kind: LlmErrorKind, source: LlmErrorSource): string {
 
 export interface RenderedLlmError {
   text: string
-  keyboard?: InlineKeyboardMarkup
 }
 
 /**
@@ -257,9 +255,49 @@ function formatRelativeTail(deltaMs: number): string {
 }
 
 /**
- * Render ONE clean card for a parsed LLM error. Action buttons for the
- * actionable kinds (auth → Reauth, quota_wall → Wait/switch). `agent` is used
- * in the callback_data (URL-encoded) and the headline; `tz` localizes the reset.
+ * A short local-tz clock+abbrev for a reset instant (`4:52pm AEST`), or '' when
+ * there is no finite reset to name. Used to embed the reset in the recommendation
+ * line. Shares the same tz-formatting primitives as {@link formatResetLocal}, so
+ * an invalid IANA tz throws here too (guarded by {@link renderLlmErrorSafe}).
+ */
+function formatResetClock(resetAt: Date | undefined, tz: string): string {
+  if (resetAt == null) return ''
+  const ms = resetAt.getTime()
+  if (!Number.isFinite(ms)) return ''
+  return `${fmtLocalClock(ms, tz)} ${tzAbbrev(ms, tz)}`
+}
+
+/**
+ * The plain-text "what to DO" line for the actionable error classes. Replaces
+ * the former dead action buttons (auth → Reauth, quota_wall → Wait): those
+ * inline_keyboard callbacks were only ever exercised in tests — the gateway
+ * wiring routes renderLlmError solely for the transient rate_limit/overload_529
+ * kinds, so the auth/quota buttons were unreachable in production (Ken, CPO,
+ * 2026-07: drop the buttons, recommend in text). Transient kinds return undefined
+ * — their coreText already says "retrying automatically", no operator action.
+ */
+function buildRecommendation(parsed: ParsedLlmError, tz: string): string | undefined {
+  switch (parsed.kind) {
+    case 'auth':
+      return '→ Re-authenticate this account to continue.'
+    case 'quota_wall': {
+      const reset = formatResetClock(parsed.resetAt, tz)
+      return reset
+        ? `→ Switch to another account, or wait for the quota to reset at ${reset}.`
+        : '→ Switch to another account, or wait for the quota to reset.'
+    }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Render ONE clean card for a parsed LLM error. No action buttons — the
+ * actionable kinds (auth, quota_wall) carry a plain-text recommendation line
+ * instead (see {@link buildRecommendation}). `agent` is the headline label; `tz`
+ * localizes the reset. Throws if `tz` is an invalid IANA zone AND a reset is
+ * present (Intl.DateTimeFormat rejects the zone at construction) — call
+ * {@link renderLlmErrorSafe} from any crash-sensitive surface.
  */
 export function renderLlmError(
   parsed: ParsedLlmError,
@@ -276,32 +314,32 @@ export function renderLlmError(
 
   if (parsed.model) lines.push(`_model: ${escapeAgent(parsed.model)}_`)
 
-  const text = lines.join('\n')
+  const recommendation = buildRecommendation(parsed, tz)
+  if (recommendation) lines.push(recommendation)
 
-  switch (parsed.kind) {
-    case 'auth':
-      return {
-        text,
-        keyboard: {
-          inline_keyboard: [
-            [
-              { text: '🔐 Reauth now', callback_data: `op:reauth:${encodeURIComponent(agent)}` },
-              { text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(agent)}` },
-            ],
-          ],
-        },
-      }
-    case 'quota_wall':
-      return {
-        text,
-        keyboard: {
-          inline_keyboard: [
-            [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(agent)}` }],
-          ],
-        },
-      }
-    default:
-      return { text }
+  return { text: lines.join('\n') }
+}
+
+/**
+ * Crash-guarded wrapper around {@link renderLlmError}. An invalid IANA timezone
+ * makes Intl.DateTimeFormat throw a RangeError at construction time — the
+ * local-time.ts "never throws" contract does NOT cover construction-time zone
+ * validation, so a bad `SWITCHROOM_TIMEZONE`/`TZ` would otherwise crash the
+ * operator-event turn. On ANY formatting failure, degrade to a minimal, tz-free
+ * safe line built only from the JSON-stripped coreText + agent. Total — never
+ * throws.
+ */
+export function renderLlmErrorSafe(
+  parsed: ParsedLlmError,
+  agent: string,
+  tz: string,
+  now: Date = new Date(),
+): RenderedLlmError {
+  try {
+    return renderLlmError(parsed, agent, tz, now)
+  } catch {
+    const safeAgent = escapeAgent(agent)
+    return { text: `${kindEmoji(parsed.kind)} ${parsed.coreText} (**${safeAgent}**)` }
   }
 }
 

package/telegram-plugin/narrative-flush.ts

@@ -0,0 +1,181 @@
+/**
+ * Time-boxed narrative early-paint — the TIMER half of the JSONL-text-narrative
+ * primitive, and the pure, fully-unit-testable kernel of it (companion to
+ * `narrative-dedup.ts`, which owns the SHOW-vs-SUPPRESS decision).
+ *
+ * ## Why this exists
+ * A `text` / `sub_agent_text` block is parked for ONE lookahead step so the
+ * reducer can tell DRAFT-THEN-SEND (suppress — it duplicates the reply) from
+ * WORKING NARRATION (show). On a normal turn the lookahead is the FIRST real
+ * `tool_use`, so the opening narration ("On it, pulling the logs…") only painted
+ * when that tool landed — a visible gap while the agent thinks before its first
+ * tool.
+ *
+ * This kernel adds a deterministic timer: when a block is parked, arm a short
+ * timer. If a lookahead event (tool_use / next text / turn_end) arrives first,
+ * the normal path resolves the block and the timer is CANCELLED. If the timer
+ * fires first, the parked narration is painted EARLY — so it surfaces
+ * ~`flushMs` into the turn instead of waiting for the first tool.
+ *
+ * ## Anti-double-print guarantee (the correctness core)
+ * The whole reason the decision is deferred is that a parked block might turn out
+ * to be the outgoing reply, which must NEVER surface as a card narration step AND
+ * as the canonical reply. The timer introduces a window where a block is painted
+ * BEFORE its lookahead reply arrives. This kernel keeps the guarantee
+ * deterministically, NOT by hoping the window hides the race:
+ *   - A block painted by the timer is remembered (`timerShown`).
+ *   - When the reply/stream_reply lookahead finally arrives (on a tool or at
+ *     turn_end), if it is a draft-then-send of the timer-painted block
+ *     (`isDraftOfReply`), the kernel emits a RETRACT effect so the caller removes
+ *     the prematurely-shown step. Correctness therefore does not depend on the
+ *     250ms window winning the race — the retract is the guarantee; the timer is
+ *     only the early-paint trigger.
+ *
+ * ## Purity
+ * No I/O, no real timers, no state of its own beyond the two explicit slots. All
+ * effects (paint a step, retract a step, arm/disarm a real timer) are injected,
+ * so the kernel is driven deterministically in tests with fake timers. The caller
+ * (gateway reducer for the main agent, subagent-watcher for sub/worker) owns the
+ * effects and the per-turn lifetime.
+ */
+
+import { REPLY_TOOLS, isDraftOfReply } from './narrative-dedup.js'
+
+/**
+ * Time-box for the parked-narrative early-paint (the kernel's home for the
+ * constant so BOTH callers share ONE source of truth):
+ *   - the main-agent gateway path drives the kernel with a real `setTimeout`
+ *     scheduler (`makeNarrativeGate`, gateway.ts);
+ *   - the worker / sub-agent watcher drives the SAME kernel with a POLL-driven
+ *     scheduler (stamp `deadline = nowFn()+flushMs`; flush on the next poll
+ *     tick once `nowFn() >= deadline`) — see `subagent-watcher.ts`.
+ * If a parked opening narration gets no lookahead event (tool_use / next text /
+ * turn_end) within this window — the "narrate, then think before the first
+ * tool" gap — it is painted EARLY instead of waiting for the first tool. Chosen
+ * so a normal draft-then-send `reply` (emitted right after the text block)
+ * resolves the block FIRST; correctness does NOT depend on that race — a
+ * timer-painted block that later proves to be the reply is deterministically
+ * retracted (main path) or is structurally harmless (worker path: the reply is
+ * a Telegram-surface tool that never renders on the card). Named const so a
+ * test can pin it.
+ */
+export const PENDING_NARRATIVE_FLUSH_MS = 250
+
+/** Side effects the kernel drives. The caller owns rendering + retraction. */
+export interface NarrativeFlushEffects {
+  /** Paint a narrative block as a transient liveness step (SHOW). */
+  show(text: string): void
+  /**
+   * Retract a previously-SHOWN narration step (it turned out to draft the reply).
+   * Caller removes it from the feed. No-op-safe if already gone.
+   */
+  retractShown(text: string): void
+}
+
+/** Arms / disarms the real early-paint timer. Injected so tests can fake it. */
+export interface NarrativeFlushScheduler {
+  /** Arm the timer; MUST cancel any prior armed callback first (at-most-one). */
+  arm(fn: () => void, ms: number): void
+  /** Cancel the armed callback if any. Idempotent. */
+  disarm(): void
+}
+
+/**
+ * Pure park/timer/retract state machine for one turn (or one sub-agent entry).
+ * Construct once per turn with the effect + scheduler wiring; discard at teardown.
+ */
+export class NarrativeFlushController {
+  /** Block parked awaiting its lookahead event. Null when nothing pending. */
+  private pending: string | null = null
+  /** Block the timer painted EARLY, retained for possible retract. */
+  private timerShown: string | null = null
+
+  constructor(
+    private readonly effects: NarrativeFlushEffects,
+    private readonly scheduler: NarrativeFlushScheduler,
+    private readonly flushMs: number,
+  ) {}
+
+  /** Test/inspection accessors (no behaviour). */
+  get pendingText(): string | null {
+    return this.pending
+  }
+  get timerShownText(): string | null {
+    return this.timerShown
+  }
+
+  /**
+   * Gate step 1: a new narrative block arrived. It is itself the lookahead for
+   * the previously-parked block (pure narration — a draft is followed by a reply,
+   * not more text) → SHOW the old one, then park the new one and arm the timer.
+   */
+  stage(text: string): void {
+    this.scheduler.disarm()
+    if (this.pending != null) {
+      this.effects.show(this.pending)
+    }
+    this.pending = text
+    this.scheduler.arm(() => this.onTimerFire(), this.flushMs)
+  }
+
+  /**
+   * The early-paint timer fired: no lookahead arrived within the window. If the
+   * block is still parked, SHOW it now and remember it so a later draft-then-send
+   * reply can retract it.
+   */
+  private onTimerFire(): void {
+    if (this.pending == null) return // a lookahead already consumed it
+    const text = this.pending
+    this.pending = null
+    this.timerShown = text
+    this.effects.show(text)
+  }
+
+  /**
+   * Gate step 2: a tool_use lookahead arrived. Cancel the timer, retract a
+   * timer-painted block if THIS reply drafts it, then resolve the parked block:
+   * SUPPRESS a reply-draft, else SHOW.
+   */
+  resolveOnTool(toolName: string, input: Record<string, unknown> | undefined): void {
+    this.scheduler.disarm()
+    const replyText =
+      REPLY_TOOLS.has(toolName) && typeof input?.text === 'string' ? (input.text as string) : null
+    if (replyText != null) this.maybeRetract(replyText)
+    const pending = this.pending
+    if (pending == null) return
+    this.pending = null
+    if (replyText != null && isDraftOfReply(pending, replyText)) return // draft → SUPPRESS
+    this.effects.show(pending)
+  }
+
+  /**
+   * Gate step 3: turn_end — the terminal lookahead. Cancel the timer, retract a
+   * timer-painted block if the delivered reply drafts it, then SHOW a genuine
+   * trailing narration (or SUPPRESS a trailing draft of the answer).
+   */
+  flushAtTurnEnd(lastReplyText: string): void {
+    this.scheduler.disarm()
+    if (lastReplyText.length > 0) this.maybeRetract(lastReplyText)
+    const pending = this.pending
+    if (pending == null) return
+    this.pending = null
+    if (lastReplyText.length > 0 && isDraftOfReply(pending, lastReplyText)) return // trailing draft
+    this.effects.show(pending)
+  }
+
+  /** Turn teardown: cancel the timer so it can neither leak nor fire late. */
+  teardown(): void {
+    this.scheduler.disarm()
+    this.pending = null
+    this.timerShown = null
+  }
+
+  /** Retract the timer-painted block iff this reply is its draft-then-send. */
+  private maybeRetract(replyText: string): void {
+    const shown = this.timerShown
+    if (shown == null) return
+    if (!isDraftOfReply(shown, replyText)) return
+    this.timerShown = null
+    this.effects.retractShown(shown)
+  }
+}

package/telegram-plugin/pending-work-progress.ts

@@ -64,6 +64,19 @@
 export const EDIT_INTERVAL_MS = 60_000
 export const POLL_INTERVAL_MS = 5_000
 export const MAX_LIFETIME_MS = 30 * 60_000
+/**
+ * TTL bounding how long an in-flight background dispatch (Agent/Task) suppresses
+ * the idle auto-/clear gate (#3117). Deliberately tied to `MAX_LIFETIME_MS` (the
+ * cross-turn ambient budget cap): the two express the same "how long do we
+ * believe a background worker is still legitimately running" budget, so keeping
+ * them equal means the idle-suppression window and the ambient-liveness window
+ * agree by construction. A SHORTER idle TTL would risk clobbering a legitimate
+ * ~25-min worker mid-flight; a LONGER one would weaken the self-healing bound
+ * (a leaked `pending=true` that never clears would disable idle-clear for
+ * longer). 30 min is the deliberate midpoint the design settled on. The gate
+ * suppresses only while `dispatch age < this`; past it the suppression lapses so
+ * a stuck flag can never disable idle-clear permanently. */
+export const BACKGROUND_WORK_SUPPRESS_TTL_MS = MAX_LIFETIME_MS
 /** Rich-message wire cap is 32768 (#2669); budget headroom for the
  *  suffix and any escape expansion. If the anchor text plus suffix
  *  would exceed this, we skip the edit (the user still sees the
@@ -142,6 +155,14 @@ interface State {
   /** True after a `tool_use(Agent|Task)` was observed for this key in
    *  the current turn. Cleared on next turn start. */
   pending: boolean
+  /** Epoch ms when `pending` was last set true (#3117). null when not
+   *  pending. Load-bearing for the idle-clear suppression TTL: without a
+   *  timestamp the gate cannot bound how long an in-flight background dispatch
+   *  holds off idle-clear, so a leaked `pending=true` would disable idle-clear
+   *  forever. Re-stamped on each `noteAsyncDispatch` (a fresh dispatch re-arms
+   *  the TTL) and cleared when `pending` is set false (`startTurn`); a full
+   *  `clearPending` drops the whole entry, which is equivalent. */
+  dispatchedAt: number | null
   /** The captured anchor — last outbound reply message_id for this
    *  key. */
   anchorMessageId: number | null
@@ -179,6 +200,7 @@ function ensure(key: string): State {
   if (!s) {
     s = {
       pending: false,
+      dispatchedAt: null,
       anchorMessageId: null,
       anchorOriginalText: '',
       anchorLiteralText: false,
@@ -217,6 +239,7 @@ export function startTurn(key: string): void {
   // Only the per-turn fields reset. activatedAt/lastEditAt belong to
   // the prior turn's pending-progress and are cleared separately.
   s.pending = false
+  s.dispatchedAt = null
   s.anchorMessageId = null
   s.anchorOriginalText = ''
   s.anchorLiteralText = false
@@ -229,7 +252,13 @@ export function startTurn(key: string): void {
  */
 export function noteAsyncDispatch(key: string): void {
   if (!enabled()) return
-  ensure(key).pending = true
+  const s = ensure(key)
+  s.pending = true
+  // Stamp (and re-stamp) the dispatch epoch so the idle-clear suppression TTL
+  // (#3117) can bound how long this holds off /clear. Re-stamping on each
+  // dispatch means a fresh Agent/Task within the same wait re-arms the TTL —
+  // freshest legitimate work wins.
+  s.dispatchedAt = nowMs()
 }
 
 /**
@@ -296,6 +325,41 @@ export function hasPendingAsyncDispatch(key: string): boolean {
   return stateByKey.get(key)?.pending === true
 }
 
+/**
+ * Age in ms since the current pending async dispatch was stamped for `key`
+ * (#3117), or null if there is no pending dispatch (or, defensively, no
+ * timestamp — a pre-stamp entry from a rolling upgrade). Uses the same clock
+ * override as the rest of the module so tests drive it deterministically.
+ */
+export function asyncDispatchAgeMs(key: string): number | null {
+  const s = stateByKey.get(key)
+  if (s == null || s.pending !== true || s.dispatchedAt == null) return null
+  return nowMs() - s.dispatchedAt
+}
+
+/**
+ * True iff ANY chat key currently has a pending async dispatch whose age is
+ * within `ttlMs` (#3117). The idle auto-/clear gate is agent-wide (not scoped
+ * to a single chat key), so it consults this aggregate: while a background
+ * sub-agent is in flight AND fresh, suppress the clear; once every pending
+ * dispatch has aged past the TTL (a leaked/stuck flag), the suppression lapses
+ * and idle-clear self-heals. A non-positive `ttlMs` disables suppression.
+ */
+export function anyPendingAsyncDispatchWithin(ttlMs: number): boolean {
+  if (ttlMs <= 0) return false
+  const now = nowMs()
+  for (const s of stateByKey.values()) {
+    if (
+      s.pending === true &&
+      s.dispatchedAt != null &&
+      now - s.dispatchedAt < ttlMs
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
 /**
  * Clear pending-progress for a chat — reasons:
  *   'inbound'   — user sent a new message, they're re-engaged

package/telegram-plugin/session-tail.ts

@@ -119,7 +119,12 @@ export type SessionEvent =
   // gate keys on it.
   | { kind: 'text'; text: string; blockIndex: number; lastInMessage: boolean }
   | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string }
-  | { kind: 'turn_end'; durationMs: number }
+  // `reason` is set ONLY by an internal gateway-synthesized turn_end (never by
+  // the JSONL projection). `answer-ready-quiescence` (PR A) marks the positive
+  // deterministic quiescence-flush signal, which — unlike the orphaned-reply
+  // backstop's bare `durationMs:-1` — deliberately bypasses the recently-
+  // streaming suppression guard (quiescence IS the "streaming settled" signal).
+  | { kind: 'turn_end'; durationMs: number; reason?: 'answer-ready-quiescence' }
   // Multi-agent: sub-agent-scoped events. agentId is the sub-agent JSONL
   // filename stem (e.g. "aac6f1…"). Routed through the same ingest path
   // as parent events; the reducer fans them out to per-sub-agent state.

package/telegram-plugin/silent-end.ts

@@ -38,10 +38,34 @@ export interface SilentEndState {
   threadId: number | null
   /** Stable identifier for the in-flight turn (statusKey shape). */
   turnKey: string
+  /**
+   * Per-turn nonce — `deriveTurnId`'s `${chatKey}#${messageId}` shape (#3228).
+   * Unlike `turnKey` (the STABLE `chatId:threadId` statusKey, identical across
+   * every turn on the same chat/thread), this is unique per inbound message.
+   * The Stop hook stamps it from the enqueue envelope's `message_id`; the
+   * gateway's `decideCapturedProseDelivery` requires it to match the LIVE
+   * turn's `turnId` before delivering `pendingText`, so a stale captured-prose
+   * record from a PRIOR turn on the same chat can never be misdelivered on a
+   * later turn (Finding 3). Optional — absent when no message_id was derivable
+   * (synthetic inbounds), in which case delivery falls back to the turnKey
+   * match alone.
+   */
+  turnId?: string
   /** Incremented each time the Stop hook blocks for this turn. */
   retryCount: number
   /** Wall-clock ms of last write. */
   timestamp: number
+  /**
+   * Option A transcript-prose bridge. The substantive final-answer prose the
+   * model wrote as plain transcript text but never sent through the reply
+   * tool, as isolated by the Stop hook's transcript scan
+   * (`scanTurnForFinalReply` → `pendingText`). Present only on a hook-written
+   * state file for a turn that ended silently WITH deliverable prose; the
+   * gateway's own `writeSilentEndState` never sets it. The gateway reads it
+   * back to deliver the answer directly on the first silent-end. Optional —
+   * absent for the zero-prose (genuinely empty) silent-end.
+   */
+  pendingText?: string
 }
 
 export interface SilentEndDeps {
@@ -256,6 +280,164 @@ export function clearSilentEndState(turnKey: string, deps?: SilentEndDeps): void
   }
 }
 
+/**
+ * Minimum length (chars, trimmed) of captured prose the gateway will deliver
+ * directly on a silent-end. Mirrors `FINAL_ANSWER_MIN_CHARS` in
+ * `hooks/silent-end-scan.mjs` and `isFinalAnswerReply`'s 200-char substantive
+ * backstop — the same bar used to recognise a real answer. A shorter trailing
+ * fragment is not a dropped answer and must not be re-materialised.
+ */
+export const CAPTURED_PROSE_MIN_CHARS = 200
+
+/**
+ * Result of the captured-prose delivery decision (Option A transcript-prose
+ * bridge). Pure, side-effect-free — the gateway consumes `deliver`/`text` and
+ * owns the actual send + dedup + obligation-close bookkeeping.
+ */
+export interface CapturedProseDecision {
+  /** True → the gateway should deliver `text` directly on this silent-end. */
+  deliver: boolean
+  /** The prose to deliver; present iff `deliver === true`. */
+  text?: string
+  /** Machine-readable reason (for logs / tests). */
+  reason:
+    | 'captured-prose'
+    | 'no-state'
+    | 'turnkey-mismatch'
+    | 'turnid-mismatch'
+    | 'no-substantive-prose'
+}
+
+/**
+ * Decide whether the current silent-end turn has a substantive undelivered
+ * final answer that the gateway should deliver directly (Option A).
+ *
+ * Reads the same `silent-end-pending.json` the Stop hook wrote. Delivers ONLY
+ * when (a) the record belongs to THIS turn — BOTH the stable `turnKey` AND, when
+ * present, the per-turn `turnId` nonce must match (#3228 Finding 3: `turnKey`
+ * alone is `chatId:threadId` and identical across turns on the same chat, so it
+ * cannot by itself prove the record is this turn's rather than a stale
+ * carryover) — and (b) the persisted `pendingText` clears the substance floor.
+ * Otherwise returns `deliver:false` and the caller falls through to the existing
+ * re-prompt / represent safety nets unchanged.
+ *
+ * turnId matching is enforced ONLY when BOTH sides carry one. A record written
+ * without a nonce (synthetic inbound with no message_id) or a caller that has
+ * no live turnId falls back to the turnKey match alone — never suppress
+ * delivery on doubt, and never break the pre-nonce path.
+ *
+ * Extracted as a pure core (mirrors `decideTurnFlush` / `decideTurnEndGate`)
+ * so the gateway runs the exact code the regression tests exercise —
+ * `gateway.ts` is not importable in tests.
+ */
+export function decideCapturedProseDelivery(
+  args: { turnKey: string; turnId?: string | null; minChars?: number },
+  deps?: SilentEndDeps,
+): CapturedProseDecision {
+  const minChars = args.minChars ?? CAPTURED_PROSE_MIN_CHARS
+  const state = readSilentEndState(deps)
+  if (state == null) return { deliver: false, reason: 'no-state' }
+  if (state.turnKey !== args.turnKey) return { deliver: false, reason: 'turnkey-mismatch' }
+  // Per-turn nonce guard (#3228 Finding 3). When the on-disk record was stamped
+  // with a `turnId` AND the caller passes the live turn's `turnId`, they MUST
+  // match — otherwise the record belongs to a different turn on the same chat.
+  if (
+    typeof state.turnId === 'string' &&
+    state.turnId !== '' &&
+    args.turnId != null &&
+    args.turnId !== '' &&
+    state.turnId !== args.turnId
+  ) {
+    return { deliver: false, reason: 'turnid-mismatch' }
+  }
+  const text = typeof state.pendingText === 'string' ? state.pendingText : ''
+  if (text.trim().length < minChars) return { deliver: false, reason: 'no-substantive-prose' }
+  return { deliver: true, text, reason: 'captured-prose' }
+}
+
+/**
+ * Outcome of a captured-prose send attempt (Option A transcript-prose bridge).
+ *   - `sent`         — the answer was delivered fresh this call.
+ *   - `skipped-dedup`— the exact answer already went out (dedup hit); nothing
+ *                      new was sent, but the answer IS with the user.
+ *   - `failed`       — the send threw; the answer did NOT reach the user.
+ */
+export type CapturedProseSendOutcome = 'sent' | 'skipped-dedup' | 'failed'
+
+/**
+ * The bookkeeping effects the gateway applies after a captured-prose send
+ * attempt, injected so the settlement decision is a pure, testable core
+ * (`gateway.ts` itself is not importable in tests).
+ */
+export interface CapturedProseSettlementEffects {
+  /** Close the ending turn's delivery obligation. */
+  closeObligation: () => void
+  /** Clear the silent-end state file for this turn. */
+  clearState: () => void
+  /**
+   * Arm the deterministic Stop-hook re-prompt (recordUndeliveredTurnEnd) so
+   * the answer is recoverable — the send-failure safety net. Returns the
+   * `{ exhausted }` verdict from `recordUndeliveredTurnEnd`: `true` when the
+   * re-prompt budget was ALREADY spent (retryCount >= SILENT_END_MAX_RETRIES)
+   * on the attempt that failed, so the re-prompt can no longer recover the
+   * answer and the caller must deliver a user-facing fallback instead (#3228
+   * exhaustion-boundary gap).
+   */
+  recordUndelivered: () => { exhausted: boolean }
+}
+
+/**
+ * Result of `settleCapturedProseDelivery`. `exhausted` is meaningful only on
+ * the `failed` outcome — `true` means the Stop-hook re-prompt net is spent, so
+ * the caller must fire the user-facing fallback (a plain-text retry of the
+ * captured prose, then the generic apology) so the turn never goes silent.
+ * Always `false` for `sent` / `skipped-dedup` (the answer is already with the
+ * user; no fallback).
+ */
+export interface CapturedProseSettlementResult {
+  exhausted: boolean
+}
+
+/**
+ * Apply the correct bookkeeping after a captured-prose send attempt (#3228
+ * Finding 1). This is the deterministic core the gateway's
+ * `deliverCapturedProse` routes ALL three of its settlement points through.
+ *
+ *   - `sent` / `skipped-dedup` → the answer is with the user, so CLOSE the
+ *     obligation and CLEAR the silent-end state; the represent and the
+ *     exhausted fallback must not re-fire for the same answer.
+ *
+ *   - `failed` → the send threw, so the answer is NOT with the user. We must
+ *     NOT close the obligation or clear the state; instead we ARM the Stop-hook
+ *     re-prompt net (`recordUndelivered`). This is the regression fix: the
+ *     shared turn-end teardown (`decideObligationTurnEnd`) already CLOSES the
+ *     obligation whenever `replyCalled === true` (the interim-ack case that
+ *     reaches captured-prose delivery), so "just leave the obligation open" is
+ *     NOT a real net — without recordUndelivered a thrown send permanently
+ *     loses the answer, strictly worse than the pre-bridge behaviour.
+ *
+ *     The `{ exhausted }` verdict from `recordUndelivered` is threaded back out
+ *     to the caller (#3228 exhaustion-boundary gap): when the failed send
+ *     happened on the attempt where the re-prompt budget was ALREADY spent,
+ *     `recordUndeliveredTurnEnd` clears the state and reports `exhausted:true` —
+ *     the Stop-hook re-prompt can no longer recover the answer, so the caller
+ *     MUST deliver a user-facing fallback (mirroring the non-captured
+ *     exhausted path) or the user gets NEITHER the answer NOR the apology.
+ *
+ * Pure — no IO, no module state; the caller injects the effects.
+ */
+export function settleCapturedProseDelivery(
+  outcome: CapturedProseSendOutcome,
+  effects: CapturedProseSettlementEffects,
+): CapturedProseSettlementResult {
+  if (outcome === 'failed') {
+    return { exhausted: effects.recordUndelivered().exhausted }
+  }
+  effects.closeObligation()
+  effects.clearState()
+  return { exhausted: false }
+}
+
 /**
  * Read the state file (for tests + diagnostics). Returns null when
  * absent or unparsable.