switchroom 0.12.18 → 0.12.19

package/telegram-plugin/gateway/gateway.ts

@@ -17,7 +17,7 @@ import { execFileSync, execSync, spawn } from 'child_process'
 import {
   readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync,
   statSync, renameSync, realpathSync, chmodSync, openSync, closeSync,
-  existsSync, unlinkSync,
+  existsSync, unlinkSync, appendFileSync,
 } from 'fs'
 import { homedir } from 'os'
 import { join, extname, sep, basename } from 'path'
@@ -249,6 +249,8 @@ import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js
 import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
+import { createInboundSpool } from './inbound-spool.js'
+import { decideInboundDelivery } from './inbound-delivery-gate.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import {
   buildVaultGrantApprovedInbound,
@@ -1278,6 +1280,30 @@ function purgeReactionTracking(key: string): void {
   // response to the client was already sent when the restart was
   // scheduled, so nobody is waiting on this.
   if (activeTurnStartedAt.size === 0) {
+    // #1556: the deterministic delivery point. claude has just gone
+    // idle — flush any inbound held mid-turn so the channel
+    // notification lands at the idle prompt and submits as a fresh
+    // turn (instead of stranding in the composer, the lawgpt wedge).
+    // Zero-churn: depth check first, no work on the common empty path.
+    // Lossless: redeliver re-buffers any per-message miss (bridge
+    // mid-reconnect), which onClientRegistered then drains.
+    const selfAgentForFlush = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    if (pendingInboundBuffer.depth(selfAgentForFlush) > 0) {
+      const fr = redeliverBufferedInbound(
+        pendingInboundBuffer,
+        selfAgentForFlush,
+        (m) => ipcServer.sendToAgent(selfAgentForFlush, m),
+        inboundSpool,
+      )
+      if (fr.redelivered > 0) {
+        process.stderr.write(
+          `telegram gateway: turn-complete flushed ${fr.redelivered}/${fr.drained} ` +
+          `held inbound for ${selfAgentForFlush}` +
+          `${fr.rebuffered > 0 ? ` (${fr.rebuffered} re-buffered)` : ''}\n`,
+        )
+      }
+    }
+
     if (pendingRestarts.size > 0) {
       for (const [agentName, _timestamp] of pendingRestarts.entries()) {
         triggerSelfRestart(agentName, 'turn-complete-pending-restart');
@@ -3011,6 +3037,7 @@ silencePoke.startTimer({
       pendingInboundBuffer,
       fbSelfAgent,
       (m) => ipcServer.sendToAgent(fbSelfAgent, m),
+      inboundSpool,
     )
     process.stderr.write(
       `telegram gateway: silence-poke framework-fallback ended wedged turn ` +
@@ -3029,7 +3056,42 @@ silencePoke.startTimer({
 // vault_request_access card during the 100ms bridge-reconnect window
 // would mint the grant but silently drop the `vault_grant_approved`
 // inbound, leaving the agent stuck waiting for a manual poke.
-const pendingInboundBuffer = createPendingInboundBuffer()
+// Durable inbound spool on the persistent per-agent volume
+// (STATE_DIR = /state/agent/telegram in prod — survives container
+// recreate). Makes the "⏳ your message is queued and will be
+// processed when it reconnects" promise deterministic across a
+// gateway/container restart (finn/carrie lost-on-restart incident,
+// 2026-05-19). STATIC mode has no runtime/bridge, so no spool.
+const inboundSpool = STATIC
+  ? undefined
+  : createInboundSpool({
+      path: join(STATE_DIR, 'inbound-spool.jsonl'),
+      fs: {
+        appendFileSync: (p, d) => appendFileSync(p, d),
+        readFileSync: (p) => readFileSync(p, 'utf8'),
+        writeFileSync: (p, d) => writeFileSync(p, d),
+        renameSync: (a, b) => renameSync(a, b),
+        existsSync: (p) => existsSync(p),
+        statSizeSync: (p) => statSync(p).size,
+      },
+    })
+const pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool })
+// Boot-replay: re-queue every un-acked spooled inbound into the
+// in-memory buffer so the existing drain triggers (onClientRegistered
+// / silence-poke #1546 / idle-drain #1549) deliver them. push →
+// spool.put dedups on the already-live id, so this re-push does NOT
+// double-append. This is what makes a queued message survive a
+// restart instead of being silently lost.
+if (inboundSpool != null) {
+  const replay = inboundSpool.liveEntries()
+  for (const e of replay) pendingInboundBuffer.push(e.agent, e.msg)
+  if (replay.length > 0) {
+    process.stderr.write(
+      `telegram gateway: inbound-spool boot-replay re-queued ${replay.length} ` +
+      `un-acked inbound (durable-queue, survives restart)\n`,
+    )
+  }
+}
 const pendingPermissionBuffer = createPendingPermissionBuffer()
 
 /**
@@ -3080,6 +3142,12 @@ const ipcServer: IpcServer = createIpcServer({
       for (const msg of pending) {
         try {
           client.send(msg)
+          // Confirmed delivery to the just-registered live bridge →
+          // tombstone the durable spool entry so it isn't boot-replayed
+          // again. A throw below leaves it spooled (un-acked) so the
+          // idle-drain / escalation path still recovers it — strictly
+          // safer than the old log-and-drop.
+          inboundSpool?.ack(msg)
         } catch (err) {
           process.stderr.write(
             `telegram gateway: pending-inbound drain failed agent=${client.agentName} ` +
@@ -3542,12 +3610,17 @@ const ipcServer: IpcServer = createIpcServer({
 //
 // This is the third drain trigger. It's gated to be zero-cost and
 // zero-churn: skip entirely when nothing is buffered (one Map.get, no
-// log) or when the bridge isn't alive (exactly sendToAgent's own
-// guard — so we never drain into a dead bridge and re-buffer/log-spin).
-// Only when there IS a buffered message AND a live bridge do we reuse
-// the #1546 `redeliverBufferedInbound` (lossless: re-buffers any
-// per-message miss). A message delivered while a turn is active is
-// queued normally by the bridge — same as a live arrival, not lost.
+// log), when the bridge isn't alive (exactly sendToAgent's own guard —
+// so we never drain into a dead bridge and re-buffer/log-spin), OR
+// when a turn is in flight. The turn gate is #1556: a message
+// delivered while a turn is active is NOT safely queued by the bridge
+// — claude types it into its TUI composer and the auto-submit races
+// turn-completion, stranding it (the lawgpt wedge). Draining only at
+// `activeTurnStartedAt.size === 0` guarantees the channel notification
+// lands at an idle prompt and submits as a fresh turn. Only when there
+// IS a buffered message AND a live bridge AND no active turn do we
+// reuse the #1546 `redeliverBufferedInbound` (lossless: re-buffers any
+// per-message miss).
 const IDLE_DRAIN_INTERVAL_MS = 5000
 if (!STATIC) {
   setInterval(() => {
@@ -3556,10 +3629,14 @@ if (!STATIC) {
       pendingInboundBuffer,
       selfAgent,
       () => {
+        // #1556: never drain mid-turn — that re-creates the composer
+        // wedge this buffer exists to prevent.
+        if (activeTurnStartedAt.size > 0) return false
         const c = ipcServer.getClient(selfAgent)
         return c != null && c.isAlive()
       },
       (m) => ipcServer.sendToAgent(selfAgent, m),
+      inboundSpool,
     )
     if (r != null && r.redelivered > 0) {
       process.stderr.write(
@@ -3568,6 +3645,28 @@ if (!STATIC) {
         `${r.rebuffered > 0 ? ` (${r.rebuffered} re-buffered)` : ''}\n`,
       )
     }
+    // Bounded escalation: a spooled inbound still un-acked past its
+    // bound (default 15 min — well past the 5-min silence-poke ladder)
+    // is undeliverable in practice. Retract the "will be processed"
+    // promise EXPLICITLY (honest failure) instead of letting it sit
+    // forever. This is what makes the guarantee deterministic: every
+    // queued message ends either delivered or visibly retracted.
+    inboundSpool?.sweepEscalations((e) => {
+      const chat = e.msg.chatId
+      const threadOpts =
+        typeof e.msg.meta?.threadId === 'string' && e.msg.meta.threadId
+          ? { message_thread_id: Number(e.msg.meta.threadId) }
+          : {}
+      void swallowingApiCall(
+        () =>
+          bot.api.sendMessage(
+            chat,
+            "⚠️ I couldn't deliver an earlier message to the agent after repeated retries (it survived restarts but the agent never picked it up). Please resend it.",
+            { ...threadOpts },
+          ),
+        { chat_id: chat, verb: 'inbound-spool-escalation' },
+      )
+    })
   }, IDLE_DRAIN_INTERVAL_MS).unref()
 }
 
@@ -7377,6 +7476,29 @@ async function handleInbound(
   // push to pendingInboundBuffer, which onClientRegistered drains on
   // the next bridge register — so the notice below is now truthful.
   const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+
+  // #1556: turn-gated delivery. A non-steering inbound that arrives
+  // mid-turn must NOT be sent to the bridge now — claude would type it
+  // into its TUI composer and the auto-submit races turn-completion,
+  // stranding the message (the lawgpt wedge, 2026-05-19). Buffer it;
+  // `purgeReactionTracking`'s turn-complete hook and the turn-gated
+  // idle-drain flush it the instant claude goes idle, where the channel
+  // notification submits cleanly as a fresh turn. Steering messages are
+  // exempt — reaching claude mid-turn is the whole point of /steer.
+  if (
+    decideInboundDelivery({
+      turnInFlight: activeTurnStartedAt.size > 0,
+      isSteering,
+    }) === 'buffer-until-idle'
+  ) {
+    pendingInboundBuffer.push(selfAgent, inboundMsg)
+    process.stderr.write(
+      `telegram gateway: inbound held mid-turn agent=${selfAgent} ` +
+      `chat=${chat_id} msg=${msgId ?? '-'} — will flush on turn-complete\n`,
+    )
+    return
+  }
+
   const delivered = ipcServer.sendToAgent(selfAgent, inboundMsg)
   if (!delivered) {
     pendingInboundBuffer.push(selfAgent, inboundMsg)

package/telegram-plugin/gateway/inbound-delivery-gate.ts

@@ -0,0 +1,85 @@
+/**
+ * Inbound delivery gate (#1556 — the lawgpt composer-wedge).
+ *
+ * Pure decision: given the live turn state, should a freshly-received
+ * Telegram inbound be delivered to the bridge *now*, or held in the
+ * pending-inbound buffer until claude is idle?
+ *
+ * ## Why this exists
+ *
+ * The gateway used to `ipcServer.sendToAgent(inbound)` unconditionally,
+ * buffering ONLY when the bridge was offline. The load-bearing (and
+ * false) assumption — stated verbatim in three places before this fix
+ * (`pending-inbound-buffer.ts`, the idle-drain comment, and the
+ * implicit unconditional send) — was:
+ *
+ *   "a message delivered while a turn is active is queued normally by
+ *    the bridge, same as a live arrival, not lost."
+ *
+ * It is not. The bridge converts an inbound into an MCP
+ * `notifications/claude/channel` notification (`bridge.ts:onInbound`).
+ * When claude receives that notification mid-turn, the unmodified CLI
+ * types the text into its TUI composer and relies on an auto-submit
+ * once the turn ends. That submit races turn-completion and frequently
+ * does not fire — the message strands in the composer, claude sits at
+ * an idle prompt with the user's instruction un-actioned, and nothing
+ * self-heals it (the turn-active watchdog only catches *in-turn* hangs;
+ * this is *between-turns*-with-undelivered-input, which reads as
+ * healthy idle). Observed live: agent `lawgpt`, 2026-05-19 — a
+ * follow-up message sat unsubmitted indefinitely; only a restart
+ * cleared it, and the restart *lost* the message.
+ *
+ * ## The deterministic guarantee
+ *
+ * A non-steering inbound on the Telegram `handleInbound` path is
+ * delivered to the bridge ONLY when no turn is in flight. The channel
+ * notification therefore always lands at an idle claude prompt, where
+ * it submits cleanly as a fresh turn. It can be *delayed* (until the
+ * current turn completes) but can never strand in the composer. The
+ * turn-complete hook (`purgeReactionTracking`) and the turn-gated
+ * idle-drain timer flush the buffer the instant
+ * `activeTurnStartedAt.size === 0`.
+ *
+ * Scope: this gates the Telegram `handleInbound` path only — the one
+ * the lawgpt wedge hit. The `inject_inbound` IPC path (cron / synthetic
+ * operator wakeups) reaches the bridge directly and is deliberately
+ * NOT gated here: cron fires carry at-least-once replay semantics and
+ * their delivery contract is a separate product decision, out of scope
+ * for this bug.
+ *
+ * ## Steering is deliberately exempt
+ *
+ * An explicit `/steer` (`/s`) message is *meant* to reach claude
+ * mid-turn — that is the whole point of the steering feature (redirect
+ * the agent while it works). Steering messages keep immediate delivery.
+ * The wedge only ever affected the queued-mid-turn default path.
+ */
+
+export interface InboundDeliveryGateInput {
+  /** A turn is in flight RIGHT NOW (live: `activeTurnStartedAt.size > 0`),
+   *  evaluated at delivery time — not a receipt-time snapshot, so a turn
+   *  that completed between receipt and here correctly reads as idle. */
+  turnInFlight: boolean
+  /** This inbound carried an explicit `/steer` (`/s`) prefix and is an
+   *  intentional mid-turn redirect. */
+  isSteering: boolean
+}
+
+export type InboundDeliveryDecision =
+  /** Send to the bridge now (idle prompt, or an intentional steer). */
+  | 'deliver'
+  /** Hold in the pending-inbound buffer; the turn-complete hook /
+   *  turn-gated idle-drain flushes it when claude goes idle. */
+  | 'buffer-until-idle'
+
+/**
+ * Pure. The ONLY condition that defers delivery is "a turn is in flight
+ * AND this is not a steering message". Everything else delivers
+ * immediately (idle → submits at once; steering → intentional mid-turn).
+ */
+export function decideInboundDelivery(
+  input: InboundDeliveryGateInput,
+): InboundDeliveryDecision {
+  if (input.turnInFlight && !input.isSteering) return 'buffer-until-idle'
+  return 'deliver'
+}

package/telegram-plugin/gateway/inbound-spool.ts

@@ -0,0 +1,272 @@
+/**
+ * inbound-spool.ts — durable, crash-tolerant spool for buffered inbound.
+ *
+ * Why this exists: `pending-inbound-buffer.ts` is in-memory only. A
+ * gateway/container restart (switchroom update, agent restart, a
+ * self-restart, an OOM) destroys it — so the user-facing promise
+ * "⏳ your message is queued and will be processed when it reconnects"
+ * (gateway.ts) is a lie across a restart. Proven twice: finn and
+ * carrie (2026-05-19) lost the user's message on restart and the user
+ * had to resend. #1546/#1549 only shrank the in-memory delivery
+ * window; they cannot survive process death.
+ *
+ * This module makes the promise DETERMINISTIC: every buffered inbound
+ * is also appended to a JSONL spool on the persistent per-agent volume
+ * (`/state/agent/telegram/…`, survives container recreate). On boot the
+ * gateway replays un-acked entries back into the in-memory buffer, so
+ * the existing drain machinery delivers them. An entry is acked (and
+ * tombstoned) ONLY on confirmed delivery to a live registered bridge.
+ * Un-acked entries older than `escalateAfterMs` are surfaced to the
+ * user via an explicit "couldn't deliver — resend?" callback and then
+ * dropped: the promise is then ALWAYS resolved — kept, or visibly
+ * retracted — never silently lost.
+ *
+ * Scope (v1): the ack is "delivered to a live registered bridge", not
+ * "claude consumed it". A true claude→gateway consumption-ack needs a
+ * new bidirectional bridge protocol (high blast radius) and is a
+ * documented follow-up. v1 already eliminates the silent-loss-on-
+ * restart class — the actual incident class.
+ *
+ * Crash-consistency: append-only JSONL, one self-contained JSON object
+ * per line, written with a trailing newline in a single `appendFileSync`
+ * (atomic for small writes on local fs). A torn final line on a crash
+ * mid-write is tolerated: replay skips any line that does not
+ * round-trip `JSON.parse` + shape-check. Acks are themselves appended
+ * as tombstone lines (`{t:"ack",id}`) rather than rewriting the file;
+ * a bounded `compact()` rewrites the file dropping acked/escalated ids
+ * when it grows past `compactAtBytes`.
+ *
+ * This module is PURE w.r.t. its injected fs + clock seams so the
+ * crash/dedup/replay/escalation logic is unit-tested without a real
+ * gateway (mirrors the #1544/#1546/#1549 pure-seam idiom).
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+/** Stable dedup id for an inbound. Real Telegram messages have a
+ *  unique (chatId, messageId). Synthetic/cron inbounds use messageId
+ *  0 — fall back to a deterministic id from source+ts so retried
+ *  synthetics of the SAME logical event dedup, but distinct events
+ *  (different ts) do not collapse. */
+export function spoolId(msg: InboundMessage): string {
+  if (typeof msg.messageId === 'number' && msg.messageId > 0) {
+    return `m:${msg.chatId}:${msg.messageId}`
+  }
+  const src = msg.meta?.source ?? '-'
+  return `s:${msg.chatId}:${src}:${msg.ts}`
+}
+
+interface SpoolRecord {
+  t: 'put' | 'ack'
+  id: string
+  /** Present only on `put`. The full inbound to replay. */
+  msg?: InboundMessage
+  /** Present only on `put`. Owning agent (replay re-pushes per agent). */
+  agent?: string
+  /** Present only on `put`. ms epoch first-spooled — drives escalation. */
+  firstAt?: number
+}
+
+export interface InboundSpoolFsSeam {
+  appendFileSync: (path: string, data: string) => void
+  readFileSync: (path: string) => string
+  writeFileSync: (path: string, data: string) => void
+  /** Atomic same-dir replace (POSIX rename). Used so compaction can't
+   *  lose entries to a crash mid-rewrite. */
+  renameSync: (from: string, to: string) => void
+  existsSync: (path: string) => boolean
+  statSizeSync: (path: string) => number
+}
+
+export interface InboundSpoolOptions {
+  path: string
+  fs: InboundSpoolFsSeam
+  now?: () => number
+  log?: (line: string) => void
+  /** Un-acked entries older than this are escalated then dropped.
+   *  Default 15 min — comfortably past the 5-min silence-poke ladder
+   *  so self-heal gets every chance before we retract the promise. */
+  escalateAfterMs?: number
+  /** Rewrite-compact the JSONL once it exceeds this. Default 256 KiB. */
+  compactAtBytes?: number
+}
+
+export interface ReplayEntry {
+  agent: string
+  msg: InboundMessage
+}
+
+export interface InboundSpool {
+  /** Durably record `msg` for `agent`. Idempotent by spoolId: a
+   *  re-spool of an already-live id is a no-op (returns false). */
+  put: (agent: string, msg: InboundMessage) => boolean
+  /** Tombstone `id` — call ONLY on confirmed delivery to a live
+   *  registered bridge. Idempotent. */
+  ack: (msg: InboundMessage) => void
+  /** Live (un-acked) entries, oldest first. Used at boot to re-push
+   *  into the in-memory buffer. Pure read — does not mutate. */
+  liveEntries: () => ReplayEntry[]
+  /** Escalate+drop entries older than `escalateAfterMs`. Calls
+   *  `onEscalate` once per dropped entry (post the "couldn't deliver"
+   *  card there). Returns the count escalated. Safe to call on a timer. */
+  sweepEscalations: (onEscalate: (e: ReplayEntry) => void) => number
+  /** Test/observability: count of live (un-acked) ids. */
+  liveCount: () => number
+}
+
+export function createInboundSpool(opts: InboundSpoolOptions): InboundSpool {
+  const { path, fs } = opts
+  const now = opts.now ?? Date.now
+  const log = opts.log ?? ((l: string) => process.stderr.write(l))
+  const escalateAfterMs = opts.escalateAfterMs ?? 15 * 60 * 1000
+  const compactAtBytes = opts.compactAtBytes ?? 256 * 1024
+
+  // In-memory projection of the on-disk log, rebuilt from the file at
+  // construction. `live` maps spoolId → the put record (insertion order
+  // preserved via the Map). An `ack` deletes from `live`.
+  const live = new Map<string, { agent: string; msg: InboundMessage; firstAt: number }>()
+
+  function parseLine(line: string): SpoolRecord | null {
+    const s = line.trim()
+    if (!s) return null
+    let rec: unknown
+    try {
+      rec = JSON.parse(s)
+    } catch {
+      return null // torn / partial line from a crash mid-append — skip
+    }
+    if (rec == null || typeof rec !== 'object') return null
+    const r = rec as Record<string, unknown>
+    if (r.t !== 'put' && r.t !== 'ack') return null
+    if (typeof r.id !== 'string' || r.id.length === 0) return null
+    if (r.t === 'put') {
+      if (r.msg == null || typeof r.msg !== 'object') return null
+      if (typeof r.agent !== 'string' || r.agent.length === 0) return null
+      if (typeof r.firstAt !== 'number') return null
+    }
+    return r as unknown as SpoolRecord
+  }
+
+  // Rebuild `live` from the file. Tolerates a torn last line.
+  function hydrate(): void {
+    live.clear()
+    if (!fs.existsSync(path)) return
+    let raw = ''
+    try {
+      raw = fs.readFileSync(path)
+    } catch {
+      return
+    }
+    for (const line of raw.split('\n')) {
+      const rec = parseLine(line)
+      if (rec == null) continue
+      if (rec.t === 'put') {
+        // Last put for an id wins; an ack later removes it.
+        live.set(rec.id, {
+          agent: rec.agent as string,
+          msg: rec.msg as InboundMessage,
+          firstAt: rec.firstAt as number,
+        })
+      } else {
+        live.delete(rec.id)
+      }
+    }
+  }
+
+  function appendRecord(rec: SpoolRecord): void {
+    try {
+      fs.appendFileSync(path, JSON.stringify(rec) + '\n')
+    } catch (err) {
+      // Durability is best-effort relative to fs availability; a spool
+      // write failure must NOT break live delivery. Log loudly — a
+      // persistently failing spool means we're back to in-memory-only
+      // semantics and the operator should know.
+      log(
+        `inbound-spool: append FAILED path=${path} id=${rec.id} t=${rec.t}: ` +
+        `${(err as Error).message} — durability degraded to in-memory\n`,
+      )
+    }
+  }
+
+  function maybeCompact(): void {
+    let size = 0
+    try {
+      size = fs.existsSync(path) ? fs.statSizeSync(path) : 0
+    } catch {
+      return
+    }
+    if (size <= compactAtBytes) return
+    // Rewrite the file as exactly the current live set (one put per
+    // live id, no acks). ATOMIC: write a sibling tmp then rename over
+    // the real path. rename(2) is atomic within a filesystem, so a
+    // crash at any point leaves EITHER the full pre-compaction log OR
+    // the full compacted log on disk — never a truncated/torn file
+    // that loses live entries after the tear. (Plain writeFileSync is
+    // not atomic; a crash mid-write of a >256 KiB rewrite could drop
+    // entries past the tear — the residual the reviewer flagged.)
+    const lines: string[] = []
+    for (const [id, e] of live) {
+      lines.push(
+        JSON.stringify({ t: 'put', id, agent: e.agent, msg: e.msg, firstAt: e.firstAt } satisfies SpoolRecord),
+      )
+    }
+    const tmp = path + '.compact.tmp'
+    try {
+      fs.writeFileSync(tmp, lines.length ? lines.join('\n') + '\n' : '')
+      fs.renameSync(tmp, path)
+      log(`inbound-spool: compacted path=${path} live=${live.size}\n`)
+    } catch (err) {
+      // Compaction is opportunistic — a failure keeps the (larger but
+      // correct) append-only log; never lose data trying to shrink it.
+      log(`inbound-spool: compact FAILED path=${path}: ${(err as Error).message}\n`)
+    }
+  }
+
+  hydrate()
+
+  return {
+    put(agent, msg) {
+      const id = spoolId(msg)
+      if (live.has(id)) return false // dedup: already spooled & un-acked
+      const firstAt = now()
+      live.set(id, { agent, msg, firstAt })
+      appendRecord({ t: 'put', id, agent, msg, firstAt })
+      maybeCompact()
+      return true
+    },
+    ack(msg) {
+      const id = spoolId(msg)
+      if (!live.has(id)) return // idempotent / unknown id
+      live.delete(id)
+      appendRecord({ t: 'ack', id })
+      maybeCompact()
+    },
+    liveEntries() {
+      // Insertion order = Map iteration order = oldest first.
+      return [...live.values()].map((e) => ({ agent: e.agent, msg: e.msg }))
+    },
+    sweepEscalations(onEscalate) {
+      const cutoff = now() - escalateAfterMs
+      let n = 0
+      for (const [id, e] of [...live.entries()]) {
+        if (e.firstAt > cutoff) continue
+        live.delete(id)
+        appendRecord({ t: 'ack', id }) // tombstone — promise retracted
+        try {
+          onEscalate({ agent: e.agent, msg: e.msg })
+        } catch (err) {
+          log(`inbound-spool: onEscalate threw id=${id}: ${(err as Error).message}\n`)
+        }
+        n++
+      }
+      if (n > 0) {
+        log(`inbound-spool: escalated+dropped ${n} undelivered entr${n === 1 ? 'y' : 'ies'} (older than ${escalateAfterMs}ms)\n`)
+        maybeCompact()
+      }
+      return n
+    },
+    liveCount() {
+      return live.size
+    },
+  }
+}

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -30,6 +30,7 @@
  */
 
 import type { InboundMessage } from './ipc-protocol.js'
+import type { InboundSpool } from './inbound-spool.js'
 
 /** Default cap per agent. Tuned for `should fit a reasonable backlog of
  *  approval cards stacked while bridge is offline` but no more. */
@@ -52,6 +53,19 @@ export interface PendingInboundBuffer {
 export interface PendingInboundBufferOptions {
   capPerAgent?: number
   log?: (line: string) => void
+  /**
+   * Durable spool. When set, every `push` is also recorded on the
+   * persistent per-agent volume so a gateway/container restart cannot
+   * silently lose the message (the finn/carrie incident class). The
+   * in-memory queue stays the hot path + cap; the spool is the
+   * crash-survivable record, acked only on confirmed delivery (by
+   * `redeliverBufferedInbound`/`idleDrainTick`), boot-replayed by the
+   * gateway, and escalated-then-dropped if undeliverable past its
+   * bound. The in-memory cap eviction does NOT touch the spool — an
+   * evicted-from-memory entry survives in the spool (strictly safer
+   * than the old silent in-memory drop).
+   */
+  spool?: InboundSpool
 }
 
 /**
@@ -72,6 +86,7 @@ export function redeliverBufferedInbound(
   buffer: PendingInboundBuffer,
   agent: string,
   send: (msg: InboundMessage) => boolean,
+  spool?: InboundSpool,
 ): { drained: number; redelivered: number; rebuffered: number } {
   const pending = buffer.drain(agent)
   let redelivered = 0
@@ -85,6 +100,11 @@ export function redeliverBufferedInbound(
     }
     if (delivered) {
       redelivered++
+      // Confirmed delivery to a live registered bridge → the durable
+      // promise is kept; tombstone the spool entry so it is NOT
+      // boot-replayed again. A miss leaves it spooled (re-pushed below
+      // AND still live in the spool) for the next drain / escalation.
+      spool?.ack(msg)
     } else {
       buffer.push(agent, msg)
       rebuffered++
@@ -107,8 +127,19 @@ export function redeliverBufferedInbound(
  *     which would re-buffer+log-spin every tick; onClientRegistered
  *     will drain on the eventual reconnect instead)
  *   - otherwise → `redeliverBufferedInbound` (lossless: re-buffers any
- *     per-message miss). A message delivered mid-turn is queued
- *     normally by the bridge, same as a live arrival — not lost.
+ *     per-message miss).
+ *
+ * NOTE (#1556): a message delivered mid-turn is NOT safely queued by
+ * the bridge — the prior "queued normally, same as a live arrival"
+ * claim here was the false assumption behind the lawgpt composer
+ * wedge. claude types a mid-turn channel notification into its TUI
+ * composer and the auto-submit races turn-completion, stranding it.
+ * The `idleDrainTick` caller therefore also gates on
+ * `activeTurnStartedAt.size === 0`, so this function is never invoked
+ * mid-turn. The Telegram `handleInbound` delivery path is turn-gated
+ * (gateway.ts); the `inject_inbound` cron/synthetic path is a separate
+ * delivery contract and deliberately not gated — see
+ * `inbound-delivery-gate.ts`.
  *
  * Returns the redeliver counts only when it actually ran, else null
  * (so the caller logs only on a real flush).
@@ -118,11 +149,12 @@ export function idleDrainTick(
   agent: string,
   isBridgeAlive: () => boolean,
   send: (msg: InboundMessage) => boolean,
+  spool?: InboundSpool,
 ): { drained: number; redelivered: number; rebuffered: number } | null {
   if (!agent) return null
   if (buffer.depth(agent) === 0) return null
   if (!isBridgeAlive()) return null
-  return redeliverBufferedInbound(buffer, agent, send)
+  return redeliverBufferedInbound(buffer, agent, send, spool)
 }
 
 export function createPendingInboundBuffer(
@@ -130,6 +162,7 @@ export function createPendingInboundBuffer(
 ): PendingInboundBuffer {
   const cap = opts.capPerAgent ?? DEFAULT_PENDING_INBOUND_CAP
   const log = opts.log ?? ((line: string) => process.stderr.write(line))
+  const spool = opts.spool
   const queues = new Map<string, InboundMessage[]>()
 
   return {
@@ -149,6 +182,12 @@ export function createPendingInboundBuffer(
         )
       }
       q.push(msg)
+      // Durable record FIRST-class to the in-memory queue: spool BEFORE
+      // returning, regardless of the cap eviction above — an entry the
+      // in-memory cap drops still survives in the spool (boot-replayed /
+      // escalated), which is the whole point. spool.put dedups by
+      // spoolId so a boot-replay re-push is a no-op here.
+      spool?.put(agent, msg)
       log(
         `pending-inbound-buffer: agent=${agent} buffered source=${msg.meta?.source ?? '-'} ` +
         `depth_after=${q.length} evicted=${evicted}\n`,