switchroom 0.12.17 → 0.12.19

package/telegram-plugin/gateway/compact-notify.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure transition selector for the proactive-compaction user
+ * notification (a single Telegram card edited START → FINISH). Kept
+ * side-effect-free so the lifecycle — the part prone to double-post /
+ * stale-edit / spurious-finish — is unit-testable in isolation. The
+ * impure shell (send/editMessageText, the wall-clock timeout) lives in
+ * gateway.ts.
+ *
+ * The "finished" signal is the proactive-compaction state machine's
+ * re-arm edge (`armed: false → true`, which the decider only produces
+ * when post-`/compact` occupancy drops below 0.6×cap — i.e. context
+ * verifiably shrank). This module does NOT own the wall-clock timeout
+ * (an idle agent produces no evaluations, so a dangling card must be
+ * resolved by a real timer in the shell, independent of this loop).
+ *
+ * Session reset/rotation (`session.max_idle` / `max_turns`) is
+ * deliberately silent and is not represented here.
+ */
+
+export interface CompactNotifyState {
+  phase: "idle" | "awaiting";
+  /**
+   * The active session file when START was posted. FINISH is only
+   * accepted if the re-arm edge is observed against this SAME file —
+   * a sub-agent transcript briefly leading session-tail's currentFile
+   * can read a small occupancy and spuriously satisfy the re-arm
+   * condition; gating on the start-file rejects that false positive.
+   */
+  fileAtStart: string | null;
+}
+
+/**
+ * - `none`              — no card action this evaluation.
+ * - `start`             — post a fresh START card.
+ * - `start-superseding` — a prior card is still outstanding; mark it
+ *                         superseded, then post a fresh START card.
+ * - `finish`            — edit the outstanding card to FINISHED.
+ */
+export type CompactNotifyAction =
+  | "none"
+  | "start"
+  | "start-superseding"
+  | "finish";
+
+export interface CompactNotifyEvent {
+  /** The proactive-compaction decider fired `/compact` this eval. */
+  fired: boolean;
+  /** Decider re-arm edge this eval (wasArmed=false → state.armed=true). */
+  rearmed: boolean;
+  /** session-tail's active file used for the occupancy read this eval. */
+  activeFile: string | null;
+}
+
+export function idleCompactNotifyState(): CompactNotifyState {
+  return { phase: "idle", fileAtStart: null };
+}
+
+/**
+ * Select the card action for this idle evaluation and the next state.
+ * Pure: same inputs → same outputs, no I/O.
+ *
+ * Precedence:
+ *  1. A fire always (re)starts a card. If one was still outstanding,
+ *     supersede it first (single-outstanding-card invariant).
+ *  2. While awaiting, a re-arm edge ON THE SAME start-file → FINISH.
+ *  3. Otherwise hold (the shell's wall-clock timeout resolves a card
+ *     that never gets a re-arm — e.g. a compaction that didn't shrink
+ *     context, or an agent that went idle right after START).
+ */
+export function nextCompactNotify(
+  state: CompactNotifyState,
+  ev: CompactNotifyEvent,
+): { state: CompactNotifyState; action: CompactNotifyAction } {
+  if (ev.fired) {
+    const superseding = state.phase === "awaiting";
+    return {
+      state: { phase: "awaiting", fileAtStart: ev.activeFile },
+      action: superseding ? "start-superseding" : "start",
+    };
+  }
+
+  if (state.phase === "awaiting") {
+    if (
+      ev.rearmed &&
+      ev.activeFile != null &&
+      ev.activeFile === state.fileAtStart
+    ) {
+      return { state: idleCompactNotifyState(), action: "finish" };
+    }
+    return { state, action: "none" };
+  }
+
+  return { state, action: "none" };
+}

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'
@@ -230,6 +230,7 @@ import { refreshBanner } from '../slot-banner-driver.js'
 import { loadConfig as loadSwitchroomConfig } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
 import { readTurnUsages } from '../../src/agents/perf.js'
 import { decideProactiveCompact, initialCompactState, type CompactState } from './proactive-compact.js'
+import { nextCompactNotify, idleCompactNotifyState, type CompactNotifyState } from './compact-notify.js'
 import {
   tryHostdDispatch,
   hostdRequestId,
@@ -248,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,
@@ -1086,6 +1089,25 @@ let lastSessionActiveFile: string | null = null
 // turn and we must not double-dispatch before the first send settles.
 let compactState: CompactState = initialCompactState()
 let compactDispatching = false
+
+// User-facing proactive-compaction notification (single Telegram card
+// edited START → FINISH; transition selection is pure in
+// ./compact-notify). Session reset/rotation stays silent — not here.
+// The wall-clock timer is owned HERE (not the pure helper): an idle
+// agent produces no idle evaluations, so a card that never gets a
+// re-arm edge must be resolved by a real timer, independent of the
+// eval loop, or it would dangle forever.
+const COMPACT_CARD_TIMEOUT_MS = 15 * 60 * 1000
+interface OutstandingCompactCard {
+  chatId: string
+  threadId: number | undefined
+  messageId: number
+  occAtStart: number
+  capAtStart: number
+  timer: ReturnType<typeof setTimeout>
+}
+let compactNotifyState: CompactNotifyState = idleCompactNotifyState()
+let outstandingCompactCard: OutstandingCompactCard | null = null
 const activeDraftStreams = new Map<string, DraftStreamHandle>()
 const activeDraftParseModes = new Map<string, 'HTML' | 'MarkdownV2' | undefined>()
 const suppressPtyPreview = new Set<string>()
@@ -1258,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');
@@ -1321,8 +1367,35 @@ function maybeProactiveCompact(): void {
   const t = turns[0];
   const occupancy = t.input + t.cacheRead + t.cacheCreate;
 
+  const wasArmed = compactState.armed;
   const decision = decideProactiveCompact(compactState, occupancy, cap);
   compactState = decision.state;
+  // Re-arm edge: the decider only flips disarmed→armed when post-
+  // /compact occupancy fell below 0.6×cap — i.e. context verifiably
+  // shrank. That edge is the honest "compaction finished" signal.
+  const rearmed = !wasArmed && decision.state.armed;
+
+  // User-facing notification transitions (pure). Resolved synchronously
+  // here — before any await and before the !fire return — so a
+  // re-entrant purge pass can't double-post (compactState was already
+  // persisted/disarmed above). All card I/O is reached only past the
+  // `cap == null` opt-in return earlier in this function, so a fleet
+  // with the feature off never posts anything (Defaults preserved).
+  const nt = nextCompactNotify(compactNotifyState, {
+    fired: decision.fire,
+    rearmed,
+    activeFile: file,
+  });
+  compactNotifyState = nt.state;
+  if (nt.action === 'finish') {
+    void resolveCompactCard('finished', occupancy);
+  } else if (nt.action === 'start' || nt.action === 'start-superseding') {
+    if (nt.action === 'start-superseding') {
+      void resolveCompactCard('superseded', occupancy);
+    }
+    void postCompactCard(occupancy, cap);
+  }
+
   if (!decision.fire) return;
 
   // Set the re-entrancy guard synchronously BEFORE the await so a
@@ -1345,6 +1418,109 @@ function maybeProactiveCompact(): void {
     });
 }
 
+/**
+ * Post the START card for a proactive compaction. Best-effort: a failed
+ * send just means no card (the compaction itself still happens). The
+ * outstanding record + a wall-clock timeout are armed so the card can
+ * never dangle if the re-arm edge never arrives (failed/idle case).
+ */
+async function postCompactCard(occ: number, cap: number): Promise<void> {
+  try {
+    const chatId = loadAccess().allowFrom[0];
+    if (!chatId) return;
+    const threadId = chatThreadMap.get(chatId);
+    const text =
+      `🗜️ <b>Context compaction</b>\n` +
+      `Working context hit ~${occ.toLocaleString()} tokens ` +
+      `(cap ${cap.toLocaleString()}) — running <code>/compact</code>. ` +
+      `Older detail moves to Hindsight; I'll confirm here once the ` +
+      `context has shrunk (may take a turn or two).`;
+    const sent = await swallowingApiCall(
+      () =>
+        bot.api.sendMessage(chatId, text, {
+          parse_mode: 'HTML',
+          ...(threadId != null ? { message_thread_id: threadId } : {}),
+        }),
+      { chat_id: chatId, verb: 'proactiveCompact.start' },
+    );
+    const messageId = (sent as { message_id?: number } | undefined)
+      ?.message_id;
+    if (typeof messageId !== 'number') return;
+    const timer = setTimeout(() => {
+      void resolveCompactCard('timeout', null);
+    }, COMPACT_CARD_TIMEOUT_MS);
+    timer.unref?.();
+    outstandingCompactCard = {
+      chatId,
+      threadId,
+      messageId,
+      occAtStart: occ,
+      capAtStart: cap,
+      timer,
+    };
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: proactive-compact start card failed: ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}
+
+/**
+ * Resolve the outstanding START card to a terminal state by editing it
+ * in place. `finished` is driven by the decider re-arm edge (context
+ * verifiably shrank), `superseded` when a newer compaction starts first,
+ * `timeout` by the wall-clock timer (re-arm never arrived). The
+ * outstanding record + timer are cleared synchronously BEFORE the await
+ * so a stale message_id can never be edited twice and the timer can't
+ * double-fire. On `timeout` the pure notify state is also reset so a
+ * future compaction starts a clean lifecycle.
+ */
+async function resolveCompactCard(
+  kind: 'finished' | 'superseded' | 'timeout',
+  occNow: number | null,
+): Promise<void> {
+  const card = outstandingCompactCard;
+  if (!card) return;
+  outstandingCompactCard = null;
+  clearTimeout(card.timer);
+  if (kind === 'timeout') compactNotifyState = idleCompactNotifyState();
+  let text: string;
+  if (kind === 'finished') {
+    text =
+      `✅ <b>Context compacted</b>\n` +
+      `Working context reduced` +
+      (occNow != null
+        ? ` (~${card.occAtStart.toLocaleString()} → ` +
+          `~${occNow.toLocaleString()} tokens)`
+        : '') +
+      `. Hindsight retains the detail.`;
+  } else if (kind === 'superseded') {
+    text =
+      `↩️ <b>Context compaction superseded</b>\n` +
+      `A newer compaction started before this one confirmed.`;
+  } else {
+    text =
+      `⚠️ <b>Compaction issued</b>\n` +
+      `<code>/compact</code> was requested but the context isn't ` +
+      `confirmed reduced yet. Native compaction and Hindsight still apply.`;
+  }
+  try {
+    await swallowingApiCall(
+      () =>
+        bot.api.editMessageText(card.chatId, card.messageId, text, {
+          parse_mode: 'HTML',
+        }),
+      { chat_id: card.chatId, verb: `proactiveCompact.${kind}` },
+    );
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: proactive-compact ${kind} card edit failed: ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}
+
 function endStatusReaction(chatId: string, threadId: number | undefined, outcome: 'done' | 'error'): void {
   const key = statusKey(chatId, threadId)
   const ctrl = activeStatusReactions.get(key)
@@ -2861,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 ` +
@@ -2879,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()
 
 /**
@@ -2930,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} ` +
@@ -3392,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(() => {
@@ -3406,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(
@@ -3418,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()
 }
 
@@ -7227,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'
+}