switchroom 0.18.19 → 0.18.21

package/telegram-plugin/gateway/idle-clear.ts

@@ -67,6 +67,20 @@ export interface IdleClearState {
   alreadyCleared: boolean;
   /** A turn is in flight — never clear mid-turn. */
   turnInFlight: boolean;
+  /**
+   * A background sub-agent (Agent/Task dispatched, turn ended before it
+   * returned) is still in flight AND within its suppression TTL (#3117). The
+   * main-turn gate (`turnInFlight`) is blind to detached background work: a
+   * worker that is alive-but-silent for a full idle window (one long tool call,
+   * no stream events to re-stamp the activity clock) would otherwise be cleared,
+   * destroying the context its handback needs. Suppress the clear while this is
+   * true. It is TTL-bounded by the caller so a leaked/never-cleared pending flag
+   * cannot disable idle-clear forever — past the TTL the caller passes false and
+   * self-healing resumes. Optional/undefined ⇒ treated as false (no background
+   * work), which preserves the pre-#3117 behaviour for callers that don't wire
+   * it (e.g. the pure-decider unit tests that exercise only the wall clock).
+   */
+  backgroundWorkInFlight?: boolean;
 }
 
 export interface IdleClearDecision {
@@ -91,6 +105,14 @@ export function decideIdleClear(
 ): IdleClearDecision {
   if (state.idleClearMs <= 0) return { clear: false }; // disabled
   if (state.turnInFlight) return { clear: false }; // never mid-turn
+  // #3117 — a detached background sub-agent within its suppression TTL keeps the
+  // session alive even when the main-turn gate is open and the activity clock
+  // has gone cold (a silent long-running worker emits no stream events). The
+  // caller (gateway) bounds this by a TTL so a stuck pending flag can't disable
+  // idle-clear forever; here we simply honour it. Because #3116's write-time
+  // re-eval re-runs this whole function against the live state, this suppression
+  // is enforced at BOTH decision time and /clear write time for free.
+  if (state.backgroundWorkInFlight) return { clear: false };
   if (state.alreadyCleared) return { clear: false }; // once per idle period
   // Measured from the LAST thing that happened — activity or a turn ending —
   // never from a turn's start. A turn that ran longer than the window ends with
@@ -133,6 +155,154 @@ export function classifyIdleEvent(
   return { activity: !synthetic, turnEnded };
 }
 
+/**
+ * Inputs the gateway feeds into a decision that live OUTSIDE the idle clocks:
+ * the resolved window, the main-turn gate, and the TTL-bounded background-work
+ * suppressor. Kept separate from `IdleClearState` (the clock state the tracker
+ * owns) so the tracker's decide surface is exactly "here is the world right
+ * now" and the tracker supplies its own clocks + latch.
+ */
+export interface IdleDecisionInputs {
+  /** Resolved idle window in ms (env → per-agent config → 3h default). <=0 disables. */
+  idleClearMs: number;
+  /** A turn is in flight (the same gate proactive-compact uses). Never clear mid-turn. */
+  turnInFlight: boolean;
+  /**
+   * A detached background sub-agent is in flight AND within its suppression TTL
+   * (#3117). Optional; undefined ⇒ false (pre-#3117 behaviour). The caller bounds
+   * this by a TTL so a leaked pending flag can't disable idle-clear forever.
+   */
+  backgroundWorkInFlight?: boolean;
+}
+
+/**
+ * The gateway's idle bookkeeping as ONE stateful object (#3115).
+ *
+ * Before #3115 this lived as four bare module-level `let`s in gateway.ts
+ * (`lastIdleActivityAt`, `lastIdleTurnEndAt`, `idleAutoCleared`,
+ * `idleClearDispatching`) plus the inline `markIdleActivity` / `markIdleTurnEnd`
+ * / `maybeIdleClear` stamp+decide logic scattered across `handleSessionEvent`,
+ * `onInjectInbound`, and `handleInbound`. Nothing imported gateway.ts (~30k
+ * lines, import-time side effects), so the WIRING — that every session event
+ * actually stamps the clocks — was untestable and the test mirrored the logic
+ * in a local `IdleModel` instead of exercising it. Deleting the real stamp
+ * block left every test green while re-introducing the #3113 "productive work
+ * gets wiped" bug.
+ *
+ * Extracting the state here makes the real object importable and drivable: a
+ * deleted stamp call now fails a test because the test holds the SAME object
+ * the gateway holds. The gateway keeps ownership of its environment concerns
+ * (resolving the window, `turnInFlightForGate()`, the pending-dispatch probe)
+ * and feeds them in via `IdleDecisionInputs`; the tracker owns only the clocks
+ * and the fire-once / re-entrancy latches.
+ *
+ * The clock is injected per-call (`now`) exactly like the pure `decideIdleClear`
+ * / `classifyIdleEvent` it delegates to — the gateway passes `Date.now()`, the
+ * tests pass a deterministic virtual clock.
+ */
+export class IdleTracker {
+  /** Epoch ms of the last activity (inbound, cron fire, or any genuine session event). */
+  private lastActivityAt: number;
+  /** Epoch ms a turn last ended (null = none this process). */
+  private lastTurnEndedAt: number | null = null;
+  /** Already auto-cleared since the last activity? Fire-once-per-idle-period latch. */
+  private alreadyCleared = false;
+  /** A /clear dispatch is in flight — re-entrancy guard so a tick can't double-fire. */
+  private dispatching = false;
+
+  constructor(startedAt: number) {
+    this.lastActivityAt = startedAt;
+  }
+
+  /** Epoch ms of the last activity — for wiring assertions (was `lastIdleActivityAt`). */
+  get activityAt(): number {
+    return this.lastActivityAt;
+  }
+  /** Epoch ms a turn last ended, or null — for wiring assertions. */
+  get turnEndedAt(): number | null {
+    return this.lastTurnEndedAt;
+  }
+  /** The fire-once latch — true once cleared this idle period, until re-armed. */
+  get cleared(): boolean {
+    return this.alreadyCleared;
+  }
+  /** A /clear dispatch is currently in flight. */
+  get isDispatching(): boolean {
+    return this.dispatching;
+  }
+
+  /**
+   * Reset the idle timer + re-arm auto-clear. Call on ANY activity — inbound,
+   * a genuine cron fire, or (via `noteEvent`) any claude session-stream event.
+   * Was the gateway's `markIdleActivity()`.
+   */
+  noteInbound(now: number): void {
+    this.lastActivityAt = now;
+    this.alreadyCleared = false;
+  }
+
+  /**
+   * Feed a claude session-stream event through the classifier and stamp the
+   * clocks. Genuine activity re-arms the auto-clear; a turn ending additionally
+   * stamps the turn-end clock. Was the gateway's inline
+   * `classifyIdleEvent` + `markIdleActivity`/`markIdleTurnEnd` block in
+   * `handleSessionEvent` — the load-bearing wiring #3115 makes testable.
+   */
+  noteEvent(kind: string, now: number, durationMs?: number): void {
+    const signal = classifyIdleEvent(kind, durationMs);
+    if (signal.activity) this.noteInbound(now);
+    if (signal.turnEnded) this.lastTurnEndedAt = now;
+  }
+
+  /** Snapshot the tracker's clocks into an `IdleClearState` for a decision. */
+  private stateFor(inputs: IdleDecisionInputs, alreadyCleared: boolean): IdleClearState {
+    return {
+      lastActivityAt: this.lastActivityAt,
+      lastTurnEndedAt: this.lastTurnEndedAt,
+      idleClearMs: inputs.idleClearMs,
+      alreadyCleared,
+      turnInFlight: inputs.turnInFlight,
+      backgroundWorkInFlight: inputs.backgroundWorkInFlight,
+    };
+  }
+
+  /**
+   * Decide whether to auto-clear right now, honouring the fire-once latch.
+   * Delegates to the pure `decideIdleClear` against the live clocks + inputs.
+   */
+  decide(now: number, inputs: IdleDecisionInputs): IdleClearDecision {
+    return decideIdleClear(this.stateFor(inputs, this.alreadyCleared), now);
+  }
+
+  /**
+   * Re-evaluate idleness at /clear WRITE time (#3116 precondition), IGNORING the
+   * fire-once latch. `maybeIdleClear` latches `alreadyCleared=true` before the
+   * async inject for re-entrancy, so the write-time re-eval must judge idleness
+   * on the live clocks + turn/background gates only — any activity that arrived
+   * in the check-to-send gap must still suppress the buffered /clear.
+   */
+  decideIgnoringLatch(now: number, inputs: IdleDecisionInputs): IdleClearDecision {
+    return decideIdleClear(this.stateFor(inputs, false), now);
+  }
+
+  /** Latch the fire-once guard: a /clear has been decided for this idle period. */
+  markClearFired(): void {
+    this.alreadyCleared = true;
+  }
+  /** Re-arm after a suppressed dispatch so the next idle period can clear again. */
+  reArm(): void {
+    this.alreadyCleared = false;
+  }
+  /** Mark a /clear dispatch as begun (re-entrancy latch). */
+  beginDispatch(): void {
+    this.dispatching = true;
+  }
+  /** Mark a /clear dispatch as finished (re-entrancy latch released). */
+  endDispatch(): void {
+    this.dispatching = false;
+  }
+}
+
 /**
  * Parse a `^\d+[smh]$` duration (the SessionSchema format, e.g. "3h", "30m",
  * "7200s") to ms. Returns null on a malformed string so the caller can fall

package/telegram-plugin/gateway/inject-handler.ts

@@ -86,6 +86,17 @@ function shapeReply(
     return { body: verbHtml, accent: 'done' }
   }
 
+  // outcome === 'skipped' (#3116): an opt-in write-time precondition aborted
+  // the send before any keys were sent. No inject-map caller opts in today, so
+  // this is unreachable via this surface — but handle it explicitly so a future
+  // precondition caller gets an honest "skipped" ack instead of a failure card.
+  if (result.outcome === 'skipped') {
+    return {
+      body: `${verbHtml} — skipped (precondition not met at send time)`,
+      accent: 'issue',
+    }
+  }
+
   // outcome === 'failed'
   const code = result.errorCode ?? 'tmux_failed'
   const msg = result.errorMessage ?? 'unknown error'

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

@@ -27,6 +27,7 @@ import {
   normalizeParagraphBreaks,
   normalizePunctuation,
   stripExcessBold,
+  addParagraphSpacers,
   splitMarkdownChunks,
   hardSliceToCap,
   RICH_MESSAGE_MAX_CHARS,
@@ -87,16 +88,15 @@ export function normalizeOutboundBody(
 }
 
 /**
- * Effective-text stage. Historically this injected an NBSP paragraph spacer on
- * the rich path (#2669) to force a visible gap; that pass was removed in the
- * #2669 follow-up because the live Bot API 10.1 GFM renderer already renders a
- * `\n\n` gap as one normal blank line — the spacer was double-gapping every
- * paragraph. Both paths now pass the text through byte-identically; the stage
- * is retained as the named pipeline seam (and the literal/rich distinction is
- * kept for callers) so a future rich-only transform has a home. Pure.
+ * Effective-text spacing (#2669 rich-message regression fix, restored after the
+ * #3208 F1 misfire). The Bot API 10.1 rich GFM renderer (and the in-repo IR
+ * renderer that feeds it) renders a prose `\n\n` gap TIGHT, so paragraphs render
+ * jammed together. Inject a visible U+00A0 blank-line spacer into each block
+ * gap on the rich path only (idempotent — see addParagraphSpacers); the literal
+ * (`format:'text'`) path stays byte-exact. Pure.
  */
-export function computeEffectiveText(text: string, _literalText: boolean): string {
-  return text
+export function computeEffectiveText(text: string, literalText: boolean): string {
+  return literalText ? text : addParagraphSpacers(text)
 }
 
 /**

package/telegram-plugin/gateway/subagent-progress-inbound-builder.ts

@@ -176,12 +176,20 @@ export interface SubagentProgressDecisionInput {
    *  passes it in; the decision returns the new bucket idx on
    *  `deliver: true` so the caller can update its tracker. */
   lastBucketIdx: number | null
+  /** #3233: true for a growth-independent SKELETON liveness cue (empty
+   *  `latestSummary`, no step content). It exists ONLY to first-paint /
+   *  keep-alive the in-message worker-feed row; the legacy bucket relay would
+   *  turn it into a synthesized "still working" inbound with no content — a
+   *  blank card. Suppressed deterministically here so the worker-feed-DISABLED
+   *  path degrades to a no-op rather than a blank envelope. */
+  skeleton?: boolean
   /** Deterministic clock for tests. */
   nowMs?: number
 }
 
 export type SubagentProgressSkipReason =
   | 'env-disabled'
+  | 'skeleton-liveness'
   | 'foreground'
   | 'no-chat'
   | 'bucket-already-fired'
@@ -199,6 +207,8 @@ export type SubagentProgressDecision =
  *
  * Gates, in order:
  *   1. kill-switch — `SWITCHROOM_DISABLE_SUBAGENT_PROGRESS=1` disables.
+ *   1b. skeleton-liveness (#3233) — a contentless skeleton cue is never
+ *       relayed as a synthesized inbound (worker-feed row only).
  *   2. foreground — foreground sub-agents stream natively.
  *   3. no-chat    — nowhere to deliver.
  *   4. missing-jsonl-id — the dedup key. Without it we'd lose
@@ -233,6 +243,13 @@ export function decideSubagentProgress(
   if (isEnvFlagOn(input.disableEnvValue)) {
     return { deliver: false, reason: 'env-disabled' }
   }
+  // #3233: a skeleton liveness cue carries no step content — never relay it as
+  // a synthesized progress inbound (that would be a blank card). Its whole job
+  // is the in-message worker-feed row; when that surface is off, degrade to a
+  // no-op. Checked before bucketing so it can never advance the bucket tracker.
+  if (input.skeleton === true) {
+    return { deliver: false, reason: 'skeleton-liveness' }
+  }
   if (!input.isBackground) {
     return { deliver: false, reason: 'foreground' }
   }

package/telegram-plugin/gateway/turn-record-status.ts

@@ -0,0 +1,134 @@
+/**
+ * Honest turn-record status derivation (PR B — "send-honesty" fix).
+ *
+ * `emitTurnRecord` historically wrote `status: finalAnswerDelivered ? 'complete'
+ * : 'no_reply'`. On the turn-flush / backstop paths `finalAnswerDelivered` is set
+ * BEFORE the async send actually runs, so a send that then throws (e.g.
+ * `FLOOD_WAIT_ACTIVE` during a flood ban) was still recorded `complete` — a turn
+ * where the user received NOTHING logged as delivered.
+ *
+ * The fix threads a per-turn `deliveryOutcome`, set only AFTER the send resolves,
+ * and derives the recorded status from that real outcome. These helpers are pure
+ * and injectable so the outcome ↔ status mapping is unit-testable without the
+ * 30k-line gateway module (mirrors `turns-jsonl-rotate.ts`).
+ */
+
+/**
+ * The resolved fate of a backstop (turn-flush) send, stamped on the turn only
+ * once the send has actually resolved:
+ * - `delivered`  — every chunk reached Telegram.
+ * - `failed`     — the send threw, OR a partial multi-chunk delivery (chunk 1 ok,
+ *                  a later chunk failed): the answer did not fully reach the user.
+ * - `suppressed` — the flush short-circuited because the reply tool already
+ *                  delivered this turn's answer (the 2s recent-outbound guard).
+ */
+export type DeliveryOutcome = 'delivered' | 'failed' | 'suppressed'
+
+/** The status strings written to turns.jsonl. `send_failed` is new in PR B. */
+export type TurnStatus = 'complete' | 'no_reply' | 'send_failed'
+
+/**
+ * Derive the recorded turn status from the turn's flags.
+ *
+ * `deliveryOutcome` (when present) is authoritative — it reflects the REAL send
+ * resolution on the backstop paths. When it is absent (the synchronous
+ * reply-tool tail, silent-marker, and genuine no-reply paths) we fall back to the
+ * legacy `finalAnswerDelivered` reading, preserving existing semantics exactly.
+ *
+ *   delivered            → complete
+ *   failed / partial     → send_failed   (NOT complete, NOT silently no_reply)
+ *   suppressed           → complete iff the reply path delivered, else no_reply
+ *   undefined (legacy)   → complete iff finalAnswerDelivered, else no_reply
+ *                          (fail-safe: an IIFE that dies before stamping an
+ *                          outcome never fabricates `complete`)
+ */
+export function computeTurnStatus(turn: {
+  finalAnswerDelivered: boolean
+  deliveryOutcome?: DeliveryOutcome
+}): TurnStatus {
+  switch (turn.deliveryOutcome) {
+    case 'failed':
+      return 'send_failed'
+    case 'delivered':
+      return 'complete'
+    case 'suppressed':
+      return turn.finalAnswerDelivered ? 'complete' : 'no_reply'
+    default:
+      return turn.finalAnswerDelivered ? 'complete' : 'no_reply'
+  }
+}
+
+/**
+ * Resolve a backstop send's outcome from what actually happened on the wire.
+ * A throw is a failure; a no-throw send that delivered fewer chunks than it
+ * split into is a partial delivery and is treated as `failed` (the user did not
+ * receive the whole answer) — never silently `delivered`/`complete`.
+ */
+export function backstopSendOutcome(args: {
+  threw: boolean
+  sentCount: number
+  chunkCount: number
+}): DeliveryOutcome {
+  if (args.threw) return 'failed'
+  // Defense (Fix 5): a "send" that split into zero chunks delivered nothing —
+  // do NOT let sentCount(0) < chunkCount(0) === false slip through to
+  // 'delivered'/'complete' (which would trip the silent-no-op-candidate
+  // detector on a tools:0 turn). Nothing sent → failed.
+  if (args.chunkCount === 0) return 'failed'
+  if (args.sentCount < args.chunkCount) return 'failed'
+  return 'delivered'
+}
+
+/**
+ * Stamp a turn's `deliveryOutcome` from a resolved backstop send. This is the
+ * exact accounting the turn-flush IIFE's `finally` performs — factored here so
+ * the gateway and the tests run the SAME mapping (a real send that throws or
+ * partially delivers must produce `send_failed`, never `complete`). Mutates and
+ * returns the resolved outcome.
+ */
+export function finalizeBackstopSend(
+  turn: { deliveryOutcome?: DeliveryOutcome },
+  send: { threw: boolean; sentCount: number; chunkCount: number },
+): DeliveryOutcome {
+  const outcome = backstopSendOutcome(send)
+  turn.deliveryOutcome = outcome
+  return outcome
+}
+
+/** The parsed shape of one turns.jsonl row. */
+export interface TurnRecordRow {
+  ts: number
+  agent: string
+  duration_ms: number
+  tools: number
+  status: TurnStatus
+  turn_id: string
+}
+
+/**
+ * Build the turns.jsonl row for a turn. The single source of truth for the
+ * `status` field — `emitTurnRecord` serializes exactly this, so a test that
+ * asserts on `buildTurnRecord(...).status` is asserting the value the gateway
+ * actually writes (proving `emitTurnRecord` derives status from the resolved
+ * `deliveryOutcome` via `computeTurnStatus`, not the speculative flag).
+ */
+export function buildTurnRecord(
+  turn: {
+    agent: string
+    startedAt: number
+    toolCallCount: number
+    turnId: string
+    finalAnswerDelivered: boolean
+    deliveryOutcome?: DeliveryOutcome
+  },
+  endedAt: number,
+): TurnRecordRow {
+  return {
+    ts: Math.floor(endedAt / 1000),
+    agent: turn.agent,
+    duration_ms: turn.startedAt > 0 ? endedAt - turn.startedAt : 0,
+    tools: turn.toolCallCount ?? 0,
+    status: computeTurnStatus(turn),
+    turn_id: turn.turnId,
+  }
+}

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -172,6 +172,29 @@ function main() {
     if (decision.threadId != null) {
       nextState.threadId = decision.threadId
     }
+    // Per-turn nonce (Finding 3, #3228). The gateway requires this to match
+    // the live turn's `turnId` before delivering `pendingText`, so a stale
+    // record left over from a prior turn on the same chat/thread can never
+    // deliver a previous turn's answer on a later one. Explicitly drop a
+    // carried-over `turnId` from the spread `...state` when THIS turn has no
+    // derivable nonce, so an old value never lingers.
+    if (decision.turnId) nextState.turnId = decision.turnId
+    else delete nextState.turnId
+  } else {
+    delete nextState.turnId
+  }
+  // Option A transcript-prose bridge: when the scan isolated a substantive
+  // final answer the model wrote as plain text but never sent through the
+  // reply tool, persist it so the gateway's turn-end path can deliver it
+  // directly on the first silent-end (instead of relying on this hook's
+  // re-prompt / the obligation represent to eventually recover it). The
+  // gateway reads this field back out of the same state file. Explicitly
+  // clear a stale carryover value from a prior turn's spread `...state` when
+  // THIS turn has no deliverable prose, so an old answer is never re-sent.
+  if (typeof decision.pendingText === 'string' && decision.pendingText.length > 0) {
+    nextState.pendingText = decision.pendingText
+  } else {
+    delete nextState.pendingText
   }
   try {
     writeFileSync(statePath, JSON.stringify(nextState), 'utf8')

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -123,14 +123,25 @@ export function isFinalAnswerReply({ text, disableNotification, done }) {
  * @returns {{ chatId: string | null, threadId: number | null }}
  */
 function parseChannelEnvelope(content) {
-  if (typeof content !== 'string') return { chatId: null, threadId: null, source: null }
+  if (typeof content !== 'string') {
+    return { chatId: null, threadId: null, messageId: null, source: null }
+  }
   const chatMatch = content.match(/chat_id="([^"]+)"/)
   const threadMatch = content.match(/message_thread_id="([^"]+)"/)
+  // LEFT-ANCHOR the message_id match on an attribute boundary (start-of-string
+  // or a whitespace/quote before the name) so it matches ONLY the real
+  // `message_id` attribute — never a same-suffix sibling like
+  // `target_message_id`, `reply_to_message_id`, or `original_message_id`.
+  // Byte-identical to session-tail.ts `parseChannelMeta`'s `grab('message_id')`
+  // so the turnId the hook derives here matches the gateway's `deriveTurnId`
+  // exactly (Finding 3, #3228).
+  const msgMatch = content.match(/(?:^|[\s"'])message_id="([^"]+)"/)
   const sourceMatch = content.match(/<channel[^>]*\bsource="([^"]+)"/)
   const threadRaw = threadMatch ? Number(threadMatch[1]) : NaN
   return {
     chatId: chatMatch ? chatMatch[1] : null,
     threadId: Number.isFinite(threadRaw) && threadRaw !== 0 ? threadRaw : null,
+    messageId: msgMatch ? msgMatch[1] : null,
     source: sourceMatch ? sourceMatch[1] : null,
   }
 }
@@ -148,6 +159,27 @@ function buildTurnKey(chatId, threadId) {
   return `${chatId}:${threadId == null || threadId === 0 ? '_' : threadId}`
 }
 
+/**
+ * Build the per-turn nonce the gateway stamps as `CurrentTurn.turnId`
+ * (`gateway.ts deriveTurnId` → `${chatKey(chatId, threadId)}#${messageId}`).
+ * Unlike `buildTurnKey` (the STABLE `chatId:threadId` statusKey, shared by
+ * every turn on the same chat/thread), this is unique per inbound message —
+ * so a stale captured-prose record from a PRIOR turn on the same chat can
+ * never be misdelivered on a LATER turn (Finding 3, #3228). Returns null when
+ * the enqueue envelope carries no usable message_id (synthetic inbounds); the
+ * gateway then falls back to the turnKey-only match, unchanged.
+ *
+ * @param {string | null} chatId
+ * @param {number | null} threadId
+ * @param {string | null} messageId
+ * @returns {string | null}
+ */
+function buildTurnId(chatId, threadId, messageId) {
+  if (chatId == null) return null
+  if (messageId == null || messageId === '' || String(messageId) === '0') return null
+  return `${buildTurnKey(chatId, threadId)}#${messageId}`
+}
+
 /**
  * Build the `{ decided: 'block', ... }` result shape, populating
  * `turnKey`/`chatId`/`threadId` from the enqueue envelope when
@@ -155,13 +187,27 @@ function buildTurnKey(chatId, threadId) {
  *
  * @param {ReturnType<typeof parseChannelEnvelope>} envelope
  * @param {string} reason
+ * @param {string} [pendingText] The substantive undelivered final-answer
+ *   prose the model wrote as plain transcript text but never sent through a
+ *   reply tool (Option A transcript-prose bridge). Only populated when it
+ *   clears the substance floor, so the gateway never re-delivers a short
+ *   trailing pleasantry. Omitted entirely otherwise.
  */
-function buildBlockResult(envelope, reason) {
+function buildBlockResult(envelope, reason, pendingText) {
   const block = { decided: 'block', reason }
   if (envelope.chatId) {
     block.chatId = envelope.chatId
     block.threadId = envelope.threadId
     block.turnKey = buildTurnKey(envelope.chatId, envelope.threadId)
+    // Per-turn nonce (Finding 3, #3228). Populated only when the enqueue
+    // envelope carried a real message_id — the gateway requires it to match
+    // this turn's `turnId` before delivering `pendingText`, so a stale record
+    // carried over from a prior turn on the same chat/thread is rejected.
+    const turnId = buildTurnId(envelope.chatId, envelope.threadId, envelope.messageId)
+    if (turnId != null) block.turnId = turnId
+  }
+  if (typeof pendingText === 'string' && pendingText.length > 0) {
+    block.pendingText = pendingText
   }
   return block
 }
@@ -191,6 +237,15 @@ function buildBlockResult(envelope, reason) {
  *                                     the hook's state.
  *   { decided: 'unknown', reason }  — couldn't locate turn-start; caller fail-open
  *
+ * On a 'block' decision the result MAY carry `pendingText`: the substantive
+ * final-answer prose the model wrote as plain transcript text after the last
+ * delivery event (or the whole turn's prose when nothing was ever delivered),
+ * joined and trimmed. This is the Option A transcript-prose bridge — the
+ * gateway reads it back out of the state file and delivers it directly on the
+ * first silent-end instead of waiting for the model re-prompt / obligation
+ * represent to eventually recover it. Only surfaced when it clears the same
+ * FINAL_ANSWER_MIN_CHARS substance floor the block decision uses.
+ *
  * Turn-start anchor: the most recent `queue-operation`/`enqueue` line
  * (the inbound message the gateway pushed onto the session). For
  * queued mid-turn messages (multiple `enqueue` lines per "turn"), we
@@ -232,7 +287,7 @@ function buildBlockResult(envelope, reason) {
  * false-positive that burned retry budget on healthy turns.
  *
  * @param {string} jsonl
- * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, chatId?: string, threadId?: number | null }}
+ * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, turnId?: string, chatId?: string, threadId?: number | null, pendingText?: string }}
  */
 export function scanTurnForFinalReply(jsonl) {
   const lines = jsonl.split('\n')
@@ -294,7 +349,16 @@ export function scanTurnForFinalReply(jsonl) {
           // the same bar `isFinalAnswerReply` uses to recognise a real
           // answer — counts as "undelivered content the user was waiting
           // on". #2956 review finding.
-          blocks.push({ kind: 'text', chars: String(c.text ?? '').trim().length })
+          //
+          // Carry the trimmed text itself too (Option A transcript-prose
+          // bridge): when this turn ends up blocked, the joined undelivered
+          // text becomes `pendingText` so the gateway can deliver the model's
+          // real answer directly. Trimmed per-block; joined below.
+          blocks.push({
+            kind: 'text',
+            chars: String(c.text ?? '').trim().length,
+            text: String(c.text ?? '').trim(),
+          })
         }
         continue
       }
@@ -339,10 +403,36 @@ export function scanTurnForFinalReply(jsonl) {
       lastAllowReason = blocks[i].reason
     }
   }
-  const sawUndeliveredTextAfterAllow = blocks
-    .slice(lastAllowBlockIdx + 1)
+  const undeliveredSlice = blocks.slice(lastAllowBlockIdx + 1)
+  const sawUndeliveredTextAfterAllow = undeliveredSlice
     .some((b) => b.kind === 'text' && (b.chars ?? 0) >= FINAL_ANSWER_MIN_CHARS)
 
+  // Option A transcript-prose bridge: isolate the undelivered final-answer
+  // prose so the gateway can deliver it directly.
+  //
+  // Finding 2 (#3228): a real dropped answer is a SINGLE substantive block —
+  // NOT concatenated inter-tool narration ("Let me check…", "Still querying…")
+  // that only crosses the floor once joined. The old code joined ALL post-
+  // delivery text blocks and surfaced the join whenever the COMBINED length
+  // hit the floor, so a run of short narration masqueraded as a final answer
+  // (and in the zero-delivery case that join was every text block in the
+  // turn). Instead, deliver only the LAST block that CLEARS the substance
+  // floor ON ITS OWN. This mirrors the block decision itself
+  // (`sawUndeliveredTextAfterAllow`, which requires a single ≥floor block) and
+  // handles the "big answer then short closer" shape by delivering the answer,
+  // not the closer. When no single block clears the floor, `pendingText` stays
+  // undefined and the gateway falls through to the re-prompt / represent nets.
+  const substantiveBlocks = undeliveredSlice.filter(
+    (b) =>
+      b.kind === 'text' &&
+      typeof b.text === 'string' &&
+      (b.chars ?? 0) >= FINAL_ANSWER_MIN_CHARS,
+  )
+  const pendingText =
+    substantiveBlocks.length > 0
+      ? substantiveBlocks[substantiveBlocks.length - 1].text
+      : undefined
+
   if (lastAllowBlockIdx === -1) {
     // No qualifying delivery/silence event anywhere in the turn.
     // Cron-fired turns (#2053): a scheduled turn that produced no
@@ -354,7 +444,7 @@ export function scanTurnForFinalReply(jsonl) {
     if (envelope.source === 'cron') {
       return { decided: 'allow', reason: 'cron-source' }
     }
-    return buildBlockResult(envelope, 'no-final-reply')
+    return buildBlockResult(envelope, 'no-final-reply', pendingText)
   }
 
   if (sawUndeliveredTextAfterAllow) {
@@ -363,7 +453,7 @@ export function scanTurnForFinalReply(jsonl) {
     // sent through a delivery tool. This is the "at least once" bug:
     // an early ack (or any qualifying reply) must not amnesty
     // everything written afterward.
-    return buildBlockResult(envelope, 'trailing-text-after-reply')
+    return buildBlockResult(envelope, 'trailing-text-after-reply', pendingText)
   }
 
   return { decided: 'allow', reason: lastAllowReason }