switchroom 0.18.19 → 0.18.21

package/telegram-plugin/gateway/gateway.ts

@@ -192,7 +192,8 @@ import { appendActivityLabel, clipNarrative, renderActivityFeedWithNested, forma
 import { formatModelLabel } from '../model-label.js'
 import { createSessionModelSource } from './session-model-source.js'
 import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
-import { REPLY_TOOLS, isDraftOfReply } from '../narrative-dedup.js'
+import { REPLY_TOOLS } from '../narrative-dedup.js'
+import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { createTurnTypingLoop } from './turn-typing-loop.js'
@@ -236,7 +237,7 @@ import { decideSilentReplyAnchor } from '../silent-reply-anchor.js'
 import { classifyInbound } from '../inbound-classifier.js'
 import * as silencePoke from '../silence-poke.js'
 import * as pendingProgress from '../pending-work-progress.js'
-import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd, silentEndFallbackText, type SilentEndDeps } from '../silent-end.js'
+import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd, silentEndFallbackText, decideCapturedProseDelivery, settleCapturedProseDelivery, CAPTURED_PROSE_MIN_CHARS, type SilentEndDeps, type CapturedProseSendOutcome } from '../silent-end.js'
 import { isFinalAnswerReply, isSubstantiveFinalReply, FINAL_ANSWER_MIN_CHARS } from '../final-answer-detect.js'
 import { deriveTurnRole, decideTerminalReason, parsePostAnswerLivenessMs, evaluatePostAnswerLiveness, type LoopRole } from '../turn-liveness-floor.js'
 import { createAnswerStream, type AnswerStreamHandle } from '../answer-stream.js'
@@ -348,7 +349,7 @@ const REPLY_TO_TEXT_MAX = 200
 // #1161 silent-end fallback text now lives in ../silent-end.ts
 // (`silentEndFallbackText`, imported above) so the transport-boundary
 // tests exercise the real string — see PR #2892.
-import { splitMarkdownChunks, repairEscapedWhitespace, normalizeParagraphBreaks, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { splitMarkdownChunks, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { scrubVoice } from '../text-voice-scrub.js'
 import {
@@ -399,6 +400,11 @@ import {
   decideTurnFlush,
   isTurnFlushSafetyEnabled,
 } from '../turn-flush-safety.js'
+// PR A — deterministic answer-ready quiescence flush (late-delivery fix).
+import {
+  AnswerReadyFlushController,
+  resolveAnswerReadyFlushMs,
+} from '../answer-ready-flush.js'
 // #1667 — pure decision core for the turn_end answer-delivery gate (#1664).
 import { decideTurnEndGate } from './turn-end-gate.js'
 // #1122 PR3: turn-flush-prose-recovery removed with the progress card.
@@ -514,7 +520,7 @@ import { resolveOutboundTopic as resolveOutboundTopicHelper, topicForRecipient,
 import { readTurnUsages } from '../../src/agents/perf.js'
 import { buildContextOccupancy, writeContextOccupancySnapshot } from './context-occupancy.js'
 import { decideProactiveCompact, initialCompactState, type CompactState } from './proactive-compact.js'
-import { decideIdleClear, classifyIdleEvent, idleDurationToMs, DEFAULT_IDLE_CLEAR_MS } from './idle-clear.js'
+import { IdleTracker, idleDurationToMs, DEFAULT_IDLE_CLEAR_MS } from './idle-clear.js'
 import { nextCompactNotify, idleCompactNotifyState, type CompactNotifyState } from './compact-notify.js'
 import {
   tryHostdDispatch,
@@ -545,7 +551,7 @@ import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { handleRequestMs365Approval } from './ms365-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
-import { isCronIdentity, deliverInjectWithFallback } from './cron-session.js'
+import { isCronIdentity, isCronInjectFire, deliverInjectWithFallback } from './cron-session.js'
 import {
   ObligationLedger,
   buildObligationRepresentInbound,
@@ -608,6 +614,11 @@ import { resolveAnswerThreadId } from './answer-thread-resolve.js'
 import { resolveChatIdFallback } from './chat-id-fallback.js'
 import { decideObligationTurnEnd } from './obligation-turn-end.js'
 import { maybeRotate } from './turns-jsonl-rotate.js'
+import {
+  buildTurnRecord,
+  finalizeBackstopSend,
+  type DeliveryOutcome,
+} from './turn-record-status.js'
 import {
   createDeliveryQueue,
   trackDelivery,
@@ -713,6 +724,7 @@ import { redact } from '../secret-detect/redact.js'
 import { classifyAdminGate } from '../admin-commands/index.js'
 import {
   startSubagentWatcher,
+  resolveInflightTerminalCapMs,
   type SubagentWatcherHandle,
 } from '../subagent-watcher.js'
 import { listRecords as listWorktreeRecords, touchHeartbeat as touchWorktreeHeartbeat } from '../../src/worktree/registry.js'
@@ -2015,6 +2027,14 @@ function resolveSubagentOriginChat(
  * hits the fallback). A gateway restart clears it.
  */
 const WORKER_FEED_FALLBACK_LOG_CAP = 256
+/**
+ * Margin added to the watcher's in-flight terminal cap to form the worker-feed
+ * backstop TTL (`staleWorkerTtlMs`). The feed reaps a row only once it has been
+ * silent for cap + this margin — comfortably past the watcher's own terminal-
+ * transition latency, so the backstop can only ever bite a genuinely ghosted
+ * slot, never a live-but-quiet worker. 5 min.
+ */
+const WORKER_FEED_STALE_TTL_MARGIN_MS = 5 * 60_000
 const workerFeedOwnerDmFallbackLogged = new Set<string>()
 
 /**
@@ -3039,6 +3059,16 @@ type CurrentTurn = {
   // even though `replyCalled` is true — the #1664 case where the real answer
   // ended up as plain transcript text rendered into an ephemeral draft.
   finalAnswerDelivered: boolean
+  // PR B (send-honesty). The REAL fate of a backstop (turn-flush) send,
+  // stamped only AFTER the async send resolves inside the IIFE — success →
+  // 'delivered', throw/partial → 'failed', reply-tool-already-sent
+  // short-circuit → 'suppressed'. `emitTurnRecord` derives the recorded
+  // status from THIS (via `computeTurnStatus`) rather than the speculative
+  // `finalAnswerDelivered` flag, so a flood-dropped answer is logged
+  // `send_failed` instead of a false `complete`. Undefined on the synchronous
+  // turn-end paths (reply-tool tail, silent-marker, genuine no-reply), where
+  // the legacy `finalAnswerDelivered` reading still applies unchanged.
+  deliveryOutcome?: DeliveryOutcome
   // Feed-reopen-after-ack refinement — whether the reply that set
   // `finalAnswerDelivered` was a *substantive* final answer (stream
   // `done`, or ≥200 chars) as opposed to a short pinging interim ACK.
@@ -3100,6 +3130,14 @@ type CurrentTurn = {
   silentAnchorText: string
   capturedText: string[]
   orphanedReplyTimeoutId: ReturnType<typeof setTimeout> | null
+  // PR A — answer-ready quiescence flush timer. Armed in `case 'text'` once the
+  // turn has a genuine composed terminal answer and is quiescent; fires a
+  // positive `answer-ready-quiescence` synthetic turn_end after the ~1 s
+  // debounce so the answer is delivered deterministically instead of waiting on
+  // the unreliable turn_duration signal or the ~150 s orphaned-reply backstop.
+  // Cleared on any tool activity, on `endCurrentTurnAtomic`, and re-armed on
+  // each subsequent text chunk (the debounce).
+  answerReadyFlushTimeoutId: ReturnType<typeof setTimeout> | null
   // Per-turn liveness tracker for the orphaned-reply backstop. Owns
   // `lastStreamEventAt` (stamped on ANY genuine stream event so a model
   // reasoning pause keeps the turn "recently streaming" and re-arms the fuse
@@ -3212,17 +3250,19 @@ type CurrentTurn = {
   // (via `renderActivityFeed`) as a capped chronological list into the
   // in-place edited activity message and clears on reply. Reset per turn.
   mirrorLines: string[]
-  // Narrative-dedup gate state (JSONL-text-narrative primitive). A `text`
-  // block is held here for ONE lookahead step so the next event (a tool_use
-  // or turn_end) can decide draft-then-send (SUPPRESS, it duplicates the
-  // reply) vs working-narration (SHOW it as a transient mirrorLines step).
-  // Null when nothing is pending. The pure decision lives in
-  // narrative-dedup.ts; this slot is the per-turn cursor. Reset per turn.
-  // Invariant `chat-is-the-single-source-of-truth`: a SHOWN narrative is
-  // rendered through the SAME appendActivityLabel→renderStepFeed path as a
-  // tool step — a transient, clipped, rolling-window line replaced by the
-  // next event, never a persisted parallel mirror.
-  pendingNarrative: { text: string } | null
+  // Narrative-dedup gate state (JSONL-text-narrative primitive). A `text` block
+  // is parked for ONE lookahead step so the next event (a tool_use or turn_end)
+  // can decide draft-then-send (SUPPRESS, it duplicates the reply) vs
+  // working-narration (SHOW it as a transient mirrorLines step). The pure park /
+  // timer / retract state machine lives in `narrative-flush.ts`; this controller
+  // is the per-turn instance, wired with the SHOW effect (`showNarrativeStep`),
+  // the RETRACT effect (splice the timer-painted line out of `mirrorLines`), and
+  // a real `unref`'d `setTimeout` scheduler for the ~`PENDING_NARRATIVE_FLUSH_MS`
+  // early paint. Reset per turn. Invariant `chat-is-the-single-source-of-truth`:
+  // a SHOWN narrative renders through the SAME appendActivityLabel→renderStepFeed
+  // path as a tool step — transient, clipped, rolling-window, never a persisted
+  // parallel mirror.
+  narrativeGate: NarrativeFlushController
   // Most-recently-seen reply/stream_reply `input.text` for this turn — the
   // ACTUAL delivered answer surface. Set wherever a REPLY_TOOL tool_use is
   // handled in the reducer. `flushPendingNarrativeAtTurnEnd` compares a
@@ -4738,14 +4778,19 @@ function releaseTurnBufferGate(key: string, endingTurn?: CurrentTurn): void {
 function emitTurnRecord(turn: CurrentTurn, endedAt: number): void {
   try {
     const rec =
-      JSON.stringify({
-        ts: Math.floor(endedAt / 1000),
-        agent: process.env.SWITCHROOM_AGENT_NAME ?? 'unknown',
-        duration_ms: turn.startedAt > 0 ? endedAt - turn.startedAt : 0,
-        tools: turn.toolCallCount ?? 0,
-        status: turn.finalAnswerDelivered ? 'complete' : 'no_reply',
-        turn_id: turn.turnId,
-      }) + '\n'
+      JSON.stringify(
+        buildTurnRecord(
+          {
+            agent: process.env.SWITCHROOM_AGENT_NAME ?? 'unknown',
+            startedAt: turn.startedAt,
+            toolCallCount: turn.toolCallCount ?? 0,
+            turnId: turn.turnId,
+            finalAnswerDelivered: turn.finalAnswerDelivered,
+            deliveryOutcome: turn.deliveryOutcome,
+          },
+          endedAt,
+        ),
+      ) + '\n'
     const turnsPath = '/state/agent/turns.jsonl'
     // Size-cap rotation: keep at most one rotated generation so the file can't
     // grow unbounded on a long-lived agent. Best-effort (never throws).
@@ -4765,7 +4810,10 @@ function emitTurnRecord(turn: CurrentTurn, endedAt: number): void {
   }
 }
 
-function endCurrentTurnAtomic(turn: CurrentTurn): void {
+function endCurrentTurnAtomic(
+  turn: CurrentTurn,
+  opts?: { deferRecord?: boolean },
+): number | null {
   // PR-4e — keyed liveness + keyed clear (leak-close-at-origin). Flag-OFF: the
   // guard is `currentTurn === turn` and the clear nulls the singleton, verbatim.
   // Flag-ON: the guard becomes `byKey.get(turn'sKey) === turn` (so a flip to
@@ -4774,7 +4822,12 @@ function endCurrentTurnAtomic(turn: CurrentTurn): void {
   // `turn`. `endCurrentTurnForKey` returns false (no delete) when the entry no
   // longer matches — the same early-return semantics as the old `!== turn` guard.
   const key = statusKey(turn.sessionChatId, turn.sessionThreadId)
-  if (!turnLiveForItsTopic(turn)) return
+  if (!turnLiveForItsTopic(turn)) return null
+  // PR A — the turn is ending (this is the ONE place every turn-end path funnels
+  // through, incl. the answer-ready flush's own synthetic turn_end). Clear the
+  // quiescence timer so a real turn_end that lands first cancels a pending flush,
+  // guaranteeing exactly-once delivery.
+  clearAnswerReadyFlushTimeout(turn)
   endCurrentTurnForKey(turn, key) // currentTurnByKey.delete(key) + mirror clear
   // Status-surface observability: one line at every turn CLEAR (with how far
   // the turn got), plus a DEGRADED warning when the turn did tool work but the
@@ -4783,7 +4836,15 @@ function endCurrentTurnAtomic(turn: CurrentTurn): void {
   process.stderr.write(
     `telegram gateway: ${formatTurnLifecycle('clear', 'turn_end', turn, turnEndedAt)}\n`,
   )
-  emitTurnRecord(turn, turnEndedAt)
+  // PR B — the turn-flush backstop defers the record write to its async send
+  // IIFE (passing `{ deferRecord: true }`) so the recorded `status` reflects the
+  // REAL send outcome (`turn.deliveryOutcome`) rather than the speculative
+  // `finalAnswerDelivered` flag set before the send ran. All synchronous
+  // turn-end paths still emit here, unchanged. `turnEndedAt` is returned so the
+  // deferred caller stamps the same ended-at (stable `duration_ms`).
+  if (opts?.deferRecord !== true) {
+    emitTurnRecord(turn, turnEndedAt)
+  }
   const degraded = detectStatusSurfaceDegraded(turn)
   if (degraded != null) {
     process.stderr.write(
@@ -4831,6 +4892,11 @@ function endCurrentTurnAtomic(turn: CurrentTurn): void {
     clearTimeout(turn.noReplyDrainTimer)
     turn.noReplyDrainTimer = null
   }
+  // Teardown the narrative gate's early-paint timer so it can neither leak past
+  // the turn nor fire against a torn-down turn. (Idempotent — no-op when never
+  // armed / already fired. `flushPendingNarrativeAtTurnEnd` on the turn_end event
+  // normally disarms it first; this is the belt-and-braces teardown net.)
+  turn.narrativeGate?.teardown()
   // Pass `turn` so purgeReactionTracking sees the authoritative
   // replyCalled flag even though we just nulled module-scope
   // currentTurn. Without this, the shadow trace's outboundEmitted
@@ -4846,6 +4912,7 @@ function endCurrentTurnAtomic(turn: CurrentTurn): void {
   // wedging forever. No-op when this turn delivered, when nothing is
   // buffered, or when the serialize feature is off.
   armNoReplyDrainTimer(turn)
+  return turnEndedAt
 }
 
 /**
@@ -4961,31 +5028,25 @@ function maybeProactiveCompact(): void {
 // turn, so this runs on its own interval. "Idle" means NOTHING HAS HAPPENED
 // since the last thing happened — inbound, cron fire, or ANY claude session
 // event (turn start, tool call, tool result, text, sub-agent event, turn end)
-// resets the timer via markIdleActivity(); a turn ending additionally stamps
-// markIdleTurnEnd(). Fires once per idle period; never mid-turn
+// resets the timer via idleTracker.noteInbound/noteEvent; a turn ending
+// additionally stamps the turn-end clock. Fires once per idle period; never mid-turn
 // (turnInFlightForGate, the same gate compaction uses).
 //
 // It is emphatically NOT "no turn has *started* recently" — that reading wiped
 // overlord's 3h of working context on 2026-07-11 for the crime of being busy.
 // See the idle-clear.ts header.
-let lastIdleActivityAt = Date.now();
-let lastIdleTurnEndAt: number | null = null;
-let idleAutoCleared = false;
-let idleClearDispatching = false;
+// #3115 — idle bookkeeping is ONE stateful object the gateway holds, not four
+// bare `let`s + scattered inline stamp/decide logic. The tracker owns the
+// clocks (lastActivity / lastTurnEnd) and the fire-once + re-entrancy latches;
+// the gateway feeds it environment inputs (window, turn gate, background-work
+// suppressor) at decision time. Extracting it makes the wiring importable and
+// testable — a deleted stamp call now fails a test instead of silently
+// re-introducing the #3113 "productive work gets wiped" bug. See idle-clear.ts.
+const idleTracker = new IdleTracker(Date.now());
 
 /** Reset the idle timer + re-arm auto-clear. Call on ANY activity. */
 function markIdleActivity(): void {
-  lastIdleActivityAt = Date.now();
-  idleAutoCleared = false;
-}
-
-/**
- * Stamp "a turn just ended". The idle window is measured from
- * max(lastActivityAt, lastTurnEndedAt), so a turn that ran LONGER than the
- * window can't be cleared on the first tick after `turnInFlight` goes false.
- */
-function markIdleTurnEnd(): void {
-  lastIdleTurnEndAt = Date.now();
+  idleTracker.noteInbound(Date.now());
 }
 
 /** Idle window in ms: env override → per-agent config → 3h default. 0 disables. */
@@ -5012,40 +5073,77 @@ function resolveIdleClearMs(): number {
 
 /** Evaluate idle auto-clear (runs on IDLE_CLEAR_CHECK_MS interval). */
 function maybeIdleClear(): void {
-  if (idleClearDispatching) return;
+  if (idleTracker.isDispatching) return;
   const agentName = process.env.SWITCHROOM_AGENT_NAME;
   if (!agentName) return;
   const idleClearMs = resolveIdleClearMs();
-  const decision = decideIdleClear(
-    {
-      lastActivityAt: lastIdleActivityAt,
-      lastTurnEndedAt: lastIdleTurnEndAt,
-      idleClearMs,
-      alreadyCleared: idleAutoCleared,
-      turnInFlight: turnInFlightForGate(),
-    },
-    Date.now(),
-  );
+  const decision = idleTracker.decide(Date.now(), {
+    idleClearMs,
+    turnInFlight: turnInFlightForGate(),
+    // #3117 — TTL-bounded background-work suppressor. A detached sub-agent
+    // (Agent/Task dispatched, main turn ended before it returned) is invisible
+    // to turnInFlightForGate(); consult the pending-dispatch flag directly so a
+    // silent long-running worker isn't /clear'ed out from under its handback.
+    // The TTL keeps a leaked flag from disabling idle-clear forever.
+    backgroundWorkInFlight: pendingProgress.anyPendingAsyncDispatchWithin(
+      pendingProgress.BACKGROUND_WORK_SUPPRESS_TTL_MS,
+    ),
+  });
   if (!decision.clear) return;
   // Fire once per idle period — set BEFORE the await so the next tick can't
   // double-dispatch. markIdleActivity() re-arms on the next real activity.
-  idleAutoCleared = true;
-  idleClearDispatching = true;
+  idleTracker.markClearFired();
+  idleTracker.beginDispatch();
   process.stderr.write(
     `telegram gateway: idle auto-/clear for ${agentName} ` +
       `(idle >= ${Math.round(idleClearMs / 60_000)}m)\n`,
   );
-  // Accepted check-to-send race (same as maybeProactiveCompact): a new inbound
-  // could arrive between the gate check and the tmux send; /clear then lands in
-  // claude's prompt buffer and runs at the next idle prompt (inject.ts FUTURE-GAP).
-  void injectSlashCommandImpl(agentName, '/clear')
+  // #3116 — write-time precondition closes (most of) the check-to-send race.
+  // A new inbound could arrive between the gate decision above and the tmux
+  // send; without a guard /clear lands in claude's prompt buffer and runs at
+  // the next idle prompt (inject.ts FUTURE-GAP), clobbering that inbound's
+  // session. The precondition below is re-evaluated INSIDE the pane lock,
+  // immediately before send-keys, and RE-RUNS THE FULL idle decision against
+  // the live clocks + turnInFlightForGate() — not a bespoke "activity
+  // unchanged" check — so any new activity in the gap suppresses the /clear
+  // (and so a future background-work input to the idle decision is honoured at
+  // write time for free). Residual: an inbound landing AFTER send-keys but
+  // before claude submits the buffered /clear is still clobbered — full
+  // closure needs buffer-cancel (tracked as a follow-up issue).
+  // alreadyCleared is latched true above for re-entrancy; decideIgnoringLatch
+  // judges idleness on the live clocks + turn/background gates only, so any
+  // activity that arrived in the check-to-send gap still suppresses the /clear.
+  // #3117 — the background-work suppressor is re-sampled at write time too, so a
+  // sub-agent dispatched in the gap (or still fresh within its TTL) suppresses
+  // the buffered /clear. This composes with #3116's write-time re-eval
+  // automatically — same tracker/decider, live inputs.
+  const stillIdleAtWrite = (): boolean =>
+    idleTracker.decideIgnoringLatch(Date.now(), {
+      idleClearMs: resolveIdleClearMs(),
+      turnInFlight: turnInFlightForGate(),
+      backgroundWorkInFlight: pendingProgress.anyPendingAsyncDispatchWithin(
+        pendingProgress.BACKGROUND_WORK_SUPPRESS_TTL_MS,
+      ),
+    }).clear;
+  void injectSlashCommandImpl(agentName, '/clear', { precondition: stillIdleAtWrite })
+    .then((result) => {
+      if (result.outcome === 'skipped') {
+        // Activity arrived in the check-to-send gap; re-arm so the next idle
+        // period can clear again rather than staying latched.
+        idleTracker.reArm();
+        process.stderr.write(
+          `telegram gateway: idle /clear suppressed for ${agentName} ` +
+            `(activity in check-to-send gap)\n`,
+        );
+      }
+    })
     .catch((err: unknown) => {
       process.stderr.write(
         `telegram gateway: idle /clear inject failed for ` +
           `${agentName}: ${err instanceof Error ? err.message : String(err)}\n`,
       );
     })
-    .finally(() => { idleClearDispatching = false; });
+    .finally(() => { idleTracker.endDispatch(); });
 }
 
 /**
@@ -8125,6 +8223,10 @@ const STREAM_THROTTLE_MS_OVERRIDE: number | undefined = (() => {
 })()
 const TURN_FLUSH_SAFETY_ENABLED = isTurnFlushSafetyEnabled()
 
+// PR A — answer-ready quiescence flush debounce (ms). 0 = kill-switch (never
+// arm). Resolved once at boot; env-tunable via SWITCHROOM_ANSWER_READY_FLUSH_MS.
+const ANSWER_READY_FLUSH_MS = resolveAnswerReadyFlushMs(process.env)
+
 // When SET, the answer-lane stream (telegram-plugin/answer-stream.ts) renders
 // the model's transcript text as a USER-VISIBLE edit-in-place message. Default
 // OFF: the lane stays dormant and the reply tool is the single canonical
@@ -9177,6 +9279,17 @@ const SILENCE_FLOOR_MS = parsePositiveMsEnv('SWITCHROOM_SILENCE_FLOOR_MS', 45_00
 // #2527 — role-aware terminal reaction honesty (the "thumbs-up false done"
 // fix). Default ON; SWITCHROOM_TG_TERMINAL_HONESTY=0 reverts to always-👍.
 const LIVENESS_TERMINAL_HONESTY = process.env.SWITCHROOM_TG_TERMINAL_HONESTY !== '0'
+// Option A transcript-prose delivery bridge. When a user turn ends without a
+// final answer, the Stop hook scans transcript_path and — if it isolated a
+// substantive answer the model wrote as plain text but never sent through the
+// reply tool — persists it in silent-end-pending.json as `pendingText`. On the
+// FIRST silent-end the gateway reads it back and delivers it directly via the
+// normal send path, instead of relying on the (unreliable) Stop-hook re-prompt
+// or waiting ~2-5 min for the obligation represent to recover it. Default ON;
+// SWITCHROOM_TG_CAPTURED_PROSE_DELIVERY=0 reverts to the pre-bridge behaviour
+// (re-prompt + represent only).
+const CAPTURED_PROSE_DELIVERY_ENABLED =
+  process.env.SWITCHROOM_TG_CAPTURED_PROSE_DELIVERY !== '0'
 // SILENCE_DEFER_INFLIGHT_TOOLS: previously an opt-in (=1). The new
 // isLegitimatelyWorking callback supersedes this — defer is now the DEFAULT
 // when the callback is wired. The legacy flag is kept so `=0` still lets
@@ -9989,6 +10102,250 @@ function agentHasInFlightBackgroundWork(now: number): boolean {
 // Throttle for the background-work defer diagnostic (the 5s sweep would otherwise
 // log every tick across a multi-minute research window).
 let lastBgWorkDeferLogMs = 0
+/**
+ * Option A transcript-prose delivery. Deliver the model's real final answer —
+ * isolated by the Stop hook's transcript scan and persisted as `pendingText`
+ * — directly via the normal send path on the first silent-end, then settle the
+ * bookkeeping so neither the obligation represent nor the exhausted fallback
+ * re-fires for the same answer.
+ *
+ * Double-send guard — content + turnKey dedup, NOT unconditional (Finding 4,
+ * #3228: the earlier "airtight by construction" claim overstated it):
+ *  - Before sending, `outboundDedup.check` is consulted. If the EXACT same
+ *    content already went out under the SAME `registryKey` (a prior turn_end
+ *    delivered it, or the re-prompted model's own reply landed), we SKIP the
+ *    send and only settle bookkeeping.
+ *  - After a successful send, `outboundDedup.record` is written so a late
+ *    reply-tool retry with the same content is suppressed at its send site
+ *    (executeReply / executeStreamReply already consult the same cache).
+ *  - The obligation is CLOSED and the silent-end state CLEARED, so
+ *    obligationSweep's "outbound delivered since open" guard and the represent
+ *    never re-fire for this origin.
+ *
+ * Divergence boundary (honest scope): the dedup key is
+ * `(chat, thread, normalized-content, registryKey)`. It suppresses the common
+ * double-send — the SAME answer re-sent within the TTL under the same
+ * registryKey. It does NOT catch a re-present that lands under a DIFFERENT
+ * registryKey with REWORDED content (different hash AND different key → the
+ * cross-turn carve-out in recent-outbound-dedup.ts:150-156 treats two non-null
+ * differing turnKeys as a miss): that is a genuinely different outbound and is
+ * out of scope for content-hash dedup. The obligation close + state clear are
+ * what make captured-prose and the represent mutually exclusive for the
+ * common case; the content dedup is a second, best-effort layer.
+ *
+ * Failure posture (Finding 1 + exhaustion-boundary gap, #3228): if the send
+ * throws, the catch below arms the deterministic Stop-hook re-prompt via
+ * recordUndeliveredTurnEnd (the shared teardown may have already closed the
+ * obligation when replyCalled was true, so "leaving the obligation open" is NOT
+ * a sufficient net on its own). Two sub-cases, honored via the `{exhausted}`
+ * verdict threaded out of settleCapturedProseDelivery:
+ *  - budget REMAINING (`exhausted:false`) → the silent-end state is (re)written
+ *    and the Stop-hook re-prompt will recover the answer; nothing else to do.
+ *  - budget SPENT (`exhausted:true`) → recordUndeliveredTurnEnd has CLEARED the
+ *    state (the re-prompt can no longer fire), and the obligation was already
+ *    closed by the interim-ack teardown, so the user would get NEITHER the
+ *    answer NOR the apology. We therefore deliver a user-facing fallback: first
+ *    retry the captured prose as PLAIN TEXT (a non-rich send often survives the
+ *    markdown/parse error a rich send rejected — the user gets the real
+ *    answer), and only if THAT also fails post the generic silentEndFallbackText
+ *    apology. This mirrors the non-captured exhausted path (silent-end.ts /
+ *    gateway turn_end #1161) so the captured path is never worse than main.
+ */
+async function deliverCapturedProse(args: {
+  chatId: string
+  threadId: number | undefined
+  statusKeyStr: string
+  registryKey: string | null
+  originTurnId: string
+  text: string
+  /** Turn elapsed for the honest "(waited Ns)" apology clause; optional. */
+  turnDurationMs?: number
+}): Promise<void> {
+  const { chatId, threadId, statusKeyStr, registryKey, originTurnId, text, turnDurationMs } = args
+  const now = Date.now()
+  // #3228 Finding 1 — the three settlement points (sent / skipped-dedup /
+  // failed) all funnel through the pure `settleCapturedProseDelivery` core so
+  // the failure posture is deterministic and unit-tested. `outcome` is set on
+  // each branch and applied ONCE at the bottom.
+  let outcome: CapturedProseSendOutcome
+  const already = outboundDedup.check(chatId, threadId, text, now, registryKey)
+  if (already == null) {
+    let out = normalizeParagraphBreaks(repairEscapedWhitespace(text))
+    out = redactOutboundText(out, 'captured_prose')
+    const chunks = splitMarkdownChunks(out, RICH_MESSAGE_MAX_CHARS)
+    const sentIds: number[] = []
+    try {
+      let liveThreadId: number | undefined = threadId
+      for (const c of chunks) {
+        const sent = await retryWithThreadFallback(
+          robustApiCall,
+          (tid) => {
+            // Built as a variable (not an inline literal) so excess-property
+            // checks don't reject `link_preview_options` on sendRichMessage's
+            // narrow Other<> type — mirrors the turn-flush send site.
+            const opts = {
+              link_preview_options: { is_disabled: true },
+              ...(tid != null ? { message_thread_id: tid } : {}),
+            }
+            return bot.api.sendRichMessage(chatId, richMessage(c), opts)
+          },
+          { threadId: liveThreadId, chat_id: chatId, verb: 'captured-prose.sendMessage' },
+        )
+        if (liveThreadId != null && (sent as { message_thread_id?: number }).message_thread_id == null) {
+          liveThreadId = undefined
+        }
+        sentIds.push(sent.message_id)
+      }
+      if (HISTORY_ENABLED && sentIds.length > 0) {
+        try {
+          recordOutbound({
+            chat_id: chatId,
+            thread_id: threadId ?? null,
+            message_ids: sentIds,
+            texts: chunks,
+          })
+        } catch {}
+      }
+      // 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)
+      process.stderr.write(
+        `telegram gateway: captured-prose delivery — sent ${out.length} chars recovered from ` +
+          `transcript scan (chat=${chatId} origin=${originTurnId})\n`,
+      )
+      outcome = 'sent'
+    } catch (err) {
+      // #3228 Finding 1 — the send threw, so the answer did NOT reach the user.
+      // The `failed` outcome routes to `settleCapturedProseDelivery`'s recovery
+      // path (recordUndelivered), NOT the close/clear path. This is load-bearing:
+      // the shared turn-end teardown (endCurrentTurnAtomic →
+      // decideObligationTurnEnd) already closes the obligation whenever
+      // `replyCalled === true` — exactly the interim-ack case that routes here —
+      // so "leaving the obligation open" is not a real net. Arming the Stop-hook
+      // re-prompt makes the failed send recoverable instead of silently lost.
+      process.stderr.write(
+        `telegram gateway: captured-prose delivery failed: ${(err as Error).message} — ` +
+          `arming the silent-end re-prompt net (recordUndeliveredTurnEnd) so the ` +
+          `answer is recoverable (chat=${chatId} origin=${originTurnId})\n`,
+      )
+      outcome = 'failed'
+    }
+  } else {
+    process.stderr.write(
+      `telegram gateway: captured-prose delivery skipped — this answer already went out ` +
+        `(dedup age=${already.ageMs}ms chat=${chatId} origin=${originTurnId}); settling bookkeeping\n`,
+    )
+    outcome = 'skipped-dedup'
+  }
+  // Apply the settlement bookkeeping through the pure core (#3228 Finding 1):
+  //   sent / skipped-dedup → close obligation + clear state (answer is with the
+  //                          user, so represent + exhausted fallback must not fire)
+  //   failed               → arm the Stop-hook re-prompt net (recordUndelivered),
+  //                          do NOT close/clear.
+  const settlement = settleCapturedProseDelivery(outcome, {
+    closeObligation: () => {
+      if (OBLIGATION_LEDGER_ENABLED) {
+        try { obligationLedger.close(originTurnId) } catch {}
+      }
+    },
+    clearState: () => clearSilentEndState(statusKeyStr),
+    recordUndelivered: () => {
+      try {
+        const silentEndDeps: SilentEndDeps | undefined = HISTORY_ENABLED
+          ? {
+              hasOutboundDeliveredSince: (cid, sinceMs, tid) =>
+                hasOutboundDeliveredSince(cid, sinceMs, tid, 1),
+            }
+          : undefined
+        return recordUndeliveredTurnEnd(
+          { chatId, threadId: threadId ?? null, turnKey: statusKeyStr },
+          silentEndDeps,
+        )
+      } catch (netErr) {
+        process.stderr.write(
+          `telegram gateway: captured-prose recovery-net arm failed: ${
+            (netErr as Error).message
+          } (chat=${chatId} origin=${originTurnId})\n`,
+        )
+        // Could not even record the undelivered turn — do NOT claim exhaustion
+        // (firing a fallback we can't justify). Fail safe: leave recovery to
+        // the obligation represent / next Stop hook.
+        return { exhausted: false }
+      }
+    },
+  })
+
+  // Exhaustion-boundary gap (#3228): the send FAILED on the attempt where the
+  // Stop-hook re-prompt budget was already spent, so recordUndeliveredTurnEnd
+  // cleared the state and the re-prompt can no longer recover the answer — and
+  // the obligation was already closed by the interim-ack teardown. Without this
+  // the user gets NEITHER the answer NOR the apology. Deliver a user-facing
+  // fallback, preferring the REAL answer as plain text (a non-rich send often
+  // survives the markdown/parse error the rich send threw on) before the
+  // generic apology.
+  if (outcome === 'failed' && settlement.exhausted) {
+    process.stderr.write(
+      `telegram gateway: WARN captured-prose exhausted-boundary fallback — rich send ` +
+        `failed with the re-prompt budget already spent; attempting a plain-text ` +
+        `delivery of the recovered answer before the generic apology ` +
+        `(chat=${chatId} origin=${originTurnId})\n`,
+    )
+    const plain = redactOutboundText(text, 'captured_prose')
+    const plainChunks = splitMarkdownChunks(plain, RICH_MESSAGE_MAX_CHARS)
+    try {
+      let liveThreadId: number | undefined = threadId
+      for (const c of plainChunks) {
+        // Plain sendMessage — NO parse_mode / rich rendering — so a markdown
+        // construct that made sendRichMessage 400 is sent verbatim instead.
+        const sent = await retryWithThreadFallback(
+          robustApiCall,
+          (tid) =>
+            bot.api.sendMessage(
+              chatId,
+              c,
+              tid != null ? { message_thread_id: tid } : {},
+            ),
+          { threadId: liveThreadId, chat_id: chatId, verb: 'captured-prose-plain-fallback.sendMessage' },
+        )
+        if (liveThreadId != null && (sent as { message_thread_id?: number }).message_thread_id == null) {
+          liveThreadId = undefined
+        }
+      }
+      // The real answer reached the user via plain text — record it so a late
+      // reply-tool retry with the same content is deduped at its send site.
+      outboundDedup.record(chatId, threadId, text, Date.now(), registryKey)
+      process.stderr.write(
+        `telegram gateway: captured-prose recovered via plain-text fallback ` +
+          `(chat=${chatId} origin=${originTurnId})\n`,
+      )
+    } catch (plainErr) {
+      // Plain text ALSO failed — post the generic apology so the turn is never
+      // silent (mirrors the non-captured exhausted path, gateway turn_end #1161).
+      process.stderr.write(
+        `telegram gateway: captured-prose plain-text fallback ALSO failed: ${
+          (plainErr as Error).message
+        } — posting the generic silent-end apology (chat=${chatId} origin=${originTurnId})\n`,
+      )
+      void retryWithThreadFallback(
+        robustApiCall,
+        (tid) =>
+          bot.api.sendMessage(
+            chatId,
+            silentEndFallbackText(turnDurationMs),
+            tid != null ? { message_thread_id: tid } : {},
+          ),
+        { threadId, chat_id: chatId, verb: 'captured-prose-apology-fallback.sendMessage' },
+      ).catch((err) => {
+        process.stderr.write(
+          `telegram gateway: captured-prose apology fallback send failed: ${
+            err instanceof Error ? err.message : String(err)
+          }\n`,
+        )
+      })
+    }
+  }
+}
+
 function obligationSweep(): void {
   if (!OBLIGATION_LEDGER_ENABLED) return
   if (!obligationLedger.hasOpen()) return
@@ -11460,10 +11817,18 @@ const ipcServer: IpcServer = createIpcServer({
   },
 
   onInjectInbound(_client: IpcClient, msg: InjectInboundMessage) {
-    // Cron fires (incl. cheap-cron, whose session events are dropped before
-    // currentTurn is set) are real activity — re-arm idle auto-clear so a
-    // working scheduled agent isn't wiped after 3h of "no inbound".
-    markIdleActivity()
+    // #3114 — do NOT unconditionally stamp the MAIN idle clock here. A cron
+    // fire (Tier-1 cheap-cron routed to `<agent>-cron`, or a Tier-2 main-
+    // session cron) whose cadence is shorter than `idle_clear_after` would
+    // otherwise re-arm the timer on every fire and suppress idle-clear
+    // permanently. After #3113 a cron that does real work already stamps the
+    // main clock via handleSessionEvent, so the blanket fire-time stamp is
+    // redundant for main-bridge fires and wrong for cheap-cron (whose session
+    // events are dropped for the cron identity). Only non-cron injects
+    // (reaction, vault grant, resume — genuine operator/session presence) stamp
+    // at inject time. See isCronInjectFire for the documented main-session-poll
+    // residual (a Tier-2 NO_REPLY poll still warms the clock via its real turn).
+    if (!isCronInjectFire(msg.inbound.meta)) markIdleActivity()
     const promptKey = typeof msg.inbound.meta?.prompt_key === 'string'
       ? msg.inbound.meta.prompt_key
       : 'unknown'
@@ -15021,11 +15386,10 @@ async function executeEditMessage(args: Record<string, unknown>): Promise<unknow
   // 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). No paragraph
-  // spacer pass — the NBSP spacer was removed in the #2669 follow-up because it
-  // double-gapped every paragraph; the rich renderer already shows `\n\n` as
-  // one blank line.
-  if (!editLiteralText) editRawText = stripExcessBold(normalizePunctuation(editRawText))
+  // 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
@@ -15313,6 +15677,68 @@ function resetOrphanedReplyTimeout(): void {
   }
 }
 
+/**
+ * PR A — DETERMINISTIC answer-ready quiescence flush controller.
+ *
+ * The orchestration (arm / debounce / rollover-guard / fire-time re-verify /
+ * disarm) lives in the extracted, unit-tested `AnswerReadyFlushController`
+ * (answer-ready-flush.ts) — the gateway only supplies the thin deps below and
+ * calls `.reset()` / `.clear(turn)`. Behaviour:
+ *
+ * - `reset()` (from `case 'text'`): (re)arm iff the turn has a genuine composed
+ *   terminal answer (the SAME `decideTurnFlush` classifier the turn-flush branch
+ *   uses) AND is quiescent. Each text chunk re-arms → the debounce.
+ * - `clear(turn)` (from tool activity + `endCurrentTurnAtomic`): the DISARM.
+ * - on fire: re-pin `currentTurn === turn`, re-verify quiescence, then dispatch
+ *   a positive `answer-ready-quiescence` synthetic turn_end that routes through
+ *   the IDENTICAL turn-flush send path (endCurrentTurnAtomic → send-gated IIFE →
+ *   honest PR-B record). Replaces the ~150 s dead wait with ~1 s, in code.
+ *
+ * Exactly-once: the synthetic turn_end's `endCurrentTurnAtomic` nulls the atom,
+ * so a later REAL turn_end (or the orphaned backstop) short-circuits at its
+ * `turn != null` guard; `endCurrentTurnAtomic` also calls `.clear(turn)` so a
+ * real turn_end that lands FIRST cancels a pending flush. `outboundDedup` is the
+ * second layer.
+ *
+ * The `answer-ready-quiescence` reason bypasses the `durationMs===-1`
+ * recently-streaming SUPPRESSION guard (the terminal answer text itself stamps
+ * recentlyStreaming): quiescence IS the positive "streaming has settled" signal,
+ * the opposite of the hung-turn backstop that guard protects.
+ */
+const answerReadyFlush = new AnswerReadyFlushController<CurrentTurn>({
+  getCurrentTurn: () => currentTurn,
+  getArmInput: (turn) => ({
+    flush: {
+      chatId: turn.sessionChatId,
+      replyCalled: turn.replyCalled,
+      capturedText: turn.capturedText,
+      flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
+    },
+    inFlightToolCount: toolFlightTracker.inFlightCount(),
+    hasPendingAsyncDispatch: pendingProgress.hasPendingAsyncDispatch(
+      statusKey(turn.sessionChatId, turn.sessionThreadId),
+    ),
+    flushWindowMs: ANSWER_READY_FLUSH_MS,
+  }),
+  getTimerHandle: (turn) => turn.answerReadyFlushTimeoutId,
+  setTimerHandle: (turn, handle) => {
+    turn.answerReadyFlushTimeoutId = handle
+  },
+  onFlush: () =>
+    handleSessionEvent({ kind: 'turn_end', durationMs: -1, reason: 'answer-ready-quiescence' }),
+  log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
+})
+
+/** PR A — disarm the answer-ready flush timer for a turn (thin adapter). */
+function clearAnswerReadyFlushTimeout(turn: CurrentTurn | null): void {
+  answerReadyFlush.clear(turn)
+}
+
+/** PR A — (re)arm the answer-ready flush timer for the current turn (debounce). */
+function resetAnswerReadyFlushTimeout(): void {
+  answerReadyFlush.reset()
+}
+
 function closeActivityLane(chatId: string, threadId: number | undefined): void {
   const key = chatKeyWithSuffix(chatId, threadId, 'activity')
   const stream = activeDraftStreams.get(key)
@@ -15373,6 +15799,75 @@ function composeTurnActivity(turn: CurrentTurn, final = false, liveSuffix = ''):
   return renderActivityFeedWithNested(turn.mirrorLines, childLines, final, liveSuffix, stepCount, header)
 }
 
+// PENDING_NARRATIVE_FLUSH_MS is now defined in and imported from
+// `narrative-flush.ts` (the kernel's home) so the main-agent gateway path and
+// the worker/sub-agent watcher share ONE source of truth for the time-box.
+// The main path paints a parked block via the SAME `showNarrativeStep` path a
+// lookahead would, and a timer-painted block that later proves to be the reply
+// is deterministically retracted (the RETRACT effect wired into the controller
+// below).
+
+/**
+ * Retract a narration step the flush timer painted EARLY that turned out to draft
+ * the outgoing reply — the effect half of the anti-double-print guarantee's timer
+ * path. Splice the line out of `mirrorLines` and re-render, so neither the live
+ * nor the finalized card surfaces the answer as a narration step. The splice runs
+ * synchronously BEFORE the reply's `clearActivitySummary` finalize reads
+ * `mirrorLines`, so the persisted card is clean regardless of the re-render.
+ */
+function retractNarrativeLine(turn: CurrentTurn, text: string): void {
+  const clipped = clipNarrative(text)
+  const idx = turn.mirrorLines.lastIndexOf(clipped)
+  if (idx === -1) return // rolled out of the window already — nothing to retract
+  turn.mirrorLines.splice(idx, 1)
+  // Live re-render without the retracted line (the finalize path reads the same
+  // spliced array; this only matters for the interim-ack case where finalize
+  // isn't called on this reply). Guarded on a non-null render so an emptied feed
+  // doesn't blank the card.
+  const rerender = composeTurnActivity(turn)
+  if (rerender == null) return
+  turn.activityPendingRender = rerender
+  const ea = emissionAuthorityFor(turn)
+  cardDrainGate(turn, ea, () => {
+    if (ea.mayDrain(turn)) {
+      ea.openOrEditCard('narrative', () => {
+        turn.activityInFlight = drainActivitySummary(turn, 'narrative')
+      })
+    }
+  })
+}
+
+/**
+ * Build a per-turn narrative gate: the pure park/timer/retract state machine
+ * (`narrative-flush.ts`) wired to THIS turn's SHOW effect (`showNarrativeStep`),
+ * RETRACT effect (`retractNarrativeLine`), and a real `unref`'d `setTimeout`
+ * scheduler. The scheduler captures the turn's own timer handle so a turn swap
+ * can't mis-target it — mirrors the `noReplyDrainTimer` discipline.
+ */
+function makeNarrativeGate(turn: CurrentTurn): NarrativeFlushController {
+  let handle: ReturnType<typeof setTimeout> | null = null
+  return new NarrativeFlushController(
+    {
+      show: (text) => showNarrativeStep(turn, text),
+      retractShown: (text) => retractNarrativeLine(turn, text),
+    },
+    {
+      arm: (fn, ms) => {
+        if (handle != null) clearTimeout(handle)
+        handle = setTimeout(fn, ms)
+        handle.unref?.()
+      },
+      disarm: () => {
+        if (handle != null) {
+          clearTimeout(handle)
+          handle = null
+        }
+      },
+    },
+    PENDING_NARRATIVE_FLUSH_MS,
+  )
+}
+
 /**
  * Render a SHOWN narrative text block as a transient liveness step — the
  * same path a tool label takes (appendActivityLabel → renderStepFeed), so
@@ -15418,27 +15913,20 @@ function resolvePendingNarrativeOnTool(
   toolName: string,
   input: Record<string, unknown> | undefined,
 ): void {
-  const pending = turn.pendingNarrative
-  if (pending == null) return
-  turn.pendingNarrative = null
-  if (REPLY_TOOLS.has(toolName)) {
-    const replyText = typeof input?.text === 'string' ? (input.text as string) : ''
-    if (isDraftOfReply(pending.text, replyText)) return // draft of the answer → SUPPRESS
-  }
-  showNarrativeStep(turn, pending.text) // working preamble / post-action narration → SHOW
+  // Delegate to the pure park/timer/retract kernel: it cancels the early-paint
+  // timer, retracts a timer-painted block that THIS reply drafts (anti-double-
+  // print), then SHOWs / SUPPRESSes the parked block. See narrative-flush.ts §2.
+  turn.narrativeGate.resolveOnTool(toolName, input)
 }
 
 /**
  * Narrative-dedup gate, step 1 (reducer-side): a new narrative block
  * arrived. A previously-pending block had nothing reply-shaped immediately
  * after it (pure narration) → flush it as SHOWN, then stage the new one for
- * one lookahead step. See narrative-dedup.ts §2b.
+ * one lookahead step AND arm the time-boxed early paint. See narrative-flush.ts.
  */
 function stagePendingNarrative(turn: CurrentTurn, text: string): void {
-  if (turn.pendingNarrative != null) {
-    showNarrativeStep(turn, turn.pendingNarrative.text)
-  }
-  turn.pendingNarrative = { text }
+  turn.narrativeGate.stage(text)
 }
 
 /**
@@ -15446,14 +15934,11 @@ function stagePendingNarrative(turn: CurrentTurn, text: string): void {
  * trailing narrative block and nothing after it. SUPPRESS only when the turn
  * already delivered its answer via reply/stream_reply and the trailing text
  * is a draft of that answer; otherwise SHOW (genuine trailing narration like
- * "Done — all green."). See narrative-dedup.ts §2b.
+ * "Done — all green."). Also cancels the early-paint timer and retracts a
+ * timer-painted draft of the delivered answer. See narrative-flush.ts §3.
  */
 function flushPendingNarrativeAtTurnEnd(turn: CurrentTurn, lastReplyText: string): void {
-  const pending = turn.pendingNarrative
-  if (pending == null) return
-  turn.pendingNarrative = null
-  if (lastReplyText.length > 0 && isDraftOfReply(pending.text, lastReplyText)) return // trailing duplicate of the answer
-  showNarrativeStep(turn, pending.text)
+  turn.narrativeGate.flushAtTurnEnd(lastReplyText)
 }
 
 /**
@@ -16239,9 +16724,7 @@ function handleSessionEvent(ev: SessionEvent): void {
   // background workers keep the timer warm exactly as long as they are working.
   {
     const durationMs = ev.kind === 'turn_end' ? ev.durationMs : undefined
-    const signal = classifyIdleEvent(ev.kind, durationMs)
-    if (signal.activity) markIdleActivity()
-    if (signal.turnEnded) markIdleTurnEnd()
+    idleTracker.noteEvent(ev.kind, Date.now(), durationMs)
   }
   switch (ev.kind) {
     case 'enqueue': {
@@ -16287,6 +16770,13 @@ function handleSessionEvent(ev: SessionEvent): void {
           clearTimeout(prior.orphanedReplyTimeoutId)
           prior.orphanedReplyTimeoutId = null
         }
+        // Same bounded-leak class (early-paint 250ms setTimeout): the prior
+        // turn may have armed its narrative gate's early-paint timer before
+        // being superseded. Left untorn, ~250ms later it fires showNarrativeStep
+        // on the dead turn and can paint a stale narration card below the new
+        // turn's surface. Teardown is guard-safe and idempotent (no-op when never
+        // armed / already fired / already disarmed by the prior turn's turn_end).
+        prior?.narrativeGate?.teardown()
         // #1067: swap the entire turn atom in one assignment. Every
         // handler captures `const turn = currentTurn` at entry, so a
         // captured-then-awaited read can't reattribute to the new turn.
@@ -16346,6 +16836,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           silentAnchorText: '',
           capturedText: [],
           orphanedReplyTimeoutId: null,
+          answerReadyFlushTimeoutId: null,
           // Fresh liveness tracker: lastStreamEventAt seeded to the turn start
           // so a turn that never streams still trips the fuse after windowMs.
           liveness: new LivenessTracker(startedAt),
@@ -16363,7 +16854,10 @@ function handleSessionEvent(ev: SessionEvent): void {
           activityEverOpened: false,
           activityDrainFailures: 0,
           mirrorLines: [],
-          pendingNarrative: null,
+          // Assigned immediately after this literal via makeNarrativeGate(next) —
+          // the controller's SHOW/RETRACT effects close over the turn object, which
+          // can't reference itself inside its own initializer.
+          narrativeGate: undefined as unknown as NarrativeFlushController,
           lastReplyText: '',
           foregroundSubAgents: new Map(),
           answerStream: null,
@@ -16376,6 +16870,9 @@ function handleSessionEvent(ev: SessionEvent): void {
             statusKey(ev.chatId, enqThreadIdNum),
           ),
         }
+        // Wire the per-turn narrative gate now that `next` exists (its SHOW/RETRACT
+        // effects close over the turn). Born with this turn, torn down at turn end.
+        next.narrativeGate = makeNarrativeGate(next)
         // PR-4e — route the turn-SET through the keyed accessor: flag-OFF assigns
         // the singleton (byte-identical to `currentTurn = next`); flag-ON sets the
         // per-topic `byKey[statusKey]` entry AND the most-recent mirror. The key is
@@ -16544,6 +17041,11 @@ function handleSessionEvent(ev: SessionEvent): void {
     case 'tool_use': {
       const turn = currentTurn
       if (turn == null) return
+      // PR A — the model resumed work (surface or otherwise). Cancel any pending
+      // answer-ready quiescence flush: the turn is no longer quiescent. (Fire-time
+      // re-verification would also catch this, but disarming here avoids a wasted
+      // wakeup and matches the design's disarm-on-tool requirement.)
+      clearAnswerReadyFlushTimeout(turn)
       // Narrative-dedup gate step 2 (JSONL-text-narrative primitive): a
       // narrative block was pending; this tool_use is the lookahead event
       // that decides it. reply/stream_reply with near-identical text ⇒
@@ -16630,6 +17132,11 @@ function handleSessionEvent(ev: SessionEvent): void {
       // where the JSONL tool_use rows arrive too late.
       const turn = currentTurn
       if (turn == null) return
+      // PR A — a tool_label (real-time, ~250 ms) means the model is producing
+      // work right now: cancel any pending answer-ready quiescence flush (the
+      // turn is not quiescent). Fires ahead of the JSONL tool_use, so it disarms
+      // the timer at the earliest deterministic point.
+      clearAnswerReadyFlushTimeout(turn)
       // SECONDARY FIX: an active tool_label means the model is producing work
       // right now — re-arm the orphaned-reply fuse so a multi-phase tool turn
       // (write → compile → test → fix) that regularly emits labels doesn't let
@@ -16952,6 +17459,11 @@ function handleSessionEvent(ev: SessionEvent): void {
         preambleSuppressor.onText(ev.text)
       }
       resetOrphanedReplyTimeout()
+      // PR A — (re)arm the deterministic answer-ready quiescence flush. Each
+      // text chunk debounces the timer; it fires only after ~1 s of no new
+      // stream events, delivering a composed toolless answer without waiting on
+      // the unreliable turn_duration signal or the ~150 s orphaned backstop.
+      resetAnswerReadyFlushTimeout()
 
       if (isContextExhaustionText(ev.text) && turn != null) {
         const chatId = turn.sessionChatId
@@ -17041,7 +17553,14 @@ function handleSessionEvent(ev: SessionEvent): void {
       // check to the full isLegitimatelyWorking predicate so detached background
       // work and human-wait tools (ask_user) are also protected.
       // INVARIANT: a REAL turn_end (durationMs >= 0) is NEVER suppressed.
-      if (ev.durationMs === -1) {
+      // PR A carve-out: the answer-ready quiescence flush also uses
+      // `durationMs:-1`, but it is a POSITIVE "streaming has settled" signal
+      // fired only after ~1 s of no stream events AND no in-flight tool — the
+      // exact opposite of a hung turn. It must NOT be suppressed by
+      // recentlyStreaming (the terminal answer text itself stamps that window,
+      // which is the whole bug). Its own arm/fire predicate already re-verified
+      // quiescence, so let it through to deliver.
+      if (ev.durationMs === -1 && ev.reason !== 'answer-ready-quiescence') {
         const turn = currentTurn
         const key = turn != null ? statusKey(turn.sessionChatId, turn.sessionThreadId) : ''
         // Widened to also suppress while the turn is RECENTLY STREAMING — a
@@ -17109,8 +17628,8 @@ function handleSessionEvent(ev: SessionEvent): void {
       // delivered reply text and SUPPRESS the duplicate; otherwise SHOW
       // genuine trailing narration ("Done — all green."). Must run BEFORE
       // clearActivitySummary so a SHOWN line lands in the feed's final
-      // render. Always clears turn.pendingNarrative so it can't leak across
-      // turns.
+      // render. Always clears the gate's parked block (and disarms its
+      // early-paint timer) so nothing can leak across turns.
       //
       // NIT 2 (reply-proxy precision): use `turn.lastReplyText` (the
       // most-recent reply/stream_reply input.text) rather than
@@ -17523,6 +18042,17 @@ function handleSessionEvent(ev: SessionEvent): void {
         // that this branch never reaches, this set is belt-and-braces —
         // it keeps the captured `turn` atom internally consistent for any
         // future reader.)
+        // PR B (Fix 4 — intentional record/ledger inconsistency, out of scope).
+        // We keep setting finalAnswerDelivered=true HERE (before the async send)
+        // so endCurrentTurnAtomic's obligation CLOSE (decideObligationTurnEnd,
+        // ~4818) fires unchanged at turn end. PR B only makes the turns.jsonl
+        // *record* honest (status send_failed when the send later throws) — it
+        // deliberately does NOT change obligation behavior. Consequence: a
+        // send_failed turn still CLOSES its obligation, so a flood-dropped
+        // answer is NOT re-presented — an honest record without honest recovery.
+        // Re-delivery on send_failed (drive obligation close from real send
+        // success, leave it open on failure) is a separate change — see the
+        // PR-B handback FOLLOW-UP note; do NOT touch the ledger in this PR.
         turn.finalAnswerDelivered = true
         // Feed-reopen refinement: turn-flush delivers the model's terminal
         // transcript text as the genuine answer (not an ack). Default to
@@ -17553,7 +18083,15 @@ function handleSessionEvent(ev: SessionEvent): void {
         // sendMessage await for this turn will see currentTurn == null
         // and bail; a new enqueue will swap in a fresh atom. The
         // `backstop*` locals above hold everything the IIFE needs.
-        endCurrentTurnAtomic(turn)
+        //
+        // PR B — defer the turns.jsonl record write to the send IIFE below so
+        // the recorded `status` reflects the REAL send outcome, not the
+        // speculative `finalAnswerDelivered=true` set just above. Everything
+        // else in endCurrentTurnAtomic (atom null, gate release, obligation
+        // bookkeeping, purge) still runs synchronously here for the #1067 /
+        // #1556 wedge-safety reasons. `backstopTurnEndedAt` is null iff the
+        // atom was already torn down elsewhere (no record to emit).
+        const backstopTurnEndedAt = endCurrentTurnAtomic(turn, { deferRecord: true })
         // #549 fix — turn-flush takes ownership of the captured-text
         // backup; reset the preamble buffer (its content is already in
         // the captured `capturedText`, which turn-flush is about to send).
@@ -17593,6 +18131,15 @@ function handleSessionEvent(ev: SessionEvent): void {
                 // async IIFE ran). The old redundant purgeReactionTracking
                 // here re-fired on an already-cleared key WITHOUT `endingTurn`,
                 // emitting an inconsistent shadow trace. Removed.
+                //
+                // PR B — the reply tool already delivered this turn's answer, so
+                // the flush was legitimately suppressed. Emit the deferred record
+                // as 'suppressed' (→ `complete`, since the reply path set
+                // finalAnswerDelivered). Not a failure.
+                if (backstopTurnEndedAt != null) {
+                  turn.deliveryOutcome = 'suppressed'
+                  emitTurnRecord(turn, backstopTurnEndedAt)
+                }
                 return
               }
             } catch {}
@@ -17607,15 +18154,26 @@ function handleSessionEvent(ev: SessionEvent): void {
             link_preview_options: { is_disabled: true },
           }
           const limit = RICH_MESSAGE_MAX_CHARS
-          // The `\n\n` block joins from turn-flush-safety.ts render as normal
-          // single blank lines under the Bot API 10.1 rich GFM path, so no
-          // spacer pass runs before splitting (the NBSP spacer was removed in
-          // the #2669 follow-up — it double-gapped every paragraph). Mirrors
-          // executeReply, which now also sends the normalized text as-is.
-          const renderedText = capturedText
-          const htmlChunks = splitMarkdownChunks(renderedText, limit)
+          // PR B (Fix 1) — send accounting is declared OUTSIDE the try so the
+          // single-record `finally` below can read it, and ALL setup (the chunk
+          // split) is pulled INSIDE the try so a throw there still lands in the
+          // finally (→ one honest `send_failed` row) rather than rejecting the
+          // IIFE with zero turns.jsonl rows written / an unhandled rejection.
+          let htmlChunks: string[] = []
           const sentIds: number[] = []
+          // track whether the send threw so the deferred record reflects the
+          // real outcome (throw OR partial multi-chunk → send_failed).
+          let sendThrew = false
           try {
+            // #2798 / #2692 — inject visible blank-line spacers into prose `\n\n`
+            // gaps before splitting, exactly as executeReply does. The rich GFM
+            // renderer collapses a bare `\n\n` gap TIGHT, so without this the
+            // paragraph boundaries from the '\n\n' block join (turn-flush-safety
+            // .ts) would still render jammed together. Mirrors reply's
+            // `addParagraphSpacers(text)` on the non-literal path (idempotent —
+            // exactly one U+00A0 spacer per gap, never doubled).
+            const renderedText = addParagraphSpacers(capturedText)
+            htmlChunks = splitMarkdownChunks(renderedText, limit)
             // #654 deterministic double-message fix. If the progress
             // card is on screen (60s timer fired before turn_end), edit
             // it in place with the first chunk of the answer instead of
@@ -17723,10 +18281,33 @@ function handleSessionEvent(ev: SessionEvent): void {
               unpinProgressCardForChat?.(backstopChatId, backstopThreadId)
             }
           } catch (err) {
+            sendThrew = true
             process.stderr.write(`telegram gateway: turn-flush send failed: ${(err as Error).message}\n`)
             // #1713: backstop send failed — finalize as error so the
             // turn ends cleanly with 😱 rather than leaving it open.
             if (backstopCtrl) backstopCtrl.finalize('error')
+          } finally {
+            // PR B (Fix 1) — SINGLE-RECORD GUARANTEE. The send has now RESOLVED
+            // (or thrown); this finally runs on EVERY in-process exit of the send
+            // block — clean send, throw in setup/split, throw mid-send — so
+            // exactly one turns.jsonl row is written, with the outcome reflecting
+            // what actually happened. A throw or a partial multi-chunk delivery
+            // (sentIds < htmlChunks) or an un-run/empty split → 'failed' → status
+            // `send_failed`; a full delivery → 'delivered' → `complete`. This
+            // replaces the false `complete` the old synchronous write produced
+            // for a flood-dropped / errored answer the user never received, and
+            // restores the old code's one-row-per-turn guarantee (the pre-finally
+            // shape wrote ZERO rows if setup threw). The suppressed-reply branch
+            // above already emitted its record and `return`ed BEFORE reaching
+            // this try, so it can never double-write with this finally.
+            if (backstopTurnEndedAt != null) {
+              finalizeBackstopSend(turn, {
+                threw: sendThrew,
+                sentCount: sentIds.length,
+                chunkCount: htmlChunks.length,
+              })
+              emitTurnRecord(turn, backstopTurnEndedAt)
+            }
           }
           // #2094 cosmetic: the trailing `finally { purgeReactionTracking() }`
           // was removed. endCurrentTurnAtomic already ran the canonical purge
@@ -17826,6 +18407,65 @@ function handleSessionEvent(ev: SessionEvent): void {
         // is exactly `turn.finalAnswerDelivered === false` here (silent-marker
         // and flush both returned earlier), delegated to the pure gate core.
         if (turnEndDecision === 'reprompt') {
+          // Option A transcript-prose bridge (#3227). Before falling through to
+          // the re-prompt / represent safety nets, check whether the Stop hook
+          // already isolated this turn's real answer from the transcript and
+          // persisted it in silent-end-pending.json (`pendingText`). That file
+          // lands BEFORE this turn_end handler runs (the hook fires upstream of
+          // the gateway's own state write — see silent-end-interrupt-stop.mjs).
+          // If a substantive answer is waiting, deliver it directly via the
+          // normal send path NOW, instead of leaning on the (unreliable)
+          // Stop-hook re-prompt or waiting ~2-5 min for the obligation
+          // represent. The delivery closes the obligation + records dedup, so
+          // the represent and a late reply-tool retry are both suppressed —
+          // captured-prose delivery and represent are mutually exclusive.
+          const proseDecision = CAPTURED_PROSE_DELIVERY_ENABLED
+            ? decideCapturedProseDelivery({
+                turnKey: tKey,
+                // Per-turn nonce (#3228 Finding 3) — the persisted record must
+                // belong to THIS turn, not a stale carryover from a prior turn
+                // on the same chat/thread (tKey is not per-turn unique).
+                turnId: turn.turnId,
+                minChars: CAPTURED_PROSE_MIN_CHARS,
+              })
+            : { deliver: false as const, reason: 'no-state' as const }
+          if (proseDecision.deliver && proseDecision.text != null) {
+            // Deliver the recovered answer directly. This runs async and owns
+            // its own bookkeeping — on success it closes the obligation +
+            // records dedup + clears the silent-end state; on send FAILURE it
+            // arms the recovery net itself (see below) instead of leaving the
+            // answer lost.
+            //
+            // We DELIBERATELY skip recordUndeliveredTurnEnd on the HAPPY path
+            // here: re-arming the Stop-hook re-prompt for an answer that just
+            // went out is exactly what this bridge exists to avoid.
+            //
+            // #3228 Finding 1 — the send-failure net can NOT rely on the shared
+            // turn-end teardown "leaving the obligation open". That teardown
+            // (endCurrentTurnAtomic → decideObligationTurnEnd) closes the
+            // obligation whenever `replyCalled === true`, which is EXACTLY the
+            // interim-ack case that reaches this branch. So a thrown send would
+            // otherwise leave the answer permanently lost (obligation already
+            // closed by teardown, recordUndeliveredTurnEnd skipped). The real
+            // net lives INSIDE deliverCapturedProse's catch: it calls
+            // recordUndeliveredTurnEnd, arming the deterministic Stop-hook
+            // re-prompt (parity with the non-captured path below).
+            process.stderr.write(
+              `telegram gateway: captured-prose delivery engaged on first silent-end ` +
+                `chat=${chatId} turnKey=${tKey} (#3227)\n`,
+            )
+            void deliverCapturedProse({
+              chatId,
+              threadId,
+              statusKeyStr: tKey,
+              registryKey: turn.registryKey ?? null,
+              originTurnId: turn.turnId,
+              text: proseDecision.text,
+              // For the honest "(waited Ns)" clause if the exhaustion-boundary
+              // apology fallback fires (#3228).
+              turnDurationMs,
+            })
+          } else {
           // PR #2892 (deterministic-turn-liveness RFC Phase 2) hardening:
           // wire the represent-guard-style staleness
           // check (`recordSilentTurnEnd`'s `hasOutboundDeliveredSince` dep) so
@@ -17871,6 +18511,7 @@ function handleSessionEvent(ev: SessionEvent): void {
               )
             })
           }
+          } // end else (no captured-prose to deliver)
         }
         signalTracker.clear(tKey)
         silencePoke.endTurn(tKey)
@@ -29445,6 +30086,18 @@ void (async () => {
               // channels.telegram.worker_feed.max_rows via the config cascade
               // (scaffold emits SWITCHROOM_TG_WORKER_FEED_MAX_ROWS); unset → 8.
               maxRows: workerFeedMaxRows,
+              // Backstop TTL for the feed's stale-row reaper, DERIVED in code
+              // from the watcher's effective in-flight terminal cap (same env /
+              // default the watcher itself resolves) plus a margin — NOT a
+              // hardcoded assumption about that cap's value. This keeps the
+              // invariant "the feed must never reap a row the watcher still
+              // considers live" enforced even if an operator raises the cap via
+              // SWITCHROOM_SUBAGENT_INFLIGHT_TERMINAL_CAP_MS: a worker mid-very-
+              // long tool can go silent up to the cap before the watcher
+              // declares it terminal, so the feed waits cap + margin before
+              // force-collapsing a row the terminal signals somehow never
+              // removed.
+              staleWorkerTtlMs: resolveInflightTerminalCapMs() + WORKER_FEED_STALE_TTL_MARGIN_MS,
               // #3207 review: GROUP-level status pin. Workers now coalesce into
               // ONE shared message, so the pin must follow the GROUP lifecycle,
               // not a single worker's — otherwise a sibling's finish unpins a
@@ -29610,6 +30263,23 @@ void (async () => {
                   `telegram gateway: worker ${agentId} NAMED AS LOST — falsely finalised twice, resurrection chain bound reached (issue #3023)\n`,
                 )
               },
+              // Worker-feed ghost-leak fix: the watcher's AUTHORITATIVE terminal
+              // sweep (`cleanupTerminalAgent`) fires for EVERY terminal agent,
+              // including the JSONL-vanished and boot-orphan paths that never
+              // reach `onFinish`. Wire feed removal here so cleanup and feed-
+              // remove can't diverge: `terminate` is idempotent (a no-op once
+              // `onFinish` already removed the row) and, when this was the last
+              // live worker, collapses the shared card to its terminal summary
+              // and unpins it — closing the immortal/unpinned/buried-card leak.
+              onTerminalCleanup: (agentId) => {
+                try {
+                  void workerActivityFeed?.terminate(agentId)
+                } catch (err) {
+                  process.stderr.write(
+                    `telegram gateway: worker terminal-cleanup feed removal error agent=${agentId}: ${(err as Error).message}\n`,
+                  )
+                }
+              },
               onFinish: ({ agentId, outcome, description, resultText, toolCount, durationMs, background: entryBackground }) => {
                 // Reaction promotion: if the parent turn already ended
                 // with this (or another) worker still running, its 👍 was
@@ -29872,7 +30542,7 @@ void (async () => {
               // suppresses stale-after-restart delivery (a 4-h-old
               // "still working (5m)" would be a lie). Sweep on handback
               // lives in the `onFinish` block just above.
-              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model }) => {
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model, skeleton }) => {
                 let fleetChatId = ''
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
@@ -29962,6 +30632,15 @@ void (async () => {
                     return
                   }
                   if (surface !== 'nest') return // 'skip' — orphan-status off
+                  // #3233: a skeleton liveness cue carries NO step content by
+                  // construction (empty latestSummary/progressLine) — it exists
+                  // ONLY to create/keep-alive the orphan worker-feed row handled
+                  // just above. Branch EXPLICITLY on the `skeleton` discriminator
+                  // rather than inferring "no content" from an empty step line:
+                  // a skeleton cue must never nest into the parent's live turn
+                  // card (there is nothing to render, and the parent's own card
+                  // already owns the turn). Deterministic, controls-in-code.
+                  if (skeleton) return
                   const turn = currentTurn
                   if (turn == null) return // defensive: 'nest' implies a live turn
                   // Render regardless of `replyCalled` — a foreground Task
@@ -30107,8 +30786,17 @@ void (async () => {
                   return
                 }
 
+                // #3233: with the worker feed DISABLED, the legacy bucket relay
+                // below injects a synthesized "still working" inbound turn. A
+                // skeleton liveness cue carries an EMPTY latestSummary, so
+                // letting it reach the relay would queue a blank/contentless
+                // progress card. The `skeleton` discriminator is threaded into
+                // the pure decision (gate 1b → 'skeleton-liveness'), which drops
+                // it deterministically (controls-in-code, unit-tested) rather
+                // than an opaque inline return here.
                 const progressOrigin = resolveSubagentOriginChat(agentId)
                 const decision = decideSubagentProgress({
+                  skeleton: skeleton === true,
                   disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
                   isBackground,
                   // Prefer the conversation the Task was dispatched from over