switchroom 0.18.8 → 0.18.10

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

@@ -7,17 +7,41 @@
  * (b) execute the returned effects against real I/O. This module owns
  * step (b) for the cutover.
  *
- * Scope of THIS PR — bridgeUp only:
- *   - drainBuffer                       → executed
- *   - redeliverPersistedPermVerdicts    → executed
+ * Effects wired to real executors (all effect kinds now handled):
+ *   - drainBuffer                       → redeliverBufferedInbound
+ *   - redeliverPersistedPermVerdicts    → pendingPermissionBuffer.drain → send
+ *   - deliverToBridge                   → client.send / ipcServer.sendToAgent
+ *   - bufferInbound                     → pendingInboundBuffer.push
+ *   - persistInbound                    → inboundSpool.put
+ *   - deliverPermVerdict                → client.send / ipcServer.sendToAgent
+ *   - persistPermVerdict                → pendingPermissionBuffer.push
+ *   - setTurnStarted / clearTurnStarted → onSetTurnStarted / onClearTurnStarted
+ *   - noteOutbound                      → onNoteOutbound
+ *   - firePoke                          → onFirePoke
  *   - logTrace                          → executed
  *
- * Other effects (deliverToBridge, bufferInbound, persistInbound,
- * setTurnStarted, clearTurnStarted, noteOutbound, firePoke,
- * deliverPermVerdict, persistPermVerdict) still flow through their
- * existing imperative paths in `gateway.ts`. The dispatcher logs them
- * as `not-yet-cutover` so a future PR can wire them without grep-and-
- * pray. NEVER silently no-op: the trace is the gate.
+ * Live call sites (post PR3c flip, #2794):
+ *   - bridgeUp (gateway onClientRegistered): drainBuffer /
+ *     redeliverPersistedPermVerdicts / logTrace.
+ *   - handleInbound DEFERRED_INBOUND_EMIT: the inbound-routing effects
+ *     (deliverToBridge / bufferInbound / persistInbound / setTurnStarted)
+ *     are AUTHORITATIVE when the cutover is on — the imperative twin in
+ *     gateway.ts runs only under the kill switch or the documented
+ *     carve-outs (interrupt-while-in-turn, bridge_dead). The twin is
+ *     deleted in PR4 after the 48h bake (see the "Hard removal plan"
+ *     checklist in the RFC: PR3b step 2 / PR4 remain open).
+ *   - turnEnd lifecycle effects remain shadow-only: the imperative
+ *     turn-end sites (purgeReactionTracking / releaseTurnBufferGate)
+ *     already execute the effect-equivalents with gates the machine does
+ *     not model yet (serialize-until-replied drain); PR3b step 2 tracks
+ *     that flip.
+ *
+ * The gateway-internal turn/poke effects (setTurnStarted,
+ * clearTurnStarted, noteOutbound, firePoke) map to gateway-scope state
+ * (`claudeBusyKeys`, the silence-poke ladder) 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.
@@ -26,10 +50,11 @@
 
 import type {
   Effect,
+  ChatKey,
   InboundMessage as MachineInboundMessage,
 } from './inbound-delivery-machine.js'
 import type { IpcServer, IpcClient } from './ipc-server.js'
-import type { InboundMessage } from './ipc-protocol.js'
+import type { InboundMessage, PermissionEvent } from './ipc-protocol.js'
 import type { PendingInboundBuffer } from './pending-inbound-buffer.js'
 import { redeliverBufferedInbound } from './pending-inbound-buffer.js'
 import type { InboundSpool } from './inbound-spool.js'
@@ -54,6 +79,26 @@ export interface DispatchCtx {
    * (clerk lost-message incident, 2026-06-03.)
    */
   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.
+  readonly onSetTurnStarted?: (key: ChatKey, at: number) => void
+  /**
+   * Optional: observe the outcome of a `deliverToBridge` effect. The
+   * imperative twin branches on `sendToAgent`'s boolean (delivered →
+   * steer-ack + busy-mark + delivery-confirm tracking; miss → release
+   * reservation + durable-buffer + restart notice). The machine cannot
+   * model a send that fails while the bridge is nominally alive, so the
+   * PR3c live call site needs the result to run the same post-send
+   * branches the twin runs. Called once per deliverToBridge effect,
+   * after the send attempt, before `onUserInboundDelivered` enrolment.
+   */
+  readonly onDeliverResult?: (key: ChatKey, ok: boolean, msg: InboundMessage) => void
+  readonly onClearTurnStarted?: (key: ChatKey) => void
+  readonly onNoteOutbound?: (key: ChatKey, at: number) => void
+  readonly onFirePoke?: (key: ChatKey, level: 'soft' | 'firm' | 'fallback') => void
 }
 
 const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
@@ -168,20 +213,133 @@ function dispatchOne(effect: Effect, ctx: DispatchCtx): void {
       return
     }
 
-    // The cases below are KNOWN effect kinds that this PR does NOT
-    // cut over. The imperative paths still run for them; the
-    // dispatcher logs the event so future cutover PRs can grep for
-    // exactly the call sites to migrate.
-    case 'deliverToBridge':
-    case 'bufferInbound':
-    case 'persistInbound':
-    case 'setTurnStarted':
-    case 'clearTurnStarted':
-    case 'noteOutbound':
-    case 'firePoke':
-    case 'deliverPermVerdict':
+    case 'deliverToBridge': {
+      // Route a single inbound to the live bridge. The machine's
+      // InboundMessage.payload carries the real ipc-protocol
+      // InboundMessage; the machine treats it as opaque.
+      const msg = effect.msg.payload as InboundMessage
+      let ok = false
+      try {
+        if (ctx.client) {
+          ctx.client.send(msg)
+          ok = true
+        } else {
+          ok = ctx.ipcServer.sendToAgent(ctx.selfAgent, msg)
+        }
+      } catch (err) {
+        log(
+          `telegram gateway: dispatch deliverToBridge send threw agent=${ctx.selfAgent} ` +
+            `key=${effect.key}: ${(err as Error).message}\n`,
+        )
+        ok = false
+      }
+      if (ctx.onDeliverResult) {
+        try {
+          ctx.onDeliverResult(effect.key, ok, msg)
+        } catch {
+          /* observer is best-effort; never breaks delivery */
+        }
+      }
+      if (ok && ctx.onUserInboundDelivered) {
+        // Enrol in the deliver-until-acked sweep — a socket write is not
+        // proof claude consumed it (see onUserInboundDelivered doc).
+        // Pass UNCONDITIONALLY, mirroring the drainBuffer path above:
+        // the callback self-gates via shouldTrackDelivery (inbound-
+        // delivery-confirm.ts), which REJECTS sourced messages and
+        // tracks real user inbounds (meta.source undefined) — exactly
+        // the messages the sweep protects. Do NOT pre-filter on
+        // meta.source here; an inverted guard would skip user inbounds
+        // and enrol only messages the inner gate discards.
+        try {
+          ctx.onUserInboundDelivered(msg)
+        } catch {
+          /* enrolment is best-effort; never breaks delivery */
+        }
+      }
+      log(`gw-trace dispatch deliverToBridge key=${effect.key} ok=${ok}\n`)
+      return
+    }
+
+    case 'bufferInbound': {
+      const msg = effect.msg.payload as InboundMessage
+      const buffered = ctx.pendingInboundBuffer.push(ctx.selfAgent, msg)
+      log(`gw-trace dispatch bufferInbound key=${effect.key} buffered=${buffered}\n`)
+      return
+    }
+
+    case 'persistInbound': {
+      // Durable spool. `pendingInboundBuffer.push` already spools when a
+      // spool is attached to the buffer, so a persistInbound paired with
+      // a bufferInbound is idempotent (put() is idempotent by spoolId).
+      const msg = effect.msg.payload as InboundMessage
+      const put = ctx.inboundSpool ? ctx.inboundSpool.put(ctx.selfAgent, msg) : false
+      log(`gw-trace dispatch persistInbound key=${effect.key} put=${put}\n`)
+      return
+    }
+
+    case 'deliverPermVerdict': {
+      // Branch order differs from the imperative twin
+      // (gateway.ts dispatchPermissionVerdict), which always goes via
+      // `ipcServer.sendToAgent` — it runs outside any bridgeUp context,
+      // so it has no just-registered client handle. Here `ctx.client`
+      // is preferred WHEN PRESENT for the same reason as drainBuffer /
+      // redeliverPersistedPermVerdicts above: on the bridgeUp path the
+      // registry lookup may not yet observe the just-registered client,
+      // and a direct send to the connecting socket is the reliable
+      // route. PR3c's live call site for machine-driven permVerdict
+      // events (non-bridgeUp) must construct the ctx WITHOUT `client`,
+      // which makes this branch behave exactly like the twin
+      // (sendToAgent). Note the twin additionally buffers on a failed
+      // send; the machine models that as a separate persistPermVerdict
+      // effect (bridge_dead state), so no fallback push here.
+      const ev = effect.verdict.payload as PermissionEvent
+      let ok = false
+      try {
+        if (ctx.client) {
+          ctx.client.send(ev as never)
+          ok = true
+        } else {
+          ok = ctx.ipcServer.sendToAgent(ctx.selfAgent, ev as never)
+        }
+      } catch (err) {
+        log(
+          `telegram gateway: dispatch deliverPermVerdict send threw agent=${ctx.selfAgent} ` +
+            `request=${effect.verdict.requestId}: ${(err as Error).message}\n`,
+        )
+        ok = false
+      }
+      log(`gw-trace dispatch deliverPermVerdict request=${effect.verdict.requestId} ok=${ok}\n`)
+      return
+    }
+
     case 'persistPermVerdict': {
-      log(`gw-trace dispatch not-yet-cutover effect=${effect.kind}\n`)
+      const ev = effect.verdict.payload as PermissionEvent
+      const pushed = ctx.pendingPermissionBuffer.push(ctx.selfAgent, ev)
+      log(`gw-trace dispatch persistPermVerdict request=${effect.verdict.requestId} pushed=${pushed}\n`)
+      return
+    }
+
+    case 'setTurnStarted': {
+      if (ctx.onSetTurnStarted) ctx.onSetTurnStarted(effect.key, effect.at)
+      else log(`gw-trace dispatch unwired effect=setTurnStarted key=${effect.key}\n`)
+      return
+    }
+
+    case 'clearTurnStarted': {
+      if (ctx.onClearTurnStarted) ctx.onClearTurnStarted(effect.key)
+      else log(`gw-trace dispatch unwired effect=clearTurnStarted key=${effect.key}\n`)
+      return
+    }
+
+    case 'noteOutbound': {
+      if (ctx.onNoteOutbound) ctx.onNoteOutbound(effect.key, effect.at)
+      else log(`gw-trace dispatch unwired effect=noteOutbound key=${effect.key}\n`)
+      return
+    }
+
+    case 'firePoke': {
+      if (ctx.onFirePoke) ctx.onFirePoke(effect.key, effect.level)
+      else log(`gw-trace dispatch unwired effect=firePoke key=${effect.key} level=${effect.level}\n`)
       return
     }
   }

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

@@ -261,6 +261,14 @@ export function transition(state: State, event: Event): Transition {
       const alive = state.global.kind !== 'bridge_dead'
 
       if (!alive) {
+        // ANCHORED STRING — `inbound_bridge_dead_buffer` is load-bearing:
+        // gateway.ts's PR3c bridge-dead carve-out keys off this exact stage
+        // string to route the inbound to the imperative twin (whose
+        // shouldTrackDelivery drop semantics + restart notice are the
+        // contract the machine doesn't model). Renaming it silently reroutes
+        // that carve-out; a pin test in inbound-delivery-cutover-flip.test.ts
+        // breaks on rename. Both the string key-off and this anchor are
+        // deleted in PR4 with the twin.
         return {
           state,
           effects: [

package/telegram-plugin/gateway/model-command.ts

@@ -175,7 +175,7 @@ export interface ModelCommandReply {
 }
 
 const PERSIST_NOTE =
-  '_Sticky across switchroom-managed relaunches (\`/new\`, watchdog recovery); reverts on \`/restart\`, agent restart, crash, or external container restart. \`/model default\` clears it. To persist, set \`model:\` in switchroom.yaml._'
+  '_Sticky — persists across restarts, deploys, and crashes until \`/model default\` clears it (or the configured \`model:\` in switchroom.yaml changes, which resets it and notifies you). To change the default, set \`model:\` in switchroom.yaml._'
 
 function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
   const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`${a}\``).join(' · ')
@@ -230,7 +230,7 @@ export async function handleModelCommand(
   // and ask the operator to retry (parity with the menu callback's isBusy check).
   if (deps.isBusy()) {
     return {
-      text: '⏳ The agent is mid-turn — a model switch needs an idle session. Try again in a moment.',
+      text: '⏳ The agent is mid-turn — a model switch needs an idle session. The switch was not applied.',
       html: true,
     }
   }
@@ -506,6 +506,26 @@ export const SR_MODEL_ALIASES: Record<string, string> = {
 }
 
 /** Expand a short alias (case-insensitive) to its full sr-* id, or return the original. */
+/**
+ * #3042 review blocker 2a: can `token` be trusted for a DURABLE, boot-applied
+ * `.session-model` persist WITHOUT a live confirmation from claude?
+ *
+ * A queued typed `/model <arg>` that is persisted at shutdown was never
+ * validated by claude's picker — and under the keep-by-default boot (#3039)
+ * a garbage-but-shape-valid token (e.g. `claude-nonexistnet-9`) would make
+ * every boot run `claude --model <garbage>` with the gateway dead. Only
+ * tokens with a switchroom-known meaning are offline-trustable: the static
+ * Claude aliases (claude resolves them itself) and the curated sr-* alias
+ * TARGETS (present in the LiteLLM config by construction). Full `claude-*` /
+ * arbitrary `sr-*` ids typed by hand are refused — they need the live
+ * session to verify, so the operator is asked to re-issue after boot.
+ */
+export function isOfflineTrustedModelToken(token: string): boolean {
+  if ((MODEL_ALIASES as readonly string[]).includes(token)) return true
+  if (token in SR_MODEL_ALIASES) return true
+  return Object.values(SR_MODEL_ALIASES).includes(token)
+}
+
 export function expandSrAlias(arg: string): string {
   return SR_MODEL_ALIASES[arg.toLowerCase()] ?? arg
 }
@@ -548,10 +568,67 @@ export function modelSelectCallbackData(label: string): string {
   return `${MODEL_CALLBACK_SELECT}${labelTag(label)}`
 }
 
-function busyReply(deps: Pick<ModelMenuDeps, 'escapeHtml'>): ModelMenuReply {
+const BUSY_REFUSAL_TEXT =
+  '⏳ The agent is mid-turn — the model picker needs an idle prompt. Your tap was not applied.'
+
+/**
+ * Busy-refusal detector (#3039). The gateway's queued-command drain applies a
+ * command believing the session is idle; if a new turn started in the race
+ * window the underlying handler still refuses with one of these texts. The
+ * drain matches on this and RE-ENQUEUES the command instead of stamping the
+ * refusal onto the ack card as a false final state — so no user-visible path
+ * ever ends at "try again".
+ */
+export function isBusyRefusalText(text: string): boolean {
+  return text.includes('The agent is mid-turn')
+}
+
+/**
+ * Mid-turn `/model` menu (#3039): instead of refusing ("try again in a
+ * moment"), render a STATIC keyboard that needs no picker discovery — the
+ * alias rows + the external page. Every switch tap rides the gateway's
+ * mid-turn queue (ack → apply at idle → confirm), so opening the menu during
+ * a long turn still lets the operator lock in a choice.
+ */
+function busyStaticMenu(
+  deps: Pick<ModelMenuDeps, 'escapeHtml'> & Pick<ModelCommandDeps, 'getAgentName'>,
+  page: ModelMenuPage,
+): ModelMenuReply {
+  const externalNames = externalModelNames([])
+  if (page === 'external') {
+    return {
+      text: [
+        `**Model — ${deps.escapeHtml(deps.getAgentName())}** · 🌐 External`,
+        '_Agent is mid-turn — taps are queued and apply the moment the turn ends._',
+        'These models are **billed separately** via OpenRouter. Tap one to switch the **live session**:',
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+      keyboard: externalPageKeyboard(externalNames),
+    }
+  }
+  const rows: ModelMenuKeyboardButton[][] = []
+  for (const alias of MODEL_ALIASES) {
+    if (alias === 'default') continue
+    rows.push([{
+      text: alias.charAt(0).toUpperCase() + alias.slice(1),
+      callback_data: `${MODEL_CALLBACK_ALIAS}${alias}`,
+    }])
+  }
+  rows.push([{ text: 'Default (configured)', callback_data: `${MODEL_CALLBACK_ALIAS}default` }])
+  if (externalNames.length > 0) {
+    rows.push([{ text: '🌐 External models ▸', callback_data: MODEL_CALLBACK_PAGE_EXTERNAL }])
+  }
+  rows.push([{ text: '🔄 Refresh', callback_data: MODEL_CALLBACK_REFRESH }])
   return {
-    text: '⏳ The agent is mid-turn — the model picker needs an idle prompt. Try again in a moment.',
+    text: [
+      `**Model — ${deps.escapeHtml(deps.getAgentName())}**`,
+      '_Agent is mid-turn, so the live picker can\u2019t be read right now — this is the quick list. A tap is queued and applies the moment the turn ends._',
+      'Tap a model to switch the **live session**:',
+      PERSIST_NOTE,
+    ].join('\n'),
     html: true,
+    keyboard: rows,
   }
 }
 
@@ -654,7 +731,7 @@ export async function buildModelMenu(
   deps: ModelMenuDeps & ModelCommandDeps,
   page: ModelMenuPage = 'main',
 ): Promise<ModelMenuReply> {
-  if (deps.isBusy()) return busyReply(deps)
+  if (deps.isBusy()) return busyStaticMenu(deps, page)
 
   const [discovered, quota, srNames] = await Promise.all([
     deps.discover(deps.getAgentName()),
@@ -734,6 +811,12 @@ export interface ModelCallbackOutcome {
    * "try again" line (which read as "nothing happened").
    */
   toastOnly?: boolean
+  /**
+   * True when this outcome is the mid-turn refusal (#3039). The queued-command
+   * drain re-enqueues on this instead of stamping the refusal onto the ack
+   * card as a false final state.
+   */
+  busyRefusal?: boolean
   /**
    * On a successful session switch, the live model name now running (parsed
    * from claude's confirmation, e.g. "Fable 5"). The gateway records this as
@@ -799,8 +882,9 @@ export async function handleModelMenuCallback(
     if (deps.isBusy()) {
       return {
         answer: '⏳ Agent is mid-turn — tap again when it’s idle',
-        reply: busyReply(deps),
+        reply: { text: BUSY_REFUSAL_TEXT, html: true },
         toastOnly: true,
+        busyRefusal: true,
       }
     }
     let aliasResult: InjectResult
@@ -862,8 +946,9 @@ export async function handleModelMenuCallback(
     if (deps.isBusy()) {
       return {
         answer: '⏳ Agent is mid-turn — tap again when it’s idle',
-        reply: busyReply(deps),
+        reply: { text: BUSY_REFUSAL_TEXT, html: true },
         toastOnly: true,
+        busyRefusal: true,
       }
     }
     try {
@@ -896,8 +981,9 @@ export async function handleModelMenuCallback(
   if (deps.isBusy()) {
     return {
       answer: '⏳ Agent is mid-turn — tap again when it’s idle',
-      reply: busyReply(deps),
+      reply: { text: BUSY_REFUSAL_TEXT, html: true },
       toastOnly: true,
+      busyRefusal: true,
     }
   }