switchroom 0.18.24 → 0.18.25

package/telegram-plugin/registry/turns-schema.ts

@@ -120,6 +120,26 @@ export interface Turn {
    * Null for turns that were never resumed.
    */
   resumed_at: number | null
+  /**
+   * The claude session id (the `<sessionId>.jsonl` transcript stem) that
+   * produced this turn's assistant output, stamped DURING the turn as soon as
+   * the first session event is observed (see `stampTurnSessionId`). Crash-
+   * survival redelivery uses this to resolve the EXACT transcript file for an
+   * interrupted turn, instead of `findActiveSessionFile`'s most-recent-mtime
+   * heuristic — which can shadow the new boot session's own transcript. Null
+   * until the turn produces its first session event (or for pre-migration rows).
+   */
+  session_id: string | null
+  /**
+   * Ms epoch at which the interrupted turn's captured-but-undelivered final
+   * answer was re-sent to the user at boot (crash-survival redelivery). This is
+   * the at-most-once ledger for redelivery — first-write-wins via
+   * `WHERE answer_redelivered_at IS NULL` (see `markAnswerRedelivered`). Kept on
+   * a SEPARATE marker from `resumed_at` because the two concerns have different
+   * correctness contracts (resume = at-most-once side-effect replay; redelivery
+   * = at-most-once answer send) and a turn can be both. Null until redelivered.
+   */
+  answer_redelivered_at: number | null
   created_at: number
   updated_at: number
 }
@@ -190,6 +210,15 @@ const PHASE3_MIGRATIONS = [
   `ALTER TABLE turns ADD COLUMN resumed_at INTEGER`,
 ]
 
+// Columns added for crash-survival redelivery. `session_id` pins the exact
+// transcript file for an interrupted turn (so redelivery never resolves the
+// wrong session via a most-recent-file heuristic); `answer_redelivered_at` is
+// the at-most-once redelivery ledger (stamped synchronously with the re-send).
+const PHASE4_MIGRATIONS = [
+  `ALTER TABLE turns ADD COLUMN session_id TEXT`,
+  `ALTER TABLE turns ADD COLUMN answer_redelivered_at INTEGER`,
+]
+
 function applySchema(db: SqliteDatabase): void {
   db.exec('PRAGMA journal_mode = WAL')
   db.exec('PRAGMA synchronous = NORMAL')
@@ -206,7 +235,7 @@ function applySchema(db: SqliteDatabase): void {
   // Run migrations. SQLite doesn't support "ADD COLUMN IF NOT EXISTS", so
   // we swallow the "duplicate column" error to stay idempotent on
   // pre-existing registry.db files.
-  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS]) {
+  for (const sql of [...PHASE1_MIGRATIONS, ...PHASE2_MIGRATIONS, ...PHASE3_MIGRATIONS, ...PHASE4_MIGRATIONS]) {
     try {
       db.exec(sql)
     } catch (err) {
@@ -283,6 +312,8 @@ interface RawTurnRow {
   tool_call_count: number | null
   interrupt_reason: string | null
   resumed_at: number | null
+  session_id: string | null
+  answer_redelivered_at: number | null
   created_at: number
   updated_at: number
 }
@@ -304,6 +335,8 @@ function mapRow(row: RawTurnRow): Turn {
     tool_call_count: row.tool_call_count,
     interrupt_reason: row.interrupt_reason,
     resumed_at: row.resumed_at,
+    session_id: row.session_id ?? null,
+    answer_redelivered_at: row.answer_redelivered_at ?? null,
     created_at: row.created_at,
     updated_at: row.updated_at,
   }
@@ -692,6 +725,61 @@ export function markTurnResumed(
   `).run(now, now, turnKey)
 }
 
+/**
+ * Stamp the claude `session_id` (the `<sessionId>.jsonl` transcript stem) on a
+ * turn the FIRST time it is observed, DURING the turn. First-write-wins via
+ * `WHERE session_id IS NULL` so the hot session-event path can call this on
+ * every event cheaply and idempotently. This must run while the turn is live
+ * (before any crash) so crash-survival redelivery can resolve the exact
+ * transcript file for an interrupted turn — never the most-recent-mtime file,
+ * which a fresh boot session would shadow. No-ops if `turnKey` is not found.
+ */
+export function stampTurnSessionId(
+  db: SqliteDatabase,
+  turnKey: string,
+  sessionId: string,
+  now: number = Date.now(),
+): void {
+  if (!sessionId) return
+  db.prepare(`
+    UPDATE turns
+    SET session_id = ?,
+        updated_at = ?
+    WHERE turn_key = ? AND session_id IS NULL
+  `).run(sessionId, now, turnKey)
+}
+
+/**
+ * Stamp `answer_redelivered_at` on an interrupted turn at the moment its
+ * captured-but-undelivered final answer has been re-sent at boot (crash-
+ * survival redelivery). This is the at-most-once ledger for redelivery: once
+ * stamped, the redelivery decision skips the turn on any later restart.
+ *
+ * Ordering: the caller stamps SYNCHRONOUSLY with the send (immediately after
+ * the send resolves), the same discipline as `markTurnResumed`. A residual
+ * race remains — the window between the Telegram send completing and this row
+ * (plus the send's own `role='assistant'` history row) becoming durable. A
+ * crash landing in that window could re-send on the next boot; the durable
+ * text-identity delivery oracle (matching the projected answer text against
+ * delivered `messages` rows) is what CATCHES that duplicate, so redelivery is
+ * at-most-once modulo detection, never a silent double-send of a fresh answer.
+ *
+ * Idempotent and first-write-wins (`WHERE answer_redelivered_at IS NULL`).
+ * No-ops if `turnKey` is not found.
+ */
+export function markAnswerRedelivered(
+  db: SqliteDatabase,
+  turnKey: string,
+  now: number = Date.now(),
+): void {
+  db.prepare(`
+    UPDATE turns
+    SET answer_redelivered_at = ?,
+        updated_at            = ?
+    WHERE turn_key = ? AND answer_redelivered_at IS NULL
+  `).run(now, now, turnKey)
+}
+
 /**
  * Return the single most-recently-started turn IFF it was interrupted
  * (`ended_at IS NULL`, or `ended_via` in {restart, sigterm, timeout,

package/telegram-plugin/session-tail.ts

@@ -118,6 +118,17 @@ export type SessionEvent =
   // and reserved for a future staging-skip optimization; do not assume the
   // gate keys on it.
   | { kind: 'text'; text: string; blockIndex: number; lastInMessage: boolean }
+  // Per-assistant-message token usage for the MAIN agent, extracted from
+  // `message.usage` on each `type:"assistant"` transcript line. `totalTokens`
+  // is the NEW-work delta for THIS message (input + output + cache_creation,
+  // via sumUsageTokens; cache_read is deliberately excluded — replayed cached
+  // context, not new work). `messageId` is `message.id` —
+  // REQUIRED for dedup: Claude Code persists one logical assistant message as
+  // MULTIPLE JSONL lines sharing one `message.id`, each stamped with the SAME
+  // `usage` block, so the accumulator must count a given `messageId` only once
+  // (naive summing across lines over-counts). Null messageId → un-dedupable,
+  // counted as-is. Mirrors `sub_agent_usage` but for the parent's OWN tokens.
+  | { kind: 'usage'; messageId: string | null; totalTokens: number }
   | { kind: 'tool_result'; toolUseId: string; toolName: string | null; isError?: boolean; errorText?: string }
   // `reason` is set ONLY by an internal gateway-synthesized turn_end (never by
   // the JSONL projection). `answer-ready-quiescence` (PR A) marks the positive
@@ -134,6 +145,17 @@ export type SessionEvent =
   // `model` kind (sentinel-filtered, emitted first) but agent-scoped so the
   // watcher can track it per WorkerEntry and thread it onto the worker card.
   | { kind: 'sub_agent_model'; agentId: string; model: string }
+  // Per-assistant-message token usage for a SUB-AGENT, extracted from
+  // `message.usage` on each `type:"assistant"` transcript line. `totalTokens`
+  // is the NEW-work delta for THIS message (input + output + cache_creation;
+  // cache_read is deliberately excluded — replayed cached context, not new
+  // work). `messageId` is `message.id` — REQUIRED for dedup: Claude
+  // Code ≥2.1.x persists one logical assistant message as MULTIPLE JSONL lines
+  // sharing one `message.id`, each stamped with the SAME `usage` block, so the
+  // watcher must count a given `messageId` only once (naive summing across
+  // lines 2-3x over-counts; verified against live worker jsonl — 131 usage
+  // lines / 59 unique ids). Null messageId → un-dedupable, counted as-is.
+  | { kind: 'sub_agent_usage'; agentId: string; messageId: string | null; totalTokens: number }
   | { kind: 'sub_agent_tool_use'; agentId: string; toolUseId: string | null; toolName: string; input?: Record<string, unknown>; precomputedLabel?: string }
   // Same shared contract as the main-agent `text` kind — see its doc above
   // (including the `lastInMessage` projection-artifact note). The wire-kind
@@ -283,6 +305,34 @@ export function projectAssistantTextBlocks(
  * projectSubagentLine). A thinking-only or empty line returns false; the real
  * terminal rides the following content line, which also carries `end_turn`.
  */
+/**
+ * Sum the NEW token work carried by a single assistant message's `usage`
+ * object: `input_tokens + output_tokens + cache_creation_input_tokens`. Every
+ * field is guarded with `?? 0` — Claude Code omits fields that are zero/absent
+ * on some messages. A non-object (or missing) usage returns 0 so the caller
+ * can skip a no-usage line.
+ *
+ * `cache_read_input_tokens` is DELIBERATELY EXCLUDED. On a prompt-cached turn
+ * it is replayed context (billed at ~10% and doing no new work), and it
+ * dominates the raw total — including it made the displayed number 2-5x bigger
+ * than the actual work done this turn and misread as a cost/effort figure. The
+ * three fields kept here represent new tokens processed this turn: fresh input,
+ * generated output, and newly-written cache. The nested `iterations` /
+ * `cache_creation` breakdowns are subsets already reflected in the top-level
+ * fields — never add them, that double-counts. Verified against live worker
+ * jsonl.
+ */
+export function sumUsageTokens(usage: unknown): number {
+  if (usage == null || typeof usage !== 'object') return 0
+  const u = usage as Record<string, unknown>
+  const n = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
+  return (
+    n(u.input_tokens) +
+    n(u.output_tokens) +
+    n(u.cache_creation_input_tokens)
+  )
+}
+
 export function assistantLineCarriesAnswerSurface(
   content: Array<Record<string, unknown>> | undefined,
 ): boolean {
@@ -303,6 +353,108 @@ export function assistantLineCarriesAnswerSurface(
   return false
 }
 
+export interface TrailingAnswer {
+  /** Concatenated trailing assistant text of the last turn (after the last
+   *  tool_use / turn boundary). Empty when there is none to redeliver. */
+  text: string
+  /** True iff the last content-bearing event of the transcript was text — i.e.
+   *  the turn ended on an answer, not a dangling tool_use (mid-stream). Bounds
+   *  the preamble-vs-final ambiguity for crash-survival redelivery. */
+  trailingIsText: boolean
+}
+
+/**
+ * Re-project the TRAILING assistant answer of the last turn from a claude
+ * session transcript's full text. Pure — reuses the same `projectTranscriptLine`
+ * kernel the live tail uses, so it inherits the `isApiErrorMessage` suppression
+ * (a usage-limit error line is NEVER resurfaced as an answer) and the empty-block
+ * drop. Used by crash-survival redelivery to recover the finished-but-never-sent
+ * answer from disk after a pre-flush crash.
+ *
+ * Semantics: walk the event stream in order; the "answer buffer" accumulates
+ * `text` events and is RESET by any `tool_use` (the answer-so-far was a preamble
+ * to a tool call) or by a turn boundary. What remains at end-of-file is the
+ * trailing answer of the last turn. `trailingIsText` is true only when the final
+ * content-bearing event was that text (not a tool_use), so a turn killed mid-tool
+ * never redelivers a stale preamble as an answer.
+ *
+ * TURN BOUNDARY (diff-review defect #2). A boundary is BOTH an `enqueue`
+ * queue-operation AND a real `type:"user"` message line. The kernel
+ * (`projectTranscriptLine`) emits nothing for a plain user text line — it only
+ * projects `tool_result` blocks out of `type:"user"` — so relying on `enqueue`
+ * alone would let two turns separated by a plain user line (no intervening
+ * tool_use) CONCATENATE. `isRealUserTurnBoundary` detects that separator
+ * directly so only the LAST turn's trailing text is projected.
+ */
+export function projectTrailingAnswerFromTranscript(transcriptText: string): TrailingAnswer {
+  const buf: string[] = []
+  let lastMeaningful: 'text' | 'tool_use' | null = null
+  for (const rawLine of transcriptText.split('\n')) {
+    const line = rawLine.trim()
+    if (!line) continue
+    if (isRealUserTurnBoundary(line)) {
+      // A real user message opens a new turn — discard any prior turn's tail.
+      buf.length = 0
+      lastMeaningful = null
+      continue
+    }
+    for (const ev of projectTranscriptLine(line)) {
+      if (ev.kind === 'enqueue') {
+        // New inbound turn — any prior turn's trailing text is not this turn's.
+        buf.length = 0
+        lastMeaningful = null
+      } else if (ev.kind === 'tool_use') {
+        buf.length = 0
+        lastMeaningful = 'tool_use'
+      } else if (ev.kind === 'text') {
+        const t = (ev as { text?: string }).text ?? ''
+        if (t.trim().length > 0) {
+          buf.push(t)
+          lastMeaningful = 'text'
+        }
+      }
+      // thinking / model / dequeue / tool_result etc. do not affect the answer.
+    }
+  }
+  const text = buf.join('').trim()
+  return { text, trailingIsText: lastMeaningful === 'text' && text.length > 0 }
+}
+
+/**
+ * Detect a real inbound-user turn separator in a claude session JSONL.
+ *
+ * A `type:"user"` line is EITHER a genuine user message (its `message.content`
+ * is a string, or an array carrying a `{type:"text"}` block) OR a tool_result
+ * carrier (`message.content` is an array of `{type:"tool_result"}` blocks only).
+ * Only the former opens a new turn. The main projection kernel emits NO event
+ * for a genuine user text line (it projects tool_result blocks only), so the
+ * trailing-answer projector needs this to break turns that are separated by a
+ * plain user line rather than an interleaved `enqueue` queue-operation. Pure.
+ */
+export function isRealUserTurnBoundary(line: string): boolean {
+  let obj: Record<string, unknown>
+  try {
+    obj = JSON.parse(line)
+  } catch {
+    return false
+  }
+  if (obj.type !== 'user') return false
+  const message = obj.message as Record<string, unknown> | undefined
+  const content = message?.content
+  if (typeof content === 'string') return content.trim().length > 0
+  if (Array.isArray(content)) {
+    // A genuine user message carries a text block; a tool_result carrier does
+    // not. Presence of any text block ⇒ real user turn.
+    for (const c of content) {
+      if (typeof c === 'object' && c != null && (c as Record<string, unknown>).type === 'text') {
+        const t = String((c as Record<string, unknown>).text ?? '')
+        if (t.trim().length > 0) return true
+      }
+    }
+  }
+  return false
+}
+
 /**
  * Project a single transcript line into a SessionEvent (or null if it's
  * uninteresting noise). Caller is responsible for the JSON parse — if a
@@ -364,6 +516,23 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     if (typeof mainModel === 'string' && !isModelSentinel(mainModel)) {
       events.push({ kind: 'model', model: mainModel })
     }
+    // Per-message token usage (MAIN tier): surface the summed delta so the
+    // gateway can accumulate the parent's OWN running total for the turn card's
+    // metrics line. `messageId` (message.id) rides along so the accumulator
+    // dedups the multi-line split-message shape (one logical message → many
+    // JSONL lines, one shared `usage`). Emitted only when a usage object with a
+    // non-zero total exists — a no-usage line contributes nothing and is
+    // skipped. Mirrors the sub-agent emit below; this counts the parent alone
+    // (sub-agents report their own tokens on their worker-feed rows).
+    const mainUsageTotal = sumUsageTokens(message?.usage)
+    if (mainUsageTotal > 0) {
+      const mainMsgId = message?.id
+      events.push({
+        kind: 'usage',
+        messageId: typeof mainMsgId === 'string' ? mainMsgId : null,
+        totalTokens: mainUsageTotal,
+      })
+    }
     // Text→narrative projection comes from the ONE shared kernel
     // (projectAssistantTextBlocks): it owns the empty-drop + blockIndex +
     // lastInMessage contract. We emit its events at their source positions
@@ -518,6 +687,22 @@ export function projectSubagentLine(
     if (typeof subModel === 'string' && !isModelSentinel(subModel)) {
       events.push({ kind: 'sub_agent_model', agentId, model: subModel })
     }
+    // Per-message token usage: surface the summed delta so the watcher can
+    // accumulate a running total for the worker-activity card's metrics line.
+    // `messageId` (message.id) rides along so the watcher dedups the multi-line
+    // split-message shape (one logical message → many JSONL lines, one shared
+    // `usage`). Emitted only when a usage object with a non-zero total exists —
+    // a no-usage line contributes nothing and is skipped here.
+    const subUsageTotal = sumUsageTokens(message?.usage)
+    if (subUsageTotal > 0) {
+      const subMsgId = message?.id
+      events.push({
+        kind: 'sub_agent_usage',
+        agentId,
+        messageId: typeof subMsgId === 'string' ? subMsgId : null,
+        totalTokens: subUsageTotal,
+      })
+    }
     // Text→narrative projection comes from the SAME shared kernel as the
     // main agent (projectAssistantTextBlocks): one source for the empty-drop
     // + blockIndex + lastInMessage contract. The `make` adapter only changes

package/telegram-plugin/subagent-watcher.ts

@@ -125,6 +125,19 @@ export interface WorkerEntry {
   lastActivityAt: number
   /** Number of tool calls seen so far. */
   toolCount: number
+  /**
+   * Running TOTAL tokens across every assistant message the worker has emitted
+   * (input + output + cache_creation, summed via sumUsageTokens; cache_read is
+   * excluded — replayed cached context, not new work).
+   * Accumulated from `sub_agent_usage` events, deduped by `seenUsageMessageIds`
+   * so the multi-line split-message shape (one logical message persisted as
+   * several JSONL lines sharing one `message.id` + identical `usage`) counts
+   * once. Rendered on the worker card's metrics line. 0 for a worker that never
+   * emitted a usage block (e.g. a non-Claude/litellm transcript).
+   */
+  totalTokens: number
+  /** message.id set already folded into `totalTokens` (usage dedup). */
+  seenUsageMessageIds: Set<string>
   /** True once a stall notification has been sent (suppresses repeat). */
   stallNotified: boolean
   /**
@@ -557,6 +570,9 @@ export interface SubagentWatcherConfig {
     state: WorkerState
     outcome: 'completed' | 'failed' | 'orphan'
     toolCount: number
+    /** Final running TOTAL tokens across the worker's whole life
+     *  (`WorkerEntry.totalTokens`). For the terminal worker-feed card. */
+    totalTokens: number
     durationMs: number
     /** Dispatch-time task description, for the handback envelope. */
     description: string
@@ -615,6 +631,10 @@ export interface SubagentWatcherConfig {
     lastTool: { name: string; sanitisedArg: string } | null
     /** Tool-use count observed so far. */
     toolCount: number
+    /** Running TOTAL tokens across the worker's assistant messages so far
+     *  (`WorkerEntry.totalTokens`). Threaded onto the worker/nested card's
+     *  metrics line. 0 for a worker that has emitted no usage yet / ever. */
+    totalTokens: number
     /** Friendly display line for THIS tick. Set on `sub_agent_tool_use`
      *  events to a `describeToolUse` label ("Reading X", "Running a
      *  command") so a foreground sub-agent that runs tools without
@@ -1089,6 +1109,8 @@ export function readSubTail(
     lastTool: { name: string; sanitisedArg: string } | null
     /** Tool-use count observed so far. */
     toolCount: number
+    /** Running total tokens so far (see SubagentWatcherConfig.onProgress). */
+    totalTokens: number
     /** Friendly display line for THIS tick (set on tool ticks; see the
      *  SubagentWatcherConfig.onProgress doc). */
     progressLine?: string
@@ -1179,6 +1201,7 @@ export function readSubTail(
               },
               lastTool: entry.lastTool,
               toolCount: entry.toolCount,
+              totalTokens: entry.totalTokens,
               model: entry.currentModel,
               skeleton: true,
             })
@@ -1320,6 +1343,7 @@ export function readSubTail(
               },
               lastTool: entry.lastTool,
               toolCount: entry.toolCount,
+              totalTokens: entry.totalTokens,
               model: entry.currentModel,
             })
             return true
@@ -1502,6 +1526,22 @@ export function readSubTail(
           }
           continue
         }
+        if (ev.kind === 'sub_agent_usage') {
+          // Accumulate the worker's running total tokens, deduped by
+          // message.id: the ≥2.1.x split-message shape stamps the SAME `usage`
+          // block on every JSONL line of one logical assistant message, so
+          // counting each line would 2-3x over-count. A null messageId is
+          // un-dedupable (older/edge shapes) — count it as-is (its usage is
+          // real). No card render here; the total rides the next onProgress
+          // tick's payload like the model does.
+          if (ev.messageId == null) {
+            entry.totalTokens += ev.totalTokens
+          } else if (!entry.seenUsageMessageIds.has(ev.messageId)) {
+            entry.seenUsageMessageIds.add(ev.messageId)
+            entry.totalTokens += ev.totalTokens
+          }
+          continue
+        }
         if (ev.kind === 'sub_agent_tool_use') {
           // Narrative-dedup gate step 2: a sub_agent_text block was pending;
           // this tool is the lookahead that decides it (SHOW unless it drafts
@@ -1567,6 +1607,7 @@ export function readSubTail(
                   },
                   lastTool: entry.lastTool,
                   toolCount: entry.toolCount,
+                  totalTokens: entry.totalTokens,
                   progressLine: toolLine,
                   model: entry.currentModel,
                 })
@@ -1892,6 +1933,8 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       dispatchedAt: n,
       lastActivityAt: n,
       toolCount: 0,
+      totalTokens: 0,
+      seenUsageMessageIds: new Set<string>(),
       stallNotified: false,
       stalledAt: null,
       completionNotified: false,
@@ -2157,6 +2200,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             // registerAgent's short-circuit + Gap 1 promotion).
             outcome: entry.errored ? 'failed' : entry.historical ? 'orphan' : 'completed',
             toolCount: entry.toolCount,
+            totalTokens: entry.totalTokens,
             durationMs: nowFn() - entry.dispatchedAt,
             description: entry.description,
             // For a failure, fall back to the error detail when the worker
@@ -2184,6 +2228,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             state: entry.state,
             outcome: 'failed',
             toolCount: entry.toolCount,
+            totalTokens: entry.totalTokens,
             durationMs: nowFn() - entry.dispatchedAt,
             description: entry.description,
             resultText: entry.lastResultText,

package/telegram-plugin/tests/crash-redelivery-resume-exclusion.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest'
+import { decideRedeliverCapture } from '../gateway/redelivery-decision.js'
+import {
+  decideBootResumeKind,
+  RESUME_SYNTHETIC_PROMPT_PREFIX,
+} from '../gateway/resume-inbound-builder.js'
+import type { Turn, TurnEndedVia } from '../registry/turns-schema.js'
+
+/**
+ * Pins the MUTUAL EXCLUSION between crash-survival redelivery and the resume
+ * synthetic — the double-send guard. The gateway boot block composes exactly
+ * these two pure predicates: `decideBootResumeKind` classifies the interrupted
+ * turn, then `decideRedeliverCapture({ willBeResumed: kind === 'resume', ... })`
+ * decides whether to ALSO stage a redelivery.
+ *
+ * The load-bearing outcome: an interrupted turn that WILL be resumed (the model
+ * re-runs and emits a fresh answer) must NOT also redeliver its recovered draft
+ * — otherwise the same answer reaches the user twice. Conversely, a turn that
+ * will NOT be resumed (watchdog report, boot_resume:never suppression,
+ * resume-of-a-resume loop-guard) MUST redeliver, because nothing else re-answers.
+ *
+ * This mirrors the gateway wiring exactly, so it asserts the real composed
+ * outcome, not an isolated code path.
+ */
+
+const RESUME_MAX_AGE_MS = 10_800_000 // 3h, gateway default
+
+function makeTurn(over: Partial<Turn> = {}): Turn {
+  return {
+    turn_key: '900001:_#7',
+    chat_id: '900001',
+    thread_id: null,
+    started_at: Date.now() - 60_000, // 1 min ago — well within maxAge
+    ended_at: null,
+    ended_via: null,
+    last_assistant_msg_id: null,
+    last_assistant_done: null,
+    last_user_msg_id: null,
+    user_prompt_preview: 'deploy the staging stack',
+    assistant_reply_preview: null,
+    tool_call_count: 2,
+    interrupt_reason: null,
+    resumed_at: null,
+    session_id: 'sess-abcd', // durably pinned → redelivery is eligible on the floor
+    ...over,
+  } as Turn
+}
+
+/** Compose the two predicates exactly as the gateway boot block does. */
+function composeGate(turn: Turn, suppressed: boolean) {
+  const bootResumeKind = decideBootResumeKind({
+    pending: turn,
+    suppressed,
+    ageMs: Math.max(0, Date.now() - turn.started_at),
+    maxAgeMs: RESUME_MAX_AGE_MS,
+  })
+  const capture = decideRedeliverCapture({
+    willBeResumed: bootResumeKind === 'resume',
+    hasSessionId: Boolean(turn.session_id),
+  })
+  return { bootResumeKind, capture }
+}
+
+describe('crash-redelivery ↔ resume mutual exclusion (no double-send)', () => {
+  it('(a) an interrupted turn that WILL be resumed does NOT also redeliver', () => {
+    // ended_via 'restart' → decideBootResumeKind returns 'resume': the model
+    // re-runs and emits a fresh answer that supersedes any recovered draft.
+    const turn = makeTurn({ ended_via: 'restart' as TurnEndedVia })
+    const { bootResumeKind, capture } = composeGate(turn, /* suppressed */ false)
+    expect(bootResumeKind).toBe('resume')
+    expect(capture.capture).toBe(false)
+    expect(capture.skipReason).toBe('will-be-resumed')
+  })
+
+  it('(a2) a still-open (ended_via=null) killed-mid-flight turn is resumed, not redelivered', () => {
+    const turn = makeTurn({ ended_via: null })
+    const { bootResumeKind, capture } = composeGate(turn, false)
+    expect(bootResumeKind).toBe('resume')
+    expect(capture.capture).toBe(false)
+  })
+
+  it('(b) a watchdog-timeout turn (report, no auto re-answer) DOES redeliver', () => {
+    // ended_via 'timeout' → 'report': the synthetic only ASKS the user whether
+    // to retry — it does not auto-re-answer. Redelivery is the correct recovery.
+    const turn = makeTurn({ ended_via: 'timeout' as TurnEndedVia })
+    const { bootResumeKind, capture } = composeGate(turn, false)
+    expect(bootResumeKind).toBe('report')
+    expect(capture.capture).toBe(true)
+    expect(capture.skipReason).toBeUndefined()
+  })
+
+  it('(b2) a boot_resume:never-suppressed turn (defer-suppressed) DOES redeliver', () => {
+    // suppressed=true → 'defer-suppressed': no synthetic re-run, so redelivery
+    // is the ONLY recovery send.
+    const turn = makeTurn({ ended_via: 'restart' as TurnEndedVia })
+    const { bootResumeKind, capture } = composeGate(turn, /* suppressed */ true)
+    expect(bootResumeKind).toBe('defer-suppressed')
+    expect(capture.capture).toBe(true)
+  })
+
+  it('(b3) a resume-of-a-resume (loop-guard → defer-loop) turn DOES redeliver', () => {
+    // A turn whose prompt is itself a resume synthetic → 'defer-loop': the chain
+    // is capped, no re-run happens, so redelivery must still recover the answer.
+    const turn = makeTurn({
+      ended_via: 'restart' as TurnEndedVia,
+      user_prompt_preview: `${RESUME_SYNTHETIC_PROMPT_PREFIX} Continue the interrupted deploy.`,
+    })
+    const { bootResumeKind, capture } = composeGate(turn, false)
+    expect(bootResumeKind).toBe('defer-loop')
+    expect(capture.capture).toBe(true)
+  })
+
+  it('(b4) a STALE resume downgraded to report DOES redeliver (not suppressed)', () => {
+    // A 'restart' turn older than maxAge downgrades resume→report in
+    // selectResumeBuilder. Because the final kind is 'report' (no re-run),
+    // redelivery must fire — the gate keys on the FINAL kind, not the raw
+    // ended_via.
+    const turn = makeTurn({
+      ended_via: 'restart' as TurnEndedVia,
+      started_at: Date.now() - (RESUME_MAX_AGE_MS + 60_000),
+    })
+    const { bootResumeKind, capture } = composeGate(turn, false)
+    expect(bootResumeKind).toBe('report')
+    expect(capture.capture).toBe(true)
+  })
+
+  it('eligibility floor still applies: no session_id → no redelivery even when not resumed', () => {
+    const turn = makeTurn({ ended_via: 'timeout' as TurnEndedVia, session_id: null })
+    const { capture } = composeGate(turn, false)
+    expect(capture.capture).toBe(false)
+    expect(capture.skipReason).toBe('no-session-id')
+  })
+})