switchroom 0.18.7 → 0.18.9

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/mental-model-propose-diff.ts

@@ -27,6 +27,49 @@
 import { parseDocument } from "yaml";
 import { generateUnifiedDiff } from "../../src/web/config-diff.js";
 
+/**
+ * Decode the canonical six HTML/XML entities to their literal characters — the
+ * config-write-boundary layer of the #2976 defense-in-depth.
+ *
+ * SCOPE / reachability (be honest about which half is load-bearing):
+ *   - `source_query` decode is the REACHABLE half. A model can copy escaped
+ *     entities out of its Telegram-HTML-rendered context into a proposal's
+ *     free-form `source_query`, and undecoded it would steer recall on `R&D`
+ *     instead of `R&D` — a durable, silent corruption of a memory-integrity
+ *     field. Normalizing here means an escaped query can never LAND in
+ *     `memory.mental_models[]`.
+ *   - `name` decode is REDUNDANT belt-and-suspenders. The `mental_model_propose`
+ *     gateway tool already slug-validates `name` against
+ *     /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/ BEFORE this runs, so an entity-bearing
+ *     name is rejected upstream and can't reach here. It's kept only so this
+ *     write boundary is self-contained if that gate ever moves.
+ *   - The observed in-NAME corruption (`Nutrition Protocol & Deficit Status`,
+ *     klanker 2026-07-06) actually arrived via the DIRECT `create_mental_model`
+ *     Hindsight tool (`ensureMentalModel`, undecoded), NOT this propose path.
+ *     That vector is OUT OF SCOPE here — covered by the steering.ts context-
+ *     hygiene + in-service `Dockerfile.hindsight` normalization follow-ups.
+ *
+ * SINGLE PASS by design (matches issue #2976's success criteria): a
+ * double-escaped `R&D` decodes ONE layer to `R&D`, not all the way
+ * to `R&D` — we only undo the escaping switchroom itself applied when it
+ * rendered the model's prior output, never the user's literal intent. `&`
+ * is decoded LAST so `&amp;lt;` collapses to `&lt;` (one layer), not `<`.
+ *
+ * Accepted tradeoff: a `source_query` a human genuinely intended to contain a
+ * literal `&amp;` / `&lt;` / etc. (rare — a reflection question, not markup)
+ * will have that one layer decoded. Steering queries reading as escaped HTML is
+ * the far more common and more harmful case, so we optimize for it.
+ */
+export function decodeCanonicalEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
 /**
  * A proposed mental model, in the same snake_case shape the
  * `memory.mental_models[]` schema (#2874) accepts. `name` + `source_query`
@@ -125,20 +168,33 @@ export function buildMentalModelAppendDiff(args: {
   }
 
   // Duplicate-name guard (defense-in-depth; the executor also checks up front
-  // so it never even posts a card for a dupe).
+  // so it never even posts a card for a dupe). Compare on the DECODED name so a
+  // re-propose of an entity-escaped variant collides with the already-stored
+  // literal (#2976) rather than sneaking in a corrupted twin.
+  const decodedName = decodeCanonicalEntities(spec.name);
   const existing = readDeclaredMentalModelNames(configText, agentName);
-  if (existing.includes(spec.name)) {
+  if (existing.includes(decodedName)) {
     return {
       ok: false,
       error: "duplicate",
-      detail: `mental model "${spec.name}" is already declared for ${agentName}`,
+      detail: `mental model "${decodedName}" is already declared for ${agentName}`,
     };
   }
 
+  // #2976 write-boundary normalization: decode any HTML/XML entities the model
+  // may have copied out of its own escaped context so the LITERAL characters
+  // land in config — never `&amp;` / `&lt;` etc. The load-bearing target is the
+  // free-form `source_query`; the `name` decode is redundant with the gateway
+  // slug gate (an entity-bearing name is rejected upstream) and kept only so
+  // this boundary is self-contained. Duplicate-name guard runs on the decoded
+  // name above.
+  const name = decodedName;
+  const source_query = decodeCanonicalEntities(spec.source_query);
+
   // Assemble the minimal, schema-clean declaration node.
   const item: Record<string, unknown> = {
-    name: spec.name,
-    source_query: spec.source_query,
+    name,
+    source_query,
   };
   if (spec.refresh_after_consolidation !== undefined) {
     item.refresh_after_consolidation = spec.refresh_after_consolidation;

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

@@ -149,7 +149,7 @@ export interface ModelCommandDeps {
    * Schedule a session-only switch TO a non-Claude (`sr-*` LiteLLM/OpenRouter)
    * model. claude's in-REPL `/model` picker rejects unknown `sr-*` ids, so an
    * inject can't set them. Instead the gateway writes the chosen token to the
-   * `.session-model-override` carrier file and gracefully restarts the agent;
+   * durable `.session-model` override and gracefully restarts the agent;
    * the next boot launches `claude --model <token>` directly (LiteLLM routes
    * it, no picker validation). Session-only: reverts to the configured default
    * on the following restart. Wired to the same restart dispatch as
@@ -175,7 +175,7 @@ export interface ModelCommandReply {
 }
 
 const PERSIST_NOTE =
-  '_Session-only — lasts until restart. To persist, set \`model:\` in switchroom.yaml and restart._'
+  '_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._'
 
 function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
   const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`${a}\``).join(' · ')
@@ -240,7 +240,7 @@ export async function handleModelCommand(
   // the proxy at session start, not by claude's own REPL. A graceful restart
   // is the only clean path back to the native OAuth route. Route it through the
   // SAME carrier mechanism as a Claude → sr-* switch (scheduleModelRelaunch)
-  // so the requested Claude model is written to `.session-model-override` and
+  // so the requested Claude model is written to the durable `.session-model` and
   // survives the restart — otherwise boot launches the configured default and
   // the operator's choice is silently dropped. start.sh's LiteLLM-down guard
   // only special-cases `sr-*` overrides, so a Claude token is never dropped.
@@ -294,7 +294,7 @@ export async function handleModelCommand(
     return {
       text: [
         `Switching to \`${deps.escapeHtml(model)}\` — restarting session (~30s).`,
-        '_Session-only — reverts to the configured default on the next restart._',
+        PERSIST_NOTE,
       ].join('\n'),
       html: true,
     }
@@ -744,13 +744,20 @@ export interface ModelCallbackOutcome {
   /**
    * The canonical `claude --model` token (alias or full `claude-*` id) for a
    * Claude selection, when derivable — distinct from `selectedModel` (a display
-   * name for /status). The gateway writes this to the `.session-model-override`
-   * carrier on an sr-* → Claude transition so the requested Claude model survives
-   * the restart (otherwise boot launches the configured default). Absent when the
-   * target has no derivable token (e.g. the "Default" row → boot the configured
-   * default).
+   * name for /status). The gateway persists this to the durable
+   * `.session-model` override so the confirmed switch survives
+   * switchroom-managed relaunches (and, on an sr-* → Claude transition, its own
+   * restart). Absent when the target has no derivable token.
    */
   selectedModelToken?: string
+  /**
+   * True when the confirmed selection was the "Default (recommended)" row —
+   * i.e. the session is now on the configured default and any sticky
+   * `.session-model` override must be CLEARED (there is no token to persist;
+   * persisting nothing while leaving a stale override would re-apply the old
+   * model on the next keep-relaunch).
+   */
+  clearedDefault?: boolean
   /** Short toast for answerCallbackQuery. */
   answer: string
   /** Replacement dashboard (message edit). */
@@ -872,7 +879,7 @@ export async function handleModelMenuCallback(
       answer: `Switching to ${friendlyName} — restarting (~30s)`,
       reply: await menuWithBannerStatic(
         deps,
-        `🔄 Switching session to **${deps.escapeHtml(friendlyName)}** — restarting (~30s). _Session-only; reverts to the configured default on the next restart._`,
+        `🔄 Switching session to **${deps.escapeHtml(friendlyName)}** — restarting (~30s).\n${PERSIST_NOTE}`,
       ),
       selectedModel: srName,
     }
@@ -949,11 +956,16 @@ export async function handleModelMenuCallback(
   // "Default (recommended)". If neither resolves, record nothing rather than lie.
   const token = canonicalClaudeToken(target.label)
   const selectedModel = sessionModelFromConfirmation(result.confirmation) ?? token ?? undefined
+  // The "Default (recommended)" row has no derivable token BY DESIGN — a
+  // confirmed switch to it means "back on the configured default", which the
+  // gateway must translate into clearing the sticky override.
+  const clearedDefault = token == null && /^default\b/i.test(target.label.trim())
   return {
     answer: deps.escapeHtml(result.confirmation),
     reply: await menuWithBanner(deps, `✅ ${deps.escapeHtml(result.confirmation)}`),
     ...(selectedModel ? { selectedModel } : {}),
     ...(token ? { selectedModelToken: token } : {}),
+    ...(clearedDefault ? { clearedDefault: true } : {}),
   }
 }
 
@@ -1030,7 +1042,7 @@ export function isKeptModelConfirmation(confirmation: string): boolean {
 
 /**
  * Normalize a picker ROW LABEL to a canonical `claude --model` token suitable
- * for the `.session-model-override` carrier (aliases and full `claude-*` ids —
+ * for the durable `.session-model` override (aliases and full `claude-*` ids —
  * NOT display strings like "Default (recommended)" or "Opus 4.8", which the CLI
  * flag rejects). Returns null when the label is a pure display label with no
  * derivable token: for the "Default" row that correctly means "boot the