switchroom 0.12.23 → 0.12.24

package/dist/cli/switchroom.js

@@ -47247,8 +47247,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.12.23";
-var COMMIT_SHA = "6c99950";
+var VERSION = "0.12.24";
+var COMMIT_SHA = "7ab1329";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.12.23",
+  "version": "0.12.24",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -27253,32 +27253,32 @@ function formatAuthQuotaLine(acc, now = Date.now()) {
   }
   return null;
 }
-function renderAuthLine(state3, agentName3, now = Date.now()) {
-  if (!state3 || state3.accounts.length === 0)
+function renderAuthLine(state4, agentName3, now = Date.now()) {
+  if (!state4 || state4.accounts.length === 0)
     return [];
-  const agentEntry = state3.agents.find((a) => a.name === agentName3);
-  const activeLabel = agentEntry?.override ?? agentEntry?.account ?? state3.active;
+  const agentEntry = state4.agents.find((a) => a.name === agentName3);
+  const activeLabel = agentEntry?.override ?? agentEntry?.account ?? state4.active;
   const seen = new Set;
   const order = [];
   if (activeLabel) {
     order.push(activeLabel);
     seen.add(activeLabel);
   }
-  for (const label of state3.fallback_order) {
+  for (const label of state4.fallback_order) {
     if (!seen.has(label)) {
       order.push(label);
       seen.add(label);
     }
   }
-  for (const acc of state3.accounts) {
+  for (const acc of state4.accounts) {
     if (!seen.has(acc.label)) {
       order.push(acc.label);
       seen.add(acc.label);
     }
   }
-  const byLabel = new Map(state3.accounts.map((a) => [a.label, a]));
+  const byLabel = new Map(state4.accounts.map((a) => [a.label, a]));
   const rows = [];
-  rows.push(`<b>Accounts (${state3.accounts.length})</b>`);
+  rows.push(`<b>Accounts (${state4.accounts.length})</b>`);
   for (const label of order) {
     const acc = byLabel.get(label);
     if (!acc)
@@ -27540,15 +27540,15 @@ function uptimeMsForStarttime(starttimeTicks, fs2 = realProcFs) {
     return null;
   }
 }
-function nextStepForAgentState(agentName3, state3) {
-  if (state3 === "failed") {
+function nextStepForAgentState(agentName3, state4) {
+  if (state4 === "failed") {
     return `Service failed \u2014 inspect with \`journalctl --user -u switchroom-${agentName3} -n 100\` then \`switchroom agent restart ${agentName3}\``;
   }
-  if (state3 === "inactive") {
+  if (state4 === "inactive") {
     return `Service inactive \u2014 start with \`switchroom agent start ${agentName3}\` (or \`systemctl --user start switchroom-${agentName3}\`)`;
   }
-  if (state3 === "deactivating" || state3 === "activating" || state3 === "auto-restart") {
-    return `Service is in a transient \`${state3}\` state \u2014 re-check with \`switchroom agent status ${agentName3}\` in a few seconds`;
+  if (state4 === "deactivating" || state4 === "activating" || state4 === "auto-restart") {
+    return `Service is in a transient \`${state4}\` state \u2014 re-check with \`switchroom agent status ${agentName3}\` in a few seconds`;
   }
   return `Inspect with \`journalctl --user -u switchroom-${agentName3} -n 100\``;
 }
@@ -27670,8 +27670,8 @@ async function probeAgentProcess(agentName3, opts = {}) {
       if ("error" in snapshot) {
         return { status: "fail", label: "Agent", detail: snapshot.error };
       }
-      const { state: state3, kv } = snapshot;
-      if (state3 === "active") {
+      const { state: state4, kv } = snapshot;
+      if (state4 === "active") {
         let pid = kv["MainPID"] ?? "?";
         if (opts.tmuxSupervisor) {
           const resolved = await resolveTmuxSupervisorPid(agentName3, execFileFn);
@@ -27685,10 +27685,10 @@ async function probeAgentProcess(agentName3, opts = {}) {
       }
       const elapsedMs = Date.now() - startMs;
       if (elapsedMs >= retryMaxMs) {
-        const isTransient = state3 === "deactivating" || state3 === "activating" || state3 === "auto-restart";
+        const isTransient = state4 === "deactivating" || state4 === "activating" || state4 === "auto-restart";
         const status = isTransient ? "degraded" : "fail";
-        const nextStep = nextStepForAgentState(agentName3, state3);
-        return { status, label: "Agent", detail: `service ${state3}`, ...nextStep ? { nextStep } : {} };
+        const nextStep = nextStepForAgentState(agentName3, state4);
+        return { status, label: "Agent", detail: `service ${state4}`, ...nextStep ? { nextStep } : {} };
       }
       await sleep2(retryIntervalMs);
     }
@@ -27708,8 +27708,8 @@ async function* watchAgentProcess(agentName3, opts = {}) {
   const now = opts.nowImpl ?? (() => Date.now());
   const startMs = now();
   let lastYieldedDetail = null;
-  async function toProbeResult(state3, kv, withinWindow) {
-    if (state3 === "active") {
+  async function toProbeResult(state4, kv, withinWindow) {
+    if (state4 === "active") {
       let pid = kv["MainPID"] ?? "?";
       if (opts.tmuxSupervisor) {
         const resolved = await resolveTmuxSupervisorPid(agentName3, execFileFn);
@@ -27722,15 +27722,15 @@ async function* watchAgentProcess(agentName3, opts = {}) {
       return { status: "ok", label: "Agent", detail: parts.join(" \u00b7 ") };
     }
     if (withinWindow) {
-      if (state3 === "failed") {
+      if (state4 === "failed") {
         return { status: "fail", label: "Agent", detail: "service failed" };
       }
       return { status: "degraded", label: "Agent", detail: "service starting" };
     }
-    const isTransient = state3 === "deactivating" || state3 === "activating" || state3 === "auto-restart" || state3 === "inactive";
+    const isTransient = state4 === "deactivating" || state4 === "activating" || state4 === "auto-restart" || state4 === "inactive";
     const status = isTransient ? "degraded" : "fail";
-    const nextStep = nextStepForAgentState(agentName3, state3);
-    return { status, label: "Agent", detail: `service ${state3}`, ...nextStep ? { nextStep } : {} };
+    const nextStep = nextStepForAgentState(agentName3, state4);
+    return { status, label: "Agent", detail: `service ${state4}`, ...nextStep ? { nextStep } : {} };
   }
   while (true) {
     const elapsedMs = now() - startMs;
@@ -29553,14 +29553,14 @@ function switchPriority2(s) {
 function escapeHtml12(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
-function buildSnapshotsFromState2(state3, quotas) {
+function buildSnapshotsFromState2(state4, quotas) {
   const out = [];
-  for (let i = 0;i < state3.accounts.length; i++) {
-    const acc = state3.accounts[i];
+  for (let i = 0;i < state4.accounts.length; i++) {
+    const acc = state4.accounts[i];
     const q = quotas[i];
     out.push({
       label: acc.label,
-      isActive: acc.label === state3.active,
+      isActive: acc.label === state4.active,
       quota: q && q.ok ? q.data : null,
       quotaError: q && !q.ok ? q.reason : undefined,
       expiresAtMs: acc.expiresAt
@@ -43814,6 +43814,237 @@ function chatKeyWithSuffix(chatId, threadId, suffix) {
   return `${chatKey(chatId, threadId)}:${suffix}`;
 }
 
+// gateway/inbound-delivery-machine.ts
+function initialState() {
+  return {
+    global: { kind: "bridge_dead" },
+    perKey: new Map
+  };
+}
+var TURN_TTL_MS = 300000;
+var OUTBOUND_RECENT_MS = 60000;
+function emptyPerKey() {
+  return { turnStartedAt: null, lastOutboundAt: null };
+}
+function updatePerKey(state3, key, update) {
+  const prior = state3.perKey.get(key) ?? emptyPerKey();
+  const next = update(prior);
+  const m = new Map(state3.perKey);
+  if (next.turnStartedAt == null && next.lastOutboundAt == null) {
+    m.delete(key);
+  } else {
+    m.set(key, next);
+  }
+  return { ...state3, perKey: m };
+}
+function chatIdOfKey(key) {
+  const idx = key.indexOf(":");
+  return idx === -1 ? key : key.slice(0, idx);
+}
+function sweepSiblings(state3, chatId, exceptKey) {
+  const effects = [];
+  let next = state3;
+  for (const [k, v] of state3.perKey) {
+    if (k === exceptKey)
+      continue;
+    if (chatIdOfKey(k) !== chatId)
+      continue;
+    if (v.turnStartedAt == null)
+      continue;
+    effects.push({ kind: "clearTurnStarted", key: k });
+    next = updatePerKey(next, k, (p) => ({ ...p, turnStartedAt: null }));
+  }
+  return { state: next, effects };
+}
+function transition(state3, event) {
+  switch (event.kind) {
+    case "bridgeUp": {
+      if (state3.global.kind !== "bridge_dead") {
+        return { state: state3, effects: [{ kind: "logTrace", stage: "bridgeUp_redundant" }] };
+      }
+      return {
+        state: { ...state3, global: { kind: "bridge_alive_idle" } },
+        effects: [
+          { kind: "redeliverPersistedPermVerdicts" },
+          { kind: "drainBuffer" },
+          { kind: "logTrace", stage: "bridge_recover" }
+        ]
+      };
+    }
+    case "bridgeDown": {
+      return {
+        state: { ...state3, global: { kind: "bridge_dead" } },
+        effects: [{ kind: "logTrace", stage: "bridge_flap" }]
+      };
+    }
+    case "inbound": {
+      const isSteering = event.msg.isSteering;
+      const inTurn = state3.global.kind === "bridge_alive_in_turn";
+      const alive = state3.global.kind !== "bridge_dead";
+      if (!alive) {
+        return {
+          state: state3,
+          effects: [
+            { kind: "bufferInbound", key: event.key, msg: event.msg },
+            { kind: "persistInbound", key: event.key, msg: event.msg },
+            { kind: "logTrace", stage: "inbound_bridge_dead_buffer", key: event.key }
+          ]
+        };
+      }
+      if (inTurn && !isSteering) {
+        return {
+          state: state3,
+          effects: [
+            { kind: "bufferInbound", key: event.key, msg: event.msg },
+            { kind: "persistInbound", key: event.key, msg: event.msg },
+            { kind: "logTrace", stage: "inbound_held_mid_turn", key: event.key, metadata: { msgId: event.msg.msgId } }
+          ]
+        };
+      }
+      if (isSteering) {
+        return {
+          state: state3,
+          effects: [
+            { kind: "deliverToBridge", key: event.key, msg: event.msg },
+            { kind: "logTrace", stage: "steer_delivered_mid_turn", key: event.key }
+          ]
+        };
+      }
+      const next = {
+        global: { kind: "bridge_alive_in_turn", activeTurn: event.key },
+        perKey: state3.perKey
+      };
+      return {
+        state: updatePerKey(next, event.key, (p) => ({ ...p, turnStartedAt: event.at })),
+        effects: [
+          { kind: "setTurnStarted", key: event.key, at: event.at },
+          { kind: "deliverToBridge", key: event.key, msg: event.msg },
+          { kind: "logTrace", stage: "fresh_turn_deliver", key: event.key, metadata: { msgId: event.msg.msgId } }
+        ]
+      };
+    }
+    case "turnStart": {
+      const next = state3.global.kind === "bridge_alive_in_turn" ? state3 : { ...state3, global: { kind: "bridge_alive_in_turn", activeTurn: event.key } };
+      return {
+        state: updatePerKey(next, event.key, (p) => ({ ...p, turnStartedAt: event.at })),
+        effects: [
+          { kind: "setTurnStarted", key: event.key, at: event.at },
+          { kind: "logTrace", stage: "turn_start", key: event.key }
+        ]
+      };
+    }
+    case "turnEnd": {
+      const chatId = chatIdOfKey(event.key);
+      const stateAfterClear = updatePerKey(state3, event.key, (p) => ({
+        turnStartedAt: null,
+        lastOutboundAt: event.outboundEmitted ? event.at : p.lastOutboundAt
+      }));
+      const sweep = sweepSiblings(stateAfterClear, chatId, event.key);
+      const wasActive = state3.global.kind === "bridge_alive_in_turn" && state3.global.activeTurn === event.key;
+      const next = wasActive ? { ...sweep.state, global: { kind: "bridge_alive_idle" } } : sweep.state;
+      const effects = [
+        { kind: "clearTurnStarted", key: event.key },
+        ...sweep.effects
+      ];
+      if (event.outboundEmitted) {
+        effects.push({ kind: "noteOutbound", key: event.key, at: event.at });
+      }
+      effects.push({ kind: "drainBuffer" });
+      effects.push({ kind: "logTrace", stage: "turn_complete", key: event.key, metadata: { outboundEmitted: event.outboundEmitted } });
+      return { state: next, effects };
+    }
+    case "modelOutbound": {
+      return {
+        state: updatePerKey(state3, event.key, (p) => ({ ...p, lastOutboundAt: event.at })),
+        effects: [
+          { kind: "noteOutbound", key: event.key, at: event.at }
+        ]
+      };
+    }
+    case "permVerdict": {
+      const alive = state3.global.kind !== "bridge_dead";
+      if (alive) {
+        return {
+          state: state3,
+          effects: [
+            { kind: "deliverPermVerdict", verdict: event.verdict },
+            { kind: "logTrace", stage: "perm_verdict_delivered" }
+          ]
+        };
+      }
+      return {
+        state: state3,
+        effects: [
+          { kind: "persistPermVerdict", verdict: event.verdict },
+          { kind: "logTrace", stage: "perm_verdict_persisted" }
+        ]
+      };
+    }
+    case "tick": {
+      const effects = [];
+      let next = state3;
+      for (const [k, v] of state3.perKey) {
+        if (v.turnStartedAt == null)
+          continue;
+        const age = event.now - v.turnStartedAt;
+        if (age <= TURN_TTL_MS) {
+          continue;
+        }
+        const recentOutbound = v.lastOutboundAt != null && event.now - v.lastOutboundAt < OUTBOUND_RECENT_MS;
+        if (recentOutbound) {
+          effects.push({ kind: "logTrace", stage: "fallback_suppressed", key: k, metadata: { recentOutboundMs: event.now - (v.lastOutboundAt ?? 0) } });
+          continue;
+        }
+        effects.push({ kind: "firePoke", key: k, level: "fallback" });
+        effects.push({ kind: "clearTurnStarted", key: k });
+        next = updatePerKey(next, k, (p) => ({ ...p, turnStartedAt: null }));
+        if (next.global.kind === "bridge_alive_in_turn" && next.global.activeTurn === k) {
+          next = { ...next, global: { kind: "bridge_alive_idle" } };
+        }
+      }
+      return { state: next, effects };
+    }
+  }
+}
+
+// gateway/inbound-delivery-machine-shadow.ts
+var state3 = initialState();
+var enabled2 = process.env.SWITCHROOM_DELIVERY_MACHINE_SHADOW !== "0";
+function shadowEmit(event) {
+  if (!enabled2)
+    return [];
+  try {
+    const result = transition(state3, event);
+    state3 = result.state;
+    const effectKinds = result.effects.map((e) => e.kind).join(",");
+    const eventDetail = formatEventDetail(event);
+    process.stderr.write(`gw-trace shadow event=${event.kind}${eventDetail} effects=[${effectKinds}] global=${state3.global.kind} perKeySize=${state3.perKey.size}
+`);
+    return result.effects;
+  } catch (err) {
+    process.stderr.write(`gw-trace shadow ERROR event=${event.kind} err=${err instanceof Error ? err.message : String(err)}
+`);
+    return [];
+  }
+}
+function formatEventDetail(event) {
+  switch (event.kind) {
+    case "inbound":
+      return ` key=${event.key} msg=${event.msg.msgId} steer=${event.msg.isSteering}`;
+    case "turnStart":
+    case "turnEnd":
+      return ` key=${event.key}${event.kind === "turnEnd" ? ` outbound=${event.outboundEmitted}` : ""}`;
+    case "permVerdict":
+      return ` req=${event.verdict.requestId} behavior=${event.verdict.behavior}`;
+    case "modelOutbound":
+      return ` key=${event.key}`;
+    case "bridgeUp":
+    case "bridgeDown":
+    case "tick":
+      return "";
+  }
+}
+
 // gateway/vault-grant-inbound-builders.ts
 function buildVaultGrantApprovedInbound(opts) {
   const ts = opts.nowMs ?? Date.now();
@@ -45248,7 +45479,7 @@ function extractToolResultErrorText(content) {
   }
   return "";
 }
-function projectSubagentLine(line, agentId, state3) {
+function projectSubagentLine(line, agentId, state4) {
   let obj;
   try {
     obj = JSON.parse(line);
@@ -45261,8 +45492,8 @@ function projectSubagentLine(line, agentId, state3) {
   if (type === "user") {
     const message = obj.message;
     const content = message?.content;
-    if (!state3.hasEmittedStart) {
-      state3.hasEmittedStart = true;
+    if (!state4.hasEmittedStart) {
+      state4.hasEmittedStart = true;
       let promptText = "";
       if (typeof content === "string") {
         promptText = content;
@@ -47046,10 +47277,10 @@ function loadCreditState(stateDir) {
   } catch {}
   return emptyCreditState();
 }
-function saveCreditState(stateDir, state3) {
+function saveCreditState(stateDir, state4) {
   mkdirSync15(stateDir, { recursive: true });
   const path = join27(stateDir, STATE_FILE);
-  writeFileSync17(path, JSON.stringify(state3, null, 2) + `
+  writeFileSync17(path, JSON.stringify(state4, null, 2) + `
 `, { mode: 384 });
 }
 
@@ -47126,11 +47357,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.12.23";
-var COMMIT_SHA = "6c99950";
-var COMMIT_DATE = "2026-05-20T04:16:33Z";
-var LATEST_PR = 1580;
-var COMMITS_AHEAD_OF_TAG = 1;
+var VERSION = "0.12.24";
+var COMMIT_SHA = "7ab1329";
+var COMMIT_DATE = "2026-05-20T14:48:10+10:00";
+var LATEST_PR = 1582;
+var COMMITS_AHEAD_OF_TAG = 3;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -48079,6 +48310,7 @@ function streamKey3(chatId, threadId) {
   return chatKey(chatId, threadId);
 }
 function purgeReactionTracking(key) {
+  shadowEmit({ kind: "turnEnd", key, at: Date.now(), outboundEmitted: true });
   const msgInfo = activeReactionMsgIds.get(key);
   activeStatusReactions.delete(key);
   activeReactionMsgIds.delete(key);
@@ -49002,6 +49234,7 @@ var ipcServer = createIpcServer({
   onClientRegistered(client3) {
     process.stderr.write(`telegram gateway: bridge registered \u2014 agent=${client3.agentName}
 `);
+    shadowEmit({ kind: "bridgeUp", at: Date.now() });
     client3.send({ type: "status", status: "agent_connected" });
     if (client3.agentName != null) {
       const pending = pendingInboundBuffer.drain(client3.agentName);
@@ -49095,6 +49328,7 @@ var ipcServer = createIpcServer({
   onClientDisconnected(client3) {
     process.stderr.write(`telegram gateway: bridge disconnected \u2014 agent=${client3.agentName}
 `);
+    shadowEmit({ kind: "bridgeDown", at: Date.now() });
     flushOnAgentDisconnect({
       agentName: client3.agentName,
       activeStatusReactions,
@@ -51057,7 +51291,7 @@ function handleSessionEvent(ev) {
 }
 function handlePtyPartial(text) {
   const turn = currentTurn;
-  const state3 = {
+  const state4 = {
     currentSessionChatId: turn?.sessionChatId ?? null,
     currentSessionThreadId: turn?.sessionThreadId,
     pendingPtyPartial: pendingPtyPartial != null ? { text: pendingPtyPartial } : null,
@@ -51066,7 +51300,7 @@ function handlePtyPartial(text) {
     suppressPtyPreview,
     lastPtyPreviewByChat
   };
-  handlePtyPartialPure(text, state3, {
+  handlePtyPartialPure(text, state4, {
     bot,
     retry: robustApiCall,
     renderText: markdownToHtml,
@@ -51082,7 +51316,7 @@ function handlePtyPartial(text) {
     },
     writeError: (line) => process.stderr.write(line)
   });
-  pendingPtyPartial = state3.pendingPtyPartial?.text ?? null;
+  pendingPtyPartial = state4.pendingPtyPartial?.text ?? null;
 }
 var gateDenyLastLoggedAt = new Map;
 var GATE_DENY_LOG_WINDOW_MS = 60000;
@@ -51275,6 +51509,17 @@ async function handleInbound(ctx, text, downloadImage, attachment) {
     return;
   }
   const inboundReceivedAt = Date.now();
+  const _shadowKey = statusKey(ctx.chat?.id != null ? String(ctx.chat.id) : "0", ctx.message?.message_thread_id);
+  shadowEmit({
+    kind: "inbound",
+    key: _shadowKey,
+    msg: {
+      msgId: ctx.message?.message_id ?? 0,
+      isSteering: false,
+      payload: null
+    },
+    at: Date.now()
+  });
   const turnInFlightAtReceipt = activeTurnStartedAt.size > 0;
   const access = result.access;
   const from = ctx.from;
@@ -53140,15 +53385,15 @@ async function doFireFleetAutoFallback(triggerAgent) {
 `);
       return false;
     }
-    const state3 = await client3.listState();
-    const probeResp = state3.accounts.length > 0 ? await client3.probeQuota(state3.accounts.map((a) => a.label)).catch(() => ({ results: [] })) : { results: [] };
-    const quotas = state3.accounts.map((a) => {
+    const state4 = await client3.listState();
+    const probeResp = state4.accounts.length > 0 ? await client3.probeQuota(state4.accounts.map((a) => a.label)).catch(() => ({ results: [] })) : { results: [] };
+    const quotas = state4.accounts.map((a) => {
       const hit = probeResp.results.find((r) => r.label === a.label);
       return hit?.result ?? { ok: false, reason: "broker returned no result for account" };
     });
     const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? "UTC";
     const outcome = await runFleetAutoFallback({
-      state: state3,
+      state: state4,
       quotas,
       setActive: (label) => client3.setActive(label),
       triggerAgent,
@@ -53334,9 +53579,9 @@ async function probeQuotaForBootCard(agent, timeoutMs) {
     const client3 = await getAuthBrokerClient(agent);
     if (!client3)
       return null;
-    const state3 = await client3.listState();
-    const entry = state3.agents.find((a) => a.name === agent);
-    const label = entry?.override ?? entry?.account ?? state3.active;
+    const state4 = await client3.listState();
+    const entry = state4.agents.find((a) => a.name === agent);
+    const label = entry?.override ?? entry?.account ?? state4.active;
     if (!label)
       return null;
     const { results } = await client3.probeQuota([label], timeoutMs);
@@ -53853,34 +54098,34 @@ Which keys for <code>${escapeHtmlForTg(agent)}</code>?
     startedAt: Date.now()
   });
 }
-async function grantWizardStep3(ctx, chatId, state3) {
+async function grantWizardStep3(ctx, chatId, state4) {
   const kb = buildGrantDurationKeyboard();
-  const keyList = state3.selectedKeys.map((k) => `\u2022 <code>${escapeHtmlForTg(k)}</code>`).join(`
+  const keyList = state4.selectedKeys.map((k) => `\u2022 <code>${escapeHtmlForTg(k)}</code>`).join(`
 `);
   const text = `<b>Grant capability token \u2014 Step 3/3</b>
 
-Keys for <code>${escapeHtmlForTg(state3.agent)}</code>:
+Keys for <code>${escapeHtmlForTg(state4.agent)}</code>:
 ${keyList}
 
 How long should this grant be valid?`;
-  const msgId = state3.wizardMsgId;
+  const msgId = state4.wizardMsgId;
   if (msgId != null) {
     await ctx.api.editMessageText(chatId, msgId, text, { parse_mode: "HTML", reply_markup: kb }).catch(() => {});
   } else {
     const sent = await switchroomReply(ctx, text, { html: true, reply_markup: kb });
-    state3.wizardMsgId = sent?.message_id;
+    state4.wizardMsgId = sent?.message_id;
   }
-  pendingVaultOps.set(chatId, { ...state3, step: "duration" });
+  pendingVaultOps.set(chatId, { ...state4, step: "duration" });
 }
-async function grantWizardConfirm(ctx, chatId, state3) {
+async function grantWizardConfirm(ctx, chatId, state4) {
   const kb = buildGrantConfirmKeyboard();
-  const expiresLabel = formatGrantExpiry(state3.ttlSeconds);
-  const keyList = state3.selectedKeys.map((k) => `\u2022 <code>${escapeHtmlForTg(k)}</code>`).join(`
+  const expiresLabel = formatGrantExpiry(state4.ttlSeconds);
+  const keyList = state4.selectedKeys.map((k) => `\u2022 <code>${escapeHtmlForTg(k)}</code>`).join(`
 `);
   const text = [
     "<b>Confirm grant</b>",
     "",
-    `Agent: <code>${escapeHtmlForTg(state3.agent)}</code>`,
+    `Agent: <code>${escapeHtmlForTg(state4.agent)}</code>`,
     `Keys:
 ${keyList}`,
     `Expires: <b>${escapeHtmlForTg(expiresLabel)}</b>`,
@@ -53888,34 +54133,34 @@ ${keyList}`,
     "Tap <b>Generate</b> to mint the token."
   ].join(`
 `);
-  const msgId = state3.wizardMsgId;
+  const msgId = state4.wizardMsgId;
   if (msgId != null) {
     await ctx.api.editMessageText(chatId, msgId, text, { parse_mode: "HTML", reply_markup: kb }).catch(() => {});
   } else {
     const sent = await switchroomReply(ctx, text, { html: true, reply_markup: kb });
-    state3.wizardMsgId = sent?.message_id;
+    state4.wizardMsgId = sent?.message_id;
   }
-  const kernelRequestId = await mintGrantWizardKernelRequest(state3.agent, loadAccess().allowFrom, state3.selectedKeys, state3.ttlSeconds ?? null);
+  const kernelRequestId = await mintGrantWizardKernelRequest(state4.agent, loadAccess().allowFrom, state4.selectedKeys, state4.ttlSeconds ?? null);
   pendingVaultOps.set(chatId, {
-    ...state3,
+    ...state4,
     step: "confirm",
     expiresLabel,
-    kernel_request_id: kernelRequestId ?? state3.kernel_request_id
+    kernel_request_id: kernelRequestId ?? state4.kernel_request_id
   });
 }
-async function executeGrantWizard(ctx, chatId, state3) {
+async function executeGrantWizard(ctx, chatId, state4) {
   pendingVaultOps.delete(chatId);
-  await recordGrantWizardKernelDecision(state3.kernel_request_id, "allow_once", ctx.from?.id ?? 0, loadAccess().allowFrom);
+  await recordGrantWizardKernelDecision(state4.kernel_request_id, "allow_once", ctx.from?.id ?? 0, loadAccess().allowFrom);
   try {
-    assertSafeAgentName(state3.agent);
+    assertSafeAgentName(state4.agent);
   } catch {
     return;
   }
   const result = await mintGrantViaBroker({
-    agent: state3.agent,
-    keys: state3.selectedKeys,
-    ttl_seconds: state3.ttlSeconds ?? null,
-    description: state3.description
+    agent: state4.agent,
+    keys: state4.selectedKeys,
+    ttl_seconds: state4.ttlSeconds ?? null,
+    description: state4.description
   });
   if (result.kind === "unreachable") {
     await switchroomReply(ctx, `\uD83D\uDD34 Broker unreachable: ${escapeHtmlForTg(result.msg)}`, { html: true });
@@ -53926,16 +54171,16 @@ async function executeGrantWizard(ctx, chatId, state3) {
     return;
   }
   const { token, id } = result;
-  const tokenPath = join32(homedir12(), ".switchroom", "agents", state3.agent, ".vault-token");
+  const tokenPath = join32(homedir12(), ".switchroom", "agents", state4.agent, ".vault-token");
   try {
-    mkdirSync21(join32(homedir12(), ".switchroom", "agents", state3.agent), { recursive: true });
+    mkdirSync21(join32(homedir12(), ".switchroom", "agents", state4.agent), { recursive: true });
     writeFileSync21(tokenPath, token, { mode: 384 });
   } catch (err) {
     await switchroomReply(ctx, `<b>Grant created but token write failed:</b> ${escapeHtmlForTg(String(err))}`, { html: true });
     return;
   }
-  const msgId = state3.wizardMsgId;
-  const successText = `\u2705 Grant <code>${escapeHtmlForTg(id)}</code> created. Written to <code>~/.switchroom/agents/${escapeHtmlForTg(state3.agent)}/.vault-token</code>`;
+  const msgId = state4.wizardMsgId;
+  const successText = `\u2705 Grant <code>${escapeHtmlForTg(id)}</code> created. Written to <code>~/.switchroom/agents/${escapeHtmlForTg(state4.agent)}/.vault-token</code>`;
   if (msgId != null) {
     await finalizeCallback(ctx, {
       ackText: "\u2705 Grant created",
@@ -54029,59 +54274,59 @@ Keys: <code>${escapeHtmlForTg(grant.key_allow.join(", "))}</code>`;
     await ackSilently();
     return;
   }
-  const state3 = pendingVaultOps.get(chatId);
-  if (!state3 || state3.kind !== "grant-wizard") {
+  const state4 = pendingVaultOps.get(chatId);
+  if (!state4 || state4.kind !== "grant-wizard") {
     await ctx.editMessageText("\u26A0\uFE0F Wizard session expired. Run /vault grant to start again.").catch(() => {});
     await ackSilently();
     return;
   }
   if (data.startsWith("vg:agent:")) {
     const agent = data.slice("vg:agent:".length);
-    const msgId = ctx.callbackQuery?.message?.message_id ?? state3.wizardMsgId;
+    const msgId = ctx.callbackQuery?.message?.message_id ?? state4.wizardMsgId;
     await grantWizardStep2(ctx, chatId, agent, msgId);
     await ackSilently();
     return;
   }
   if (data.startsWith("vg:key:")) {
     const key = data.slice("vg:key:".length);
-    if (state3.step !== "keys") {
+    if (state4.step !== "keys") {
       await ackSilently();
       return;
     }
-    const selectedSet = new Set(state3.selectedKeys ?? []);
+    const selectedSet = new Set(state4.selectedKeys ?? []);
     if (selectedSet.has(key)) {
       selectedSet.delete(key);
     } else {
       selectedSet.add(key);
     }
-    const updatedState = { ...state3, selectedKeys: [...selectedSet] };
+    const updatedState = { ...state4, selectedKeys: [...selectedSet] };
     pendingVaultOps.set(chatId, updatedState);
-    const kb = buildGrantKeysKeyboard(state3.availableKeys ?? [], selectedSet);
+    const kb = buildGrantKeysKeyboard(state4.availableKeys ?? [], selectedSet);
     await ctx.editMessageReplyMarkup({ reply_markup: kb }).catch(() => {});
     await ackSilently();
     return;
   }
   if (data === "vg:keys-continue") {
-    if (state3.step !== "keys") {
+    if (state4.step !== "keys") {
       await ackSilently();
       return;
     }
-    if (!state3.selectedKeys || state3.selectedKeys.length === 0) {
+    if (!state4.selectedKeys || state4.selectedKeys.length === 0) {
       await ctx.answerCallbackQuery({ text: "Select at least one key." }).catch(() => {});
       return;
     }
-    await grantWizardStep3(ctx, chatId, state3);
+    await grantWizardStep3(ctx, chatId, state4);
     await ackSilently();
     return;
   }
   if (data.startsWith("vg:dur:")) {
-    if (state3.step !== "duration") {
+    if (state4.step !== "duration") {
       await ackSilently();
       return;
     }
     const dur = data.slice("vg:dur:".length);
     if (dur === "custom") {
-      pendingVaultOps.set(chatId, { ...state3, awaitingCustomDuration: true });
+      pendingVaultOps.set(chatId, { ...state4, awaitingCustomDuration: true });
       const msg = ctx.callbackQuery?.message;
       if (msg && "text" in msg && msg.text) {
         await ctx.editMessageText(escapeHtmlForTg(msg.text) + `
@@ -54103,27 +54348,27 @@ Keys: <code>${escapeHtmlForTg(grant.key_allow.join(", "))}</code>`;
         return;
       }
     }
-    const newState = { ...state3, ttlSeconds, awaitingCustomDuration: false };
+    const newState = { ...state4, ttlSeconds, awaitingCustomDuration: false };
     await grantWizardConfirm(ctx, chatId, newState);
     await ackSilently();
     return;
   }
   if (data === "vg:back:duration") {
-    if (state3.step !== "duration") {
+    if (state4.step !== "duration") {
       await ackSilently();
       return;
     }
-    const msgId = state3.wizardMsgId;
-    await grantWizardStep2(ctx, chatId, state3.agent, msgId);
+    const msgId = state4.wizardMsgId;
+    await grantWizardStep2(ctx, chatId, state4.agent, msgId);
     await ackSilently();
     return;
   }
   if (data === "vg:generate") {
-    if (state3.step !== "confirm") {
+    if (state4.step !== "confirm") {
       await ackSilently();
       return;
     }
-    await executeGrantWizard(ctx, chatId, state3);
+    await executeGrantWizard(ctx, chatId, state4);
     await ackSilently();
     return;
   }
@@ -54361,15 +54606,15 @@ async function handleAuthDashboardCallback(ctx) {
         } catch {}
         return;
       }
-      const state3 = await client3.listState();
-      const probeResp = state3.accounts.length > 0 ? await client3.probeQuota(state3.accounts.map((a) => a.label)).catch(() => ({ results: [] })) : { results: [] };
-      const quotas = state3.accounts.map((a) => {
+      const state4 = await client3.listState();
+      const probeResp = state4.accounts.length > 0 ? await client3.probeQuota(state4.accounts.map((a) => a.label)).catch(() => ({ results: [] })) : { results: [] };
+      const quotas = state4.accounts.map((a) => {
         const hit = probeResp.results.find((r) => r.label === a.label);
         return hit?.result ?? { ok: false, reason: "broker returned no result for account" };
       });
       const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? "UTC";
       const { renderAuthSnapshotFormat2: renderAuthSnapshotFormat23, buildSnapshotsFromState: buildSnapshotsFromState3, buildSnapshotKeyboard: buildSnapshotKeyboard3 } = await Promise.resolve().then(() => (init_auth_snapshot_format(), exports_auth_snapshot_format));
-      const snapshots = buildSnapshotsFromState3(state3, quotas);
+      const snapshots = buildSnapshotsFromState3(state4, quotas);
       const text = renderAuthSnapshotFormat23(snapshots, {
         tz,
         now: new Date,
@@ -54757,16 +55002,16 @@ bot.command("usage", async (ctx) => {
   try {
     const client3 = await getAuthBrokerClient(currentAgent);
     if (client3) {
-      const state3 = await client3.listState();
-      if (state3.accounts.length > 0) {
-        const probeResp = await client3.probeQuota(state3.accounts.map((a) => a.label)).catch(() => ({ results: [] }));
-        const quotas = state3.accounts.map((a) => {
+      const state4 = await client3.listState();
+      if (state4.accounts.length > 0) {
+        const probeResp = await client3.probeQuota(state4.accounts.map((a) => a.label)).catch(() => ({ results: [] }));
+        const quotas = state4.accounts.map((a) => {
           const hit = probeResp.results.find((r) => r.label === a.label);
           return hit?.result ?? { ok: false, reason: "broker returned no result for account" };
         });
         const { renderAuthSnapshotFormat2: renderAuthSnapshotFormat23, buildSnapshotsFromState: buildSnapshotsFromState3 } = await Promise.resolve().then(() => (init_auth_snapshot_format(), exports_auth_snapshot_format));
         const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? "UTC";
-        const snapshots = buildSnapshotsFromState3(state3, quotas);
+        const snapshots = buildSnapshotsFromState3(state4, quotas);
         const text = renderAuthSnapshotFormat23(snapshots, {
           tz,
           now: new Date,
@@ -55606,7 +55851,7 @@ function handleChecklistUpdate(ctx, kind) {
       const taskId = task.id != null ? String(task.id) : "?";
       const user = task.user;
       const userName = user?.username ?? (user?.id != null ? String(user.id) : "unknown");
-      const state3 = kind === "checklist_tasks_done" ? task.done === false ? "undone" : "done" : "added";
+      const state4 = kind === "checklist_tasks_done" ? task.done === false ? "undone" : "done" : "added";
       const inboundMsg = {
         type: "inbound",
         chatId: chat_id,
@@ -55614,20 +55859,20 @@ function handleChecklistUpdate(ctx, kind) {
         user: userName,
         userId: user?.id ?? 0,
         ts,
-        text: `(checklist task ${state3}: id=${taskId})`,
+        text: `(checklist task ${state4}: id=${taskId})`,
         meta: {
           chat_id,
           message_id,
           kind: "checklist_task_changed",
           task_id: taskId,
-          state: state3,
+          state: state4,
           user: userName,
           user_id: user?.id != null ? String(user.id) : "0",
           ts: new Date(ts * 1000).toISOString()
         }
       };
       ipcServer.broadcast(inboundMsg);
-      process.stderr.write(`telegram gateway: checklist ${kind}: chat_id=${chat_id} message_id=${message_id} task_id=${taskId} state=${state3} user=${userName}
+      process.stderr.write(`telegram gateway: checklist ${kind}: chat_id=${chat_id} message_id=${message_id} task_id=${taskId} state=${state4} user=${userName}
 `);
     }
   } catch (err) {

package/telegram-plugin/gateway/gateway.ts

@@ -254,6 +254,13 @@ import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import { chatKey, chatKeyWithSuffix } from './chat-key.js'
+// Phase 2b PR 2 — shadow mode. Each event-site below calls shadowEmit()
+// to record what the InboundDeliveryStateMachine PREDICTS the gateway
+// should do. Behavior unchanged in this PR — the imperative code below
+// still runs everything. PR 3 will cut over to executing the machine's
+// effects.
+import { shadowEmit } from './inbound-delivery-machine-shadow.js'
+import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
@@ -1265,6 +1272,13 @@ function streamKey(chatId: string, threadId?: number | null): string {
 }
 
 function purgeReactionTracking(key: string): void {
+  // Phase 2b shadow: turn end. The key was registered via setTurnStarted
+  // when the inbound arrived; purge is the canonical turn-end signal.
+  // outboundEmitted is approximated `true` here — refined in PR 3 to read
+  // from the per-turn `replyCalled` flag on `currentTurn`. Conservative
+  // shadow approximation is safe (only affects machine's lastOutboundAt
+  // tracking; can't drive incorrect behavior in shadow mode).
+  shadowEmit({ kind: 'turnEnd', key: key as _ChatKey, at: Date.now(), outboundEmitted: true })
   const msgInfo = activeReactionMsgIds.get(key)
   activeStatusReactions.delete(key)
   activeReactionMsgIds.delete(key)
@@ -3182,6 +3196,8 @@ const ipcServer: IpcServer = createIpcServer({
 
   onClientRegistered(client: IpcClient) {
     process.stderr.write(`telegram gateway: bridge registered — agent=${client.agentName}\n`)
+    // Phase 2b shadow: bridge up.
+    shadowEmit({ kind: 'bridgeUp', at: Date.now() })
     client.send({ type: 'status', status: 'agent_connected' })
 
     // #1150: drain any synthetic inbounds queued for this agent while
@@ -3307,6 +3323,8 @@ const ipcServer: IpcServer = createIpcServer({
 
   onClientDisconnected(client: IpcClient) {
     process.stderr.write(`telegram gateway: bridge disconnected — agent=${client.agentName}\n`)
+    // Phase 2b shadow: bridge down.
+    shadowEmit({ kind: 'bridgeDown', at: Date.now() })
 
     // Scope the flush to clients that actually registered as an agent.
     // Anonymous one-shot connections (e.g. recall.py's legacy
@@ -6637,6 +6655,23 @@ async function handleInbound(
   // network RTT) but not a user-perceived end-to-end measurement.
   const inboundReceivedAt = Date.now()
 
+  // Phase 2b shadow: inbound arrival. Emit BEFORE the snapshot/gate
+  // logic so the machine sees the event at the same point in time the
+  // imperative code would. The machine internally handles fresh-turn
+  // vs mid-turn — its decision will be visible in the gw-trace shadow
+  // line emitted to stderr.
+  const _shadowKey = statusKey(ctx.chat?.id != null ? String(ctx.chat.id) : '0', ctx.message?.message_thread_id) as _ChatKey
+  shadowEmit({
+    kind: 'inbound',
+    key: _shadowKey,
+    msg: {
+      msgId: ctx.message?.message_id ?? 0,
+      isSteering: false, // refined in PR 3 — for now shadow conservatively classifies as non-steering
+      payload: null,
+    },
+    at: Date.now(),
+  })
+
   // #1556 self-blocking fix (v0.12.22): snapshot the live turn-state
   // BEFORE the fresh-turn branch (line ~7357) sets activeTurnStartedAt
   // for THIS inbound. The #1556 delivery gate further down asks "is a

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

@@ -0,0 +1,117 @@
+/**
+ * InboundDeliveryStateMachine — SHADOW MODE wiring (Phase 2b PR 2).
+ *
+ * Per RFC `docs/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:
+ *
+ *   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.
+ *
+ * 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:
+ *
+ *   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.
+ *
+ * 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 {
+  type Effect,
+  type Event,
+  type State,
+  initialState,
+  transition,
+} from './inbound-delivery-machine.js'
+
+let state: State = initialState()
+const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_SHADOW !== '0'
+
+/**
+ * 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).
+ */
+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,
+  // 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 {
+    const result = transition(state, event)
+    state = result.state
+
+    // Single structured stderr line per event — grep-friendly and
+    // low volume (one line per gateway event, not per effect). The
+    // format matches gateway.ts's existing `tg-post method=...` shape
+    // so log aggregation can pick it up without a new parser.
+    const effectKinds = result.effects.map((e) => e.kind).join(',')
+    const eventDetail = formatEventDetail(event)
+    process.stderr.write(
+      `gw-trace shadow event=${event.kind}${eventDetail} effects=[${effectKinds}] global=${state.global.kind} perKeySize=${state.perKey.size}\n`,
+    )
+    return result.effects
+  } catch (err) {
+    process.stderr.write(
+      `gw-trace shadow ERROR event=${event.kind} err=${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return []
+  }
+}
+
+/** Compact event detail for the trace line — keeps the line one-line. */
+function formatEventDetail(event: Event): string {
+  switch (event.kind) {
+    case 'inbound':
+      return ` key=${event.key} msg=${event.msg.msgId} steer=${event.msg.isSteering}`
+    case 'turnStart':
+    case 'turnEnd':
+      return ` key=${event.key}${event.kind === 'turnEnd' ? ` outbound=${event.outboundEmitted}` : ''}`
+    case 'permVerdict':
+      return ` req=${event.verdict.requestId} behavior=${event.verdict.behavior}`
+    case 'modelOutbound':
+      return ` key=${event.key}`
+    case 'bridgeUp':
+    case 'bridgeDown':
+    case 'tick':
+      return ''
+  }
+}
+
+/** Test hook: reset state to the initial empty machine. */
+export function __shadowResetForTests(): void {
+  state = initialState()
+}
+
+/** Test hook: read the current shadow state. */
+export function __shadowGetStateForTests(): State {
+  return state
+}
+
+/** Test hook: check if shadow mode is enabled (mirrors the env-var). */
+export function __shadowEnabledForTests(): boolean {
+  return enabled
+}