switchroom 0.18.30 → 0.18.32

package/telegram-plugin/gateway/inbound-delivery-machine-dispatch.ts

@@ -38,14 +38,13 @@
  *
  * The gateway-internal turn/poke effects (setTurnStarted,
  * clearTurnStarted, noteOutbound, firePoke) map to gateway-scope state
- * (`claudeBusyKeys`, the silence-poke ladder) that this decoupled module
+ * (the silence-poke ladder, turn markers) that this decoupled module
  * cannot reach directly, so they are dispatched through OPTIONAL
  * callbacks on the ctx. When a callback is absent the effect logs an
  * `unwired` trace rather than silently no-opping — the trace is the gate.
  *
- * Kill switch: `SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0` disables
- * dispatcher execution and the gateway falls back to imperative-only.
- * Default is ON — this PR is the cutover.
+ * The `SWITCHROOM_DELIVERY_MACHINE_CUTOVER` kill switch was removed in
+ * #2996 P1 after the cutover baked — the dispatcher always executes.
  */
 
 import type {
@@ -80,10 +79,10 @@ export interface DispatchCtx {
    */
   readonly onUserInboundDelivered?: (merged: InboundMessage) => void
   // ── Gateway-internal turn/poke effect callbacks ──────────────────
-  // These effects map to gateway-scope state (`claudeBusyKeys`, the
-  // silence-poke ladder) that this decoupled module cannot reach. The
-  // gateway supplies them when it flips inbound routing through the
-  // machine (PR3c). Absent → the effect logs an `unwired` trace.
+  // These effects map to gateway-scope state (the silence-poke ladder,
+  // turn markers) that this decoupled module cannot reach. The
+  // gateway supplies them at the live inbound call site. Absent → the
+  // effect logs an `unwired` trace.
   readonly onSetTurnStarted?: (key: ChatKey, at: number) => void
   /**
    * Optional: observe the outcome of a `deliverToBridge` effect. The
@@ -101,12 +100,6 @@ export interface DispatchCtx {
   readonly onFirePoke?: (key: ChatKey, level: 'soft' | 'firm' | 'fallback') => void
 }
 
-const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
-
-export function isDispatchEnabled(): boolean {
-  return enabled
-}
-
 /**
  * Execute the effects returned by `transition()`. Pure imperative
  * driver: side-effects only, no machine state held here.
@@ -117,7 +110,6 @@ export function isDispatchEnabled(): boolean {
  * already up).
  */
 export function dispatchEffects(effects: readonly Effect[], ctx: DispatchCtx): void {
-  if (!enabled) return
   for (const effect of effects) {
     dispatchOne(effect, ctx)
   }

package/telegram-plugin/gateway/inbound-delivery-machine-shadow.ts

@@ -1,32 +1,30 @@
 /**
- * InboundDeliveryStateMachine — SHADOW MODE wiring (Phase 2b PR 2).
+ * InboundDeliveryStateMachine — live machine state + event driver.
  *
- * Per RFC `reference/rfcs/inbound-delivery-state-machine.md` Phase 2b PR 2:
- * the state machine runs ALONGSIDE the existing imperative gateway
- * code, recording predicted effects to a structured trace. Behavior
- * is unchanged — every existing code path still executes the actual
- * I/O. This module's job:
+ * Historically the "shadow mode" wiring (RFC
+ * `reference/rfcs/inbound-delivery-state-machine.md` Phase 2b PR 2): the
+ * machine ran ALONGSIDE the imperative gateway code, predicting effects
+ * to a structured trace. The #3012 cutover made this state AUTHORITATIVE
+ * for the turn-in-flight gate and the deliver-vs-buffer inbound routing,
+ * and #2996 P1 removed the kill switches (`SWITCHROOM_DELIVERY_MACHINE_SHADOW`,
+ * `SWITCHROOM_DELIVERY_MACHINE_CUTOVER`) — the machine is now the sole
+ * delivery authority. (The `shadowEmit` name is kept for its ~15 gateway
+ * call sites; the `gw-trace shadow` trace prefix is kept for log-parser
+ * continuity.) This module's job:
  *
  *   1. Own the module-scope machine state.
- *   2. Expose `shadowEmit(event)` that runs `transition()` + logs the
- *      predicted effects via `gw-trace shadow ...` stderr lines.
- *   3. Provide test hooks for resetting + inspecting state.
+ *   2. Expose `shadowEmit(event)` that runs `transition()`, advances the
+ *      state, logs via `gw-trace shadow ...` stderr lines, and RETURNS
+ *      the effects for the gateway to execute (`dispatchEffects`).
+ *   3. Expose `isMachineInTurn()` — the authoritative gate read.
+ *   4. Provide test hooks for resetting + inspecting state.
  *
- * After PR 2 bakes on the fleet for 24+ hours, PR 3 will wire the
- * effects to drive ACTUAL behavior (the cutover), at which point the
- * imperative paths get deleted in PR 4.
- *
- * Telemetry approach: each `shadowEmit` writes a single stderr line
- * with the event kind + emitted effect kinds. Operators can then:
+ * Telemetry: each `shadowEmit` writes a single stderr line with the
+ * event kind + emitted effect kinds. Operators can then:
  *
  *   docker exec switchroom-<agent> sh -lc 'grep "gw-trace shadow" \
  *     /var/log/switchroom/gateway-supervisor.log | tail -50'
  *
- * to see what the state machine PREDICTS the gateway should do for
- * each event. Comparing against the actual log lines (`pending-inbound-
- * buffer: agent=X buffered ...` etc.) is the validation that the
- * machine is bit-identical with reality.
- *
  * Trace verbosity (#3025): the TTL `tick` event fires every ~30s and on a
  * healthy idle agent emits a zero-signal `event=tick effects=[]
  * global=bridge_alive_idle` line. Those no-op ticks are SUPPRESSED by
@@ -36,10 +34,6 @@
  * in `../shared/gw-trace-gate.ts` and also governs the `tg-post` poll
  * heartbeats. Real events, turn-expiring ticks, and in-turn ticks always
  * log regardless of the flag.
- *
- * Toggle off via `SWITCHROOM_DELIVERY_MACHINE_SHADOW=0` — a kill
- * switch for the case where the shadow emits prove problematic
- * (e.g., trace volume too high). The default is ON.
  */
 
 import {
@@ -52,58 +46,36 @@ import {
 import { shouldEmitShadowTrace } from '../shared/gw-trace-gate.js'
 
 let state: State = initialState()
-const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_SHADOW !== '0'
-
-// Phase 2b PR 3 — STAGED CUTOVER. When enabled, the gateway's
-// "is a turn in flight?" gate reads this machine's global state
-// instead of the PR3b `claudeBusyKeys` set. The machine tracks ONE
-// `activeTurn` (single bridge) plus TTL `tick` expiry, so — unlike a
-// per-delivery key set — it cannot accumulate orphan keys and wedge
-// the gate "in-flight forever" (the gymbro/clerk 5-min dangle of
-// 2026-05-28). Scope is the turn-in-flight GATE only; the poke ladder
-// and perm-verdict effects stay imperative for a follow-up PR.
-//
-// Kill switch: `SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0` reverts every
-// gate to the legacy claudeBusyKeys read (zero behaviour change).
-// Requires shadow mode ON — with shadow off the machine state is
-// frozen and must NOT be read as authoritative.
-const cutoverEnabled = enabled && process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
-
-/**
- * True when the kill-switch leaves the delivery machine authoritative
- * for the turn-in-flight gate. Gateway gate sites branch on this.
- */
-export function isDeliveryCutoverEnabled(): boolean {
-  return cutoverEnabled
-}
 
 /**
  * Authoritative "is a turn currently in flight?" read for the gate.
- * Maps the machine's global state to the boolean the legacy
- * `claudeBusyKeys.size > 0` gate produced. `bridge_dead` and
- * `bridge_alive_idle` are both "not in flight".
+ * The machine tracks ONE `activeTurn` (single bridge) plus TTL `tick`
+ * expiry, so — unlike the deleted per-delivery `claudeBusyKeys` set —
+ * it cannot accumulate orphan keys and wedge the gate "in-flight
+ * forever" (the gymbro/clerk 5-min dangle of 2026-05-28). `bridge_dead`
+ * and `bridge_alive_idle` are both "not in flight".
  */
 export function isMachineInTurn(): boolean {
   return state.global.kind === 'bridge_alive_in_turn'
 }
 
 /**
- * Run an event through the state machine in shadow mode. The machine
- * state advances, the predicted effects are LOGGED, but no I/O fires.
- *
- * Returns the effects for callers that want to inspect them inline
- * (e.g., the eventual PR 3 cutover will replace the return-and-ignore
- * pattern here with return-and-execute).
+ * Run an event through the state machine: the machine state advances,
+ * the effects are logged and RETURNED for the caller to execute
+ * (`dispatchEffects` at the live inbound/bridgeUp call sites; the
+ * lifecycle emits — turnStart/turnEnd/modelOutbound/tick — advance state
+ * only and ignore the return, their real-world work still being
+ * imperative per the RFC's open PR3b checklist).
  */
 export function shadowEmit(event: Event): readonly Effect[] {
-  if (!enabled) return []
-  // Shadow mode MUST NEVER break the gateway. The state machine is
-  // pure (no I/O, no async) and property-tested over 5000 schedules,
+  // The machine driver MUST NEVER break the gateway. The state machine
+  // is pure (no I/O, no async) and property-tested over 5000 schedules,
   // so transition() won't throw on well-formed input. But event
   // construction at the call site could mis-shape inputs; the
-  // try/catch is belt-and-braces so a shadow bug never wedges a real
-  // turn. The catch logs and bails — the imperative gateway code
-  // below the emit point still runs.
+  // try/catch is belt-and-braces so a driver bug never wedges a real
+  // turn. The catch logs and bails — the gateway code below the emit
+  // point still runs (falling back to the buffer-everything semantics
+  // of an un-advanced machine).
   try {
     const result = transition(state, event)
     state = result.state
@@ -164,8 +136,3 @@ export function __shadowResetForTests(): void {
 export function __shadowGetStateForTests(): State {
   return state
 }
-
-/** Test hook: check if shadow mode is enabled (mirrors the env-var). */
-export function __shadowEnabledForTests(): boolean {
-  return enabled
-}

package/telegram-plugin/gateway/obligation-ledger.ts

@@ -26,6 +26,28 @@
 
 import type { InboundMessage } from './ipc-protocol.js'
 
+/**
+ * #3282 — the durable per-chunk snapshot of a PARTIALLY delivered backstop
+ * answer, attached to the obligation so the represent can resume the exact
+ * captured answer's non-`landed-confirmed` tail (byte-identical) instead of
+ * regenerating it (which re-posts chunks that already landed). Rides the
+ * obligation ledger's atomic snapshot, so it survives a gateway/container
+ * restart. See captured-answer-resume.ts for the resume mechanism.
+ */
+export interface CapturedDeliverySnapshot {
+  /** The byte-identical captured answer, split into chunks (the SAME split the
+   *  original backstop delivery used). Re-delivered verbatim on resume. */
+  readonly chunks: string[]
+  /** Per-LANDED-chunk state: the landed message id(s) + whether a read-back
+   *  confirmed the message exists. A chunk absent here never landed → the resume
+   *  treats it as `unsent` and re-sends it. */
+  readonly chunkStates: Array<{
+    readonly index: number
+    readonly messageIds: number[]
+    readonly confirmed: boolean
+  }>
+}
+
 export interface Obligation {
   /** deriveTurnId(chat, thread, messageId) — the stable identity. */
   readonly originTurnId: string
@@ -61,6 +83,12 @@ export interface Obligation {
    *  re-present/escalate when the sweep fires < 5s later. Durable (part of the
    *  snapshot) so the grace window survives a restart. */
   lastRepresentedAt?: number
+  /** #3282 — durable captured-answer snapshot for a PARTIALLY delivered backstop
+   *  answer. Present ⇒ the represent branch drives a byte-identical captured-answer
+   *  RESUME of the non-confirmed tail (never a regeneration); absent ⇒ the genuine
+   *  "model wrote nothing" represent falls through to fresh generation. Dropped
+   *  with the obligation on close/escalate (bounded lifetime, design A6). */
+  capturedDelivery?: CapturedDeliverySnapshot
 }
 
 /** What the gateway should do for the oldest open obligation at an idle boundary. */
@@ -316,6 +344,20 @@ export class ObligationLedger {
     return null
   }
 
+  /**
+   * #3282 — attach (or refresh) the durable captured-answer snapshot for a
+   * PARTIALLY delivered backstop answer. No-op if the obligation isn't open (a
+   * fully delivered turn closes its obligation, so there is nothing to resume).
+   * Persists, so the snapshot survives a restart and the represent resumes the
+   * missing tail instead of regenerating the whole answer.
+   */
+  noteCapturedDelivery(originTurnId: string, snapshot: CapturedDeliverySnapshot): void {
+    const o = this.open.get(originTurnId)
+    if (o === undefined || snapshot.chunks.length === 0) return
+    o.capturedDelivery = snapshot
+    this.persist()
+  }
+
   /** Record that an obligation was just re-presented (bumps representCount, stamps
    *  lastRepresentedAt for the per-represent grace window). */
   markRepresented(originTurnId: string, now = Date.now()): number {

package/telegram-plugin/gateway/obligation-store.ts

@@ -55,6 +55,42 @@ function isObligationRow(x: unknown): x is Obligation {
   )
 }
 
+/**
+ * #3282 — true iff the optional captured-answer snapshot is structurally sound.
+ * A malformed blob (partial write, forward-incompatible shape) must NOT crash the
+ * resume: `sanitizeCapturedDelivery` strips it, so the obligation degrades to a
+ * fresh-generation represent (today's behaviour) rather than throwing.
+ */
+function isValidCapturedDelivery(x: unknown): boolean {
+  if (x == null || typeof x !== 'object') return false
+  const c = x as Record<string, unknown>
+  // Empty chunks ⇒ nothing to resume: treat as malformed so it is STRIPPED and
+  // the obligation degrades to a (bounded) fresh-generation represent rather than
+  // sitting non-null-but-empty and no-op'ing the sweep forever.
+  if (!Array.isArray(c.chunks) || c.chunks.length === 0 || !c.chunks.every((t) => typeof t === 'string')) return false
+  if (!Array.isArray(c.chunkStates)) return false
+  return c.chunkStates.every((s) => {
+    if (s == null || typeof s !== 'object') return false
+    const st = s as Record<string, unknown>
+    return (
+      typeof st.index === 'number' &&
+      typeof st.confirmed === 'boolean' &&
+      Array.isArray(st.messageIds) &&
+      st.messageIds.every((m) => typeof m === 'number')
+    )
+  })
+}
+
+/** Drop a malformed `capturedDelivery` in place so a corrupt snapshot degrades to
+ *  fresh-generation represent instead of crashing the resume (fail-open). */
+function sanitizeCapturedDelivery(o: Obligation): Obligation {
+  if (o.capturedDelivery != null && !isValidCapturedDelivery(o.capturedDelivery)) {
+    const { capturedDelivery: _drop, ...rest } = o
+    return rest
+  }
+  return o
+}
+
 /**
  * Load the persisted open set. Returns [] on a missing, unreadable, or
  * malformed file (fail-open to empty: a corrupt snapshot must never crash boot;
@@ -78,7 +114,7 @@ export function loadObligations(path: string, fs: ObligationStoreFsSeam): Obliga
   if (parsed == null || typeof parsed !== 'object') return []
   const env = parsed as Record<string, unknown>
   if (env.v !== 1 || !Array.isArray(env.obligations)) return []
-  return env.obligations.filter(isObligationRow)
+  return env.obligations.filter(isObligationRow).map(sanitizeCapturedDelivery)
 }
 
 /**