switchroom 0.12.21 → 0.12.23

package/dist/cli/switchroom.js

@@ -47247,8 +47247,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.12.21";
-var COMMIT_SHA = "e32c064";
+var VERSION = "0.12.23";
+var COMMIT_SHA = "6c99950";
 
 // src/cli/agent.ts
 init_source();
@@ -48583,11 +48583,32 @@ function installHindsightPlugin(agentName, agentDir, switchroomConfig) {
     rmSync3(destPath, { recursive: true, force: true });
   }
   copyDirRecursive2(sourcePath, destPath);
+  applyHindsightSettingsOverrides(destPath);
   const bankId = agentMemory?.collection ?? agentName;
   const mcpUrl = memory.config?.url ?? "http://127.0.0.1:8888/mcp/";
   const apiBaseUrl = mcpUrl.replace(/\/mcp\/?$/, "").replace(/\/$/, "");
   return { pluginDir: destPath, apiBaseUrl, bankId };
 }
+function applyHindsightSettingsOverrides(pluginDestPath) {
+  const settingsPath = join8(pluginDestPath, "settings.json");
+  if (!existsSync11(settingsPath))
+    return;
+  let raw;
+  try {
+    raw = readFileSync11(settingsPath, "utf-8");
+  } catch {
+    return;
+  }
+  let settings;
+  try {
+    settings = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  settings.retainEveryNTurns = 1;
+  writeFileSync5(settingsPath, JSON.stringify(settings, null, 2) + `
+`, "utf-8");
+}
 function buildWorkspaceContext(args) {
   const {
     name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.12.21",
+  "version": "0.12.23",
   "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

@@ -47126,11 +47126,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.12.21";
-var COMMIT_SHA = "e32c064";
-var COMMIT_DATE = "2026-05-20T02:05:49Z";
-var LATEST_PR = 1572;
-var COMMITS_AHEAD_OF_TAG = null;
+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;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -51275,6 +51275,7 @@ async function handleInbound(ctx, text, downloadImage, attachment) {
     return;
   }
   const inboundReceivedAt = Date.now();
+  const turnInFlightAtReceipt = activeTurnStartedAt.size > 0;
   const access = result.access;
   const from = ctx.from;
   const chat_id = String(ctx.chat.id);
@@ -51834,7 +51835,7 @@ ${preBlock(write.output)}`;
   };
   const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? "";
   if (decideInboundDelivery({
-    turnInFlight: activeTurnStartedAt.size > 0,
+    turnInFlight: turnInFlightAtReceipt,
     isSteering
   }) === "buffer-until-idle") {
     pendingInboundBuffer.push(selfAgent, inboundMsg);

package/telegram-plugin/gateway/gateway.ts

@@ -6637,6 +6637,39 @@ async function handleInbound(
   // network RTT) but not a user-perceived end-to-end measurement.
   const inboundReceivedAt = 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
+  // turn ALREADY in flight" — but if we read activeTurnStartedAt.size
+  // at the gate, we see the entry this handler just wrote, and buffer
+  // the very message that just started the turn. Symptom: every first
+  // post-restart message in each thread was held 5 minutes until the
+  // silence-poke fallback drained the buffer; the "5-min blank after
+  // restart" wedge documented in
+  // feedback_5min_restart_wedge_violates_vision.md.
+  //
+  // Why ONLY first-after-restart, not every steady-state message: the
+  // fresh-turn branch fires only when `priorActive = activeStatusReactions.get(key)`
+  // returns null (no controller currently running for this chat+thread).
+  // In a live conversation, the controller from the previous turn
+  // typically hasn't been cleared yet when the user's follow-up
+  // arrives (or follow-ups arrive mid-turn, taking the queued path) —
+  // so the else branch at ~7313 is skipped and the .set never fires.
+  // A fresh container after restart has EMPTY `activeStatusReactions`,
+  // so the very first message in each thread is guaranteed to enter
+  // the fresh-turn branch and trigger the self-block.
+  //
+  // Why snapshot, not move-the-set(): the .set() at ~7357 is embedded
+  // in a coupled init bundle (controller, msgIds, signalTracker.reset,
+  // silencePoke.startTurn, the 👀 reaction emit). Moving only the .set
+  // splits the bundle in ways future maintainers will drift; moving
+  // the WHOLE bundle past the gate changes user-visible ack timing
+  // (👀 wouldn't land until after the gate decides to deliver, hiding
+  // an ack on the buffered path). The snapshot is the minimal precise
+  // fix. Phase 2b's state-machine extraction will revisit this
+  // structurally.
+  const turnInFlightAtReceipt = activeTurnStartedAt.size > 0
+
   const access = result.access
   const from = ctx.from!
   const chat_id = String(ctx.chat!.id)
@@ -7546,9 +7579,15 @@ async function handleInbound(
   // idle-drain flush it the instant claude goes idle, where the channel
   // notification submits cleanly as a fresh turn. Steering messages are
   // exempt — reaching claude mid-turn is the whole point of /steer.
+  //
+  // CRITICAL: turnInFlight reads the snapshot taken at receipt above,
+  // not `activeTurnStartedAt.size > 0` live. The fresh-turn branch at
+  // line ~7357 already populated the Map for THIS inbound's turn;
+  // reading the live size here would self-block (see the comment on
+  // turnInFlightAtReceipt for the wedge symptom this fixes).
   if (
     decideInboundDelivery({
-      turnInFlight: activeTurnStartedAt.size > 0,
+      turnInFlight: turnInFlightAtReceipt,
       isSteering,
     }) === 'buffer-until-idle'
   ) {

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

@@ -0,0 +1,435 @@
+/**
+ * InboundDeliveryStateMachine — pure transition function for the
+ * gateway's inbound→bridge→outbound pipeline.
+ *
+ * Per `docs/rfcs/inbound-delivery-state-machine.md` (RFC merged in
+ * PR #1576): the gateway's delivery state was implicit and scattered
+ * across 8+ pieces of mutable state. The wedge cluster of 2026-05-19
+ * (9 PRs in 36h all patching variants of "inbound stranded → 5-min
+ * silence-poke fallback") and the v0.12.22 self-blocking gate bug
+ * (#1573, symptom-level) shared one root cause: no model anywhere in
+ * the codebase said "given these inputs, what should the gateway do."
+ *
+ * This module IS that model.
+ *
+ * ## Contract
+ *
+ *   transition(state, event) → { state', effects[] }
+ *
+ * Pure. No I/O. No timers. No mutation of inputs. The gateway
+ * dispatcher receives `{ state', effects[] }` and EXECUTES the
+ * effects against the real bridge/buffer/spool/Telegram. The
+ * machine never touches those directly.
+ *
+ * Property-tested by 5 invariants (see
+ * `tests/inbound-delivery-machine.test.ts`):
+ *
+ *   #1 — Every `inbound` event is delivered XOR persisted
+ *   #2 — Every `setTurnStarted(key)` paired with `clearTurnStarted(key)`
+ *        before the next end-of-life event for that key
+ *   #3 — Per-chat sibling-key cleanup on `turnEnd`
+ *   #4 — `permVerdict` delivered iff bridge alive; else persisted +
+ *        re-delivered on next `bridgeUp`
+ *   #5 — Spurious-fallback suppression (no `firePoke('fallback')` if
+ *        the model produced an outbound for this key in the last 60s)
+ *
+ * ## Scope of this PR
+ *
+ * This is PR 1 of the 3-PR cutover (per RFC). The module is exported
+ * but NOT WIRED into `gateway.ts`. PR 2 will swap the gateway's
+ * imperative paths to dispatch through this machine. PR 3 will
+ * delete the now-redundant primitives.
+ *
+ * Zero production behavior change in this PR. The property test is
+ * the only gate.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// Branded types — chat-key namespace
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical chat-thread key. Use the existing `chatKey()` helper from
+ * `./chat-key.ts` to construct one — that helper collapses
+ * 0/null/undefined thread IDs to the same token (#1564 sibling-key
+ * canonicalization). The state machine treats `ChatKey` as opaque.
+ */
+export type ChatKey = string & { readonly __brand: 'ChatKey' }
+
+// ─────────────────────────────────────────────────────────────────────
+// State
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Global delivery state. Mirrors the existing `currentTurn` singleton
+ * but explicit. The gateway has ONE bridge connection (single claude
+ * process per agent container), so global state is the right model.
+ */
+export type GlobalState =
+  | { kind: 'bridge_dead' }
+  | { kind: 'bridge_alive_idle' }
+  | { kind: 'bridge_alive_in_turn'; activeTurn: ChatKey }
+
+/**
+ * Per-key state. Lifts the scattered `activeTurnStartedAt` Map and
+ * silence-poke's per-key `lastOutboundAt` tracking into ONE place.
+ *
+ * `turnStartedAt`: when this chat's current turn began (null = no
+ * turn active for this key). Mirrors the existing
+ * `activeTurnStartedAt[key]` value.
+ *
+ * `lastOutboundAt`: when the model last produced an outbound for
+ * this key. CARRIES ACROSS TURNS — this is invariant #5's data: even
+ * if a new turn starts (overlapping turns case from the
+ * 2026-05-20 mid-turn silence wedge), the model's recent outbound is
+ * preserved so a spurious fallback fire is suppressed.
+ */
+export interface PerKeyState {
+  readonly turnStartedAt: number | null
+  readonly lastOutboundAt: number | null
+}
+
+export interface State {
+  readonly global: GlobalState
+  readonly perKey: ReadonlyMap<ChatKey, PerKeyState>
+}
+
+export function initialState(): State {
+  return {
+    global: { kind: 'bridge_dead' },
+    perKey: new Map(),
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Events
+// ─────────────────────────────────────────────────────────────────────
+
+export interface InboundMessage {
+  readonly msgId: number
+  readonly isSteering: boolean
+  readonly payload: unknown
+}
+
+export interface PermissionVerdict {
+  readonly requestId: string
+  readonly behavior: 'allow' | 'deny' | 'allow_once' | 'allow_always'
+  readonly payload: unknown
+}
+
+export interface SpooledInbound {
+  readonly key: ChatKey
+  readonly msg: InboundMessage
+}
+
+export type Event =
+  | { kind: 'bridgeUp'; at: number }
+  | { kind: 'bridgeDown'; at: number }
+  | { kind: 'turnStart'; key: ChatKey; at: number }
+  | { kind: 'turnEnd'; key: ChatKey; at: number; outboundEmitted: boolean }
+  | { kind: 'inbound'; key: ChatKey; msg: InboundMessage; at: number }
+  | { kind: 'permVerdict'; verdict: PermissionVerdict; at: number }
+  | { kind: 'modelOutbound'; key: ChatKey; at: number }
+  | { kind: 'tick'; now: number }
+
+// ─────────────────────────────────────────────────────────────────────
+// Effects (returned, not performed)
+// ─────────────────────────────────────────────────────────────────────
+
+export type Effect =
+  | { kind: 'deliverToBridge'; key: ChatKey; msg: InboundMessage }
+  | { kind: 'bufferInbound'; key: ChatKey; msg: InboundMessage }
+  | { kind: 'persistInbound'; key: ChatKey; msg: InboundMessage }
+  | { kind: 'drainBuffer' }
+  | { kind: 'setTurnStarted'; key: ChatKey; at: number }
+  | { kind: 'clearTurnStarted'; key: ChatKey }
+  | { kind: 'noteOutbound'; key: ChatKey; at: number }
+  | { kind: 'firePoke'; key: ChatKey; level: 'soft' | 'firm' | 'fallback' }
+  | { kind: 'deliverPermVerdict'; verdict: PermissionVerdict }
+  | { kind: 'persistPermVerdict'; verdict: PermissionVerdict }
+  | { kind: 'redeliverPersistedPermVerdicts' }
+  | { kind: 'logTrace'; stage: string; key?: ChatKey; metadata?: Readonly<Record<string, unknown>> }
+
+// ─────────────────────────────────────────────────────────────────────
+// Tunable timings (match the production silence-poke ladder for now;
+// the RFC includes a recommendation to tighten these in a follow-up,
+// but parity-first for the PR-2 cutover).
+// ─────────────────────────────────────────────────────────────────────
+
+export const TURN_TTL_MS = 300_000 // 5 min — silence-poke fallback threshold
+export const SOFT_POKE_MS = 75_000
+export const FIRM_POKE_MS = 180_000
+export const OUTBOUND_RECENT_MS = 60_000 // invariant #5 suppression window
+
+// ─────────────────────────────────────────────────────────────────────
+// Transition function
+// ─────────────────────────────────────────────────────────────────────
+
+export interface Transition {
+  readonly state: State
+  readonly effects: readonly Effect[]
+}
+
+function emptyPerKey(): PerKeyState {
+  return { turnStartedAt: null, lastOutboundAt: null }
+}
+
+function updatePerKey(
+  state: State,
+  key: ChatKey,
+  update: (prior: PerKeyState) => PerKeyState,
+): State {
+  const prior = state.perKey.get(key) ?? emptyPerKey()
+  const next = update(prior)
+  const m = new Map(state.perKey)
+  // Empty entries (both fields null) are pruned to keep the map tight
+  // — invariant #2's test reads the map size and we don't want stale
+  // empty entries inflating it.
+  if (next.turnStartedAt == null && next.lastOutboundAt == null) {
+    m.delete(key)
+  } else {
+    m.set(key, next)
+  }
+  return { ...state, perKey: m }
+}
+
+function chatIdOfKey(key: ChatKey): string {
+  // ChatKey shape is `${chatId}:${threadOrUnderscore}`. Splitting on
+  // the FIRST colon gives the chatId — robust to threads/suffixes.
+  const idx = key.indexOf(':')
+  return idx === -1 ? key : key.slice(0, idx)
+}
+
+/**
+ * Sweep all sibling keys for a chatId — Invariant #3. After the last
+ * turnEnd for a chatId, no sibling thread keys should remain.
+ *
+ * Effect: emits `clearTurnStarted` for every sibling key still
+ * holding `turnStartedAt != null`. Returns updated state.
+ *
+ * The state machine's invariant is enforced because we PROACTIVELY
+ * purge siblings on turnEnd. The production sibling-key sweep
+ * (#1564's `purgeStaleTurnsForChat`) becomes redundant.
+ */
+function sweepSiblings(
+  state: State,
+  chatId: string,
+  exceptKey: ChatKey,
+): { state: State; effects: Effect[] } {
+  const effects: Effect[] = []
+  let next = state
+  for (const [k, v] of state.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 }
+}
+
+export function transition(state: State, event: Event): Transition {
+  switch (event.kind) {
+    case 'bridgeUp': {
+      if (state.global.kind !== 'bridge_dead') {
+        // Idempotent: a second bridgeUp is a no-op.
+        return { state, effects: [{ kind: 'logTrace', stage: 'bridgeUp_redundant' }] }
+      }
+      return {
+        state: { ...state, global: { kind: 'bridge_alive_idle' } },
+        effects: [
+          { kind: 'redeliverPersistedPermVerdicts' },
+          { kind: 'drainBuffer' },
+          { kind: 'logTrace', stage: 'bridge_recover' },
+        ],
+      }
+    }
+
+    case 'bridgeDown': {
+      // Keep perKey state intact — the next bridgeUp + turnEnd will
+      // resolve naturally. Clearing turn state on bridge flap was the
+      // wedge-cluster's "drain on disconnect" footgun.
+      return {
+        state: { ...state, global: { kind: 'bridge_dead' } },
+        effects: [{ kind: 'logTrace', stage: 'bridge_flap' }],
+      }
+    }
+
+    case 'inbound': {
+      const isSteering = event.msg.isSteering
+      const inTurn = state.global.kind === 'bridge_alive_in_turn'
+      const alive = state.global.kind !== 'bridge_dead'
+
+      if (!alive) {
+        return {
+          state,
+          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) {
+        // Mid-turn non-steering inbound: buffer (the #1556 contract).
+        return {
+          state,
+          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 } },
+          ],
+        }
+      }
+
+      // Alive + (idle OR steering): deliver immediately.
+      // Steering messages reach claude mid-turn intentionally; they
+      // do NOT start a new turn (existing turn continues).
+      if (isSteering) {
+        return {
+          state,
+          effects: [
+            { kind: 'deliverToBridge', key: event.key, msg: event.msg },
+            { kind: 'logTrace', stage: 'steer_delivered_mid_turn', key: event.key },
+          ],
+        }
+      }
+
+      // Fresh turn: state transitions to in_turn(key), perKey
+      // turnStartedAt is set, message delivered.
+      const next: State = {
+        global: { kind: 'bridge_alive_in_turn', activeTurn: event.key },
+        perKey: state.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': {
+      // External signal that a turn has begun (e.g. session_event
+      // from bridge). Distinct from the implicit turn-start in
+      // `inbound`: a turn can begin without a fresh inbound (cron
+      // injection, scheduled fire).
+      const next: State = state.global.kind === 'bridge_alive_in_turn'
+        ? state
+        : { ...state, 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': {
+      // Clear turn state for the ending key AND sweep siblings
+      // (invariant #3). Transition global to idle if the ending turn
+      // was the active one.
+      const chatId = chatIdOfKey(event.key)
+      const stateAfterClear = updatePerKey(state, event.key, (p) => ({
+        turnStartedAt: null,
+        lastOutboundAt: event.outboundEmitted ? event.at : p.lastOutboundAt,
+      }))
+      const sweep = sweepSiblings(stateAfterClear, chatId, event.key)
+      const wasActive = state.global.kind === 'bridge_alive_in_turn' && state.global.activeTurn === event.key
+      const next: State = wasActive
+        ? { ...sweep.state, global: { kind: 'bridge_alive_idle' } }
+        : sweep.state
+      const effects: Effect[] = [
+        { 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': {
+      // Updates lastOutboundAt for the key. Does NOT change global
+      // state. This is invariant #5's data: it carries across turn
+      // boundaries so a spurious fallback can be suppressed.
+      return {
+        state: updatePerKey(state, event.key, (p) => ({ ...p, lastOutboundAt: event.at })),
+        effects: [
+          { kind: 'noteOutbound', key: event.key, at: event.at },
+        ],
+      }
+    }
+
+    case 'permVerdict': {
+      const alive = state.global.kind !== 'bridge_dead'
+      if (alive) {
+        return {
+          state,
+          effects: [
+            { kind: 'deliverPermVerdict', verdict: event.verdict },
+            { kind: 'logTrace', stage: 'perm_verdict_delivered' },
+          ],
+        }
+      }
+      return {
+        state,
+        effects: [
+          { kind: 'persistPermVerdict', verdict: event.verdict },
+          { kind: 'logTrace', stage: 'perm_verdict_persisted' },
+        ],
+      }
+    }
+
+    case 'tick': {
+      // Scan perKey for stale turns. For each entry with a non-null
+      // turnStartedAt where `now - turnStartedAt > TURN_TTL_MS`:
+      //   - Check lastOutboundAt: if it's null OR more than
+      //     OUTBOUND_RECENT_MS old, fire the fallback poke + clear.
+      //   - Otherwise suppress (invariant #5).
+      const effects: Effect[] = []
+      let next = state
+      for (const [k, v] of state.perKey) {
+        if (v.turnStartedAt == null) continue
+        const age = event.now - v.turnStartedAt
+        if (age <= TURN_TTL_MS) {
+          // Not yet stale enough for fallback. Soft/firm pokes are
+          // not modeled here yet — they're advisory, the gateway
+          // emits them; the state machine governs the fallback gate.
+          continue
+        }
+        // Stale enough for fallback. Check the suppression window.
+        const recentOutbound =
+          v.lastOutboundAt != null && (event.now - v.lastOutboundAt) < OUTBOUND_RECENT_MS
+        if (recentOutbound) {
+          // Invariant #5: model recently broke silence; suppress fire.
+          effects.push({ kind: 'logTrace', stage: 'fallback_suppressed', key: k, metadata: { recentOutboundMs: event.now - (v.lastOutboundAt ?? 0) } })
+          continue
+        }
+        // Fire the fallback + clear the turn.
+        effects.push({ kind: 'firePoke', key: k, level: 'fallback' })
+        effects.push({ kind: 'clearTurnStarted', key: k })
+        next = updatePerKey(next, k, (p) => ({ ...p, turnStartedAt: null }))
+        // If this was the active turn globally, drop to idle.
+        if (next.global.kind === 'bridge_alive_in_turn' && next.global.activeTurn === k) {
+          next = { ...next, global: { kind: 'bridge_alive_idle' } }
+        }
+      }
+      return { state: next, effects }
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Test-only helpers — mirror silence-poke.ts's __XForTests idiom
+// ─────────────────────────────────────────────────────────────────────
+
+export function __chatIdOfKeyForTests(key: ChatKey): string {
+  return chatIdOfKey(key)
+}