switchroom 0.12.18 → 0.12.20

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,9 @@ 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 { purgeStaleTurnsForChat } from './turn-state-purge.js'
+import { decideInboundDelivery } from './inbound-delivery-gate.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import {
   buildVaultGrantApprovedInbound,
@@ -1278,6 +1281,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');
@@ -1292,6 +1319,32 @@ function purgeReactionTracking(key: string): void {
   }
 }
 
+/**
+ * Atomic null-and-purge for a wedged turn. Every site that ends a
+ * turn by nulling `currentTurn` MUST also clear the turn's statusKey
+ * from `activeTurnStartedAt` — else a dangling entry survives and
+ * `#1556`'s turn-gate holds every new inbound mid-turn forever
+ * (gymbro / klanker held-mid-turn symptom, 2026-05-20).
+ *
+ * Pre-this, three turn-end paths (silent-marker / turn-flush /
+ * `turn_end`) nulled `currentTurn` on code-paths whose
+ * `purgeReactionTracking` calls weren't reached on every branch,
+ * leaving sibling entries under the turn's statusKey that the
+ * silence-poke framework-fallback's `purgeReactionTracking(fbKey)`
+ * couldn't catch (different key shape). The fallback now also sweeps
+ * siblings for `fbChatId` (`turn-state-purge.ts`) as defense-in-depth,
+ * but THIS helper closes the leak at origin: null and purge are
+ * inseparable at every call site.
+ *
+ * Idempotent: a second purge is a no-op `.delete()` on a key already
+ * gone — handlers that already purge elsewhere are unharmed.
+ */
+function endCurrentTurnAtomic(turn: CurrentTurn): void {
+  if (currentTurn !== turn) return
+  currentTurn = null
+  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId))
+}
+
 /**
  * Model-idle proactive-compaction check. Called ONLY from the
  * activeTurnStartedAt.size === 0 gate above (never mid-turn). Opt-in via
@@ -2985,6 +3038,23 @@ silencePoke.startTimer({
     // for this chat starts a fresh turn instead of queueing forever.
     silencePoke.endTurn(fbKey)
     purgeReactionTracking(fbKey)
+    // Defense-in-depth: the fallback's purgeReactionTracking above
+    // clears the canonical statusKey(chatId, threadId) for fbKey
+    // only. activeTurnStartedAt can hold sibling entries for the
+    // SAME chat (different threads, or a `null` vs `undefined`-thread
+    // variant left over from a normal turn-end path that nulled
+    // currentTurn without invoking purgeReactionTracking — the
+    // gymbro/klanker held-mid-turn symptom, 2026-05-20). Any sibling
+    // for fbChatId is by definition stale when THIS fallback fires
+    // (the chat has been silent ≥5 min); sweep them via the same
+    // purger. Multi-chat-safe — only touches keys for fbChatId, so
+    // #1546's intentional cross-chat safety guard is preserved.
+    // See turn-state-purge.ts.
+    const fbExtraPurge = purgeStaleTurnsForChat(
+      fbChatId,
+      activeTurnStartedAt.keys(),
+      purgeReactionTracking,
+    )
     // Null `currentTurn` if it's still pointing at the wedged turn —
     // when claude eventually fires a late `turn_end` for this session
     // (or never does), the handler's `const turn = currentTurn` snapshot
@@ -3011,13 +3081,15 @@ silencePoke.startTimer({
       pendingInboundBuffer,
       fbSelfAgent,
       (m) => ipcServer.sendToAgent(fbSelfAgent, m),
+      inboundSpool,
     )
     process.stderr.write(
       `telegram gateway: silence-poke framework-fallback ended wedged turn ` +
       `chat=${fbChatId} thread=${ctx.threadId ?? '-'} silence_ms=${ctx.silenceMs} ` +
       `currentTurn_nulled=${turnMatchesFallback} ` +
       `drained_buffered=${fbRedeliver.redelivered}/${fbRedeliver.drained}` +
-      `${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ''}\n`,
+      `${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ''}` +
+      `${fbExtraPurge.purged.length > 0 ? ` extra_keys_purged=${fbExtraPurge.purged.length}` : ''}\n`,
     )
   },
 })
@@ -3029,7 +3101,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 +3187,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 +3655,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 +3674,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 +3690,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()
 }
 
@@ -5587,7 +5731,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           turn.answerStream = null
         }
         // Null the atom — this turn is being abandoned.
-        if (currentTurn === turn) currentTurn = null
+        endCurrentTurnAtomic(turn)
         // #549 fix — context-exhaustion teardown also resets preamble state.
         preambleSuppressor.reset()
       }
@@ -5785,7 +5929,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         // returns early at handler entry. A new `enqueue` swaps in a
         // fresh atom; the silent-turn teardown doesn't need to preserve
         // any of the prior turn's state.
-        if (currentTurn === turn) currentTurn = null
+        endCurrentTurnAtomic(turn)
         // #549 fix — silent-marker teardown drops any pending preamble.
         preambleSuppressor.dropNow()
         return
@@ -5819,7 +5963,7 @@ 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.
-        if (currentTurn === turn) currentTurn = null
+        endCurrentTurnAtomic(turn)
         // #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).
@@ -6091,7 +6235,7 @@ function handleSessionEvent(ev: SessionEvent): void {
       // #1067: null the atom in one assignment, replacing the seven
       // field clears the pre-refactor version did. Any late-arriving
       // event for this turn will see currentTurn == null and bail.
-      if (currentTurn === turn) currentTurn = null
+      endCurrentTurnAtomic(turn)
       // #549 fix — preamble flush already happened at the TOP of this
       // turn_end handler (before turn.answerStream is nulled). See
       // comment near line 3431.
@@ -7377,6 +7521,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
+    },
+  }
+}