switchroom 0.12.19 → 0.12.20

package/dist/host-control/main.js

@@ -14026,7 +14026,11 @@ var VaultConfigSchema = exports_external.object({
         path: ["approvalAuth"]
       });
     }
-  }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation.")
+  }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation."),
+  backup: exports_external.object({
+    destination: exports_external.string().optional().describe("Destination directory for `switchroom vault backup`. " + "When unset, the CLI defaults to " + "`~/.switchroom-config/vault-backups/` if that operator config " + "repo exists, else `~/.switchroom/vault-backups/`. " + "Path is tilde-expanded at read time. " + "MUST NOT be `~/.switchroom/vault/` (the broker bind-mount dir, " + "validated by `switchroom apply` against an artifact allowlist)."),
+    retain: exports_external.number().int().nonnegative().default(30).describe("How many of the most-recent backups to keep in the destination dir. " + "Older ones are pruned after each new backup is written. Default 30 " + "= roughly a month at daily cadence.")
+  }).optional().describe("Configuration for `switchroom vault backup`. Optional — the CLI works " + "with built-in defaults if this block is absent. The backed-up file is " + "the AES-256-GCM-encrypted vault envelope; the operator passphrase " + "remains the gate, so committing backups to a private git repo extends " + "durability without weakening encryption (provided the auto-unlock " + "blob is NEVER co-located — `vault backup` refuses to write into a " + "directory that contains an auto-unlock-shaped sibling).")
 });
 var QuotaConfigSchema = exports_external.object({
   weekly_budget_usd: exports_external.number().positive().optional().describe("Weekly USD spend budget. If unset, the greeting shows raw usage only."),

package/dist/vault/approvals/kernel-server.js

@@ -11285,7 +11285,11 @@ var init_schema = __esm(() => {
           path: ["approvalAuth"]
         });
       }
-    }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation.")
+    }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation."),
+    backup: exports_external.object({
+      destination: exports_external.string().optional().describe("Destination directory for `switchroom vault backup`. " + "When unset, the CLI defaults to " + "`~/.switchroom-config/vault-backups/` if that operator config " + "repo exists, else `~/.switchroom/vault-backups/`. " + "Path is tilde-expanded at read time. " + "MUST NOT be `~/.switchroom/vault/` (the broker bind-mount dir, " + "validated by `switchroom apply` against an artifact allowlist)."),
+      retain: exports_external.number().int().nonnegative().default(30).describe("How many of the most-recent backups to keep in the destination dir. " + "Older ones are pruned after each new backup is written. Default 30 " + "= roughly a month at daily cadence.")
+    }).optional().describe("Configuration for `switchroom vault backup`. Optional — the CLI works " + "with built-in defaults if this block is absent. The backed-up file is " + "the AES-256-GCM-encrypted vault envelope; the operator passphrase " + "remains the gate, so committing backups to a private git repo extends " + "durability without weakening encryption (provided the auto-unlock " + "blob is NEVER co-located — `vault backup` refuses to write into a " + "directory that contains an auto-unlock-shaped sibling).")
   });
   QuotaConfigSchema = exports_external.object({
     weekly_budget_usd: exports_external.number().positive().optional().describe("Weekly USD spend budget. If unset, the greeting shows raw usage only."),

package/dist/vault/broker/server.js

@@ -11285,7 +11285,11 @@ var init_schema = __esm(() => {
           path: ["approvalAuth"]
         });
       }
-    }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation.")
+    }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation."),
+    backup: exports_external.object({
+      destination: exports_external.string().optional().describe("Destination directory for `switchroom vault backup`. " + "When unset, the CLI defaults to " + "`~/.switchroom-config/vault-backups/` if that operator config " + "repo exists, else `~/.switchroom/vault-backups/`. " + "Path is tilde-expanded at read time. " + "MUST NOT be `~/.switchroom/vault/` (the broker bind-mount dir, " + "validated by `switchroom apply` against an artifact allowlist)."),
+      retain: exports_external.number().int().nonnegative().default(30).describe("How many of the most-recent backups to keep in the destination dir. " + "Older ones are pruned after each new backup is written. Default 30 " + "= roughly a month at daily cadence.")
+    }).optional().describe("Configuration for `switchroom vault backup`. Optional — the CLI works " + "with built-in defaults if this block is absent. The backed-up file is " + "the AES-256-GCM-encrypted vault envelope; the operator passphrase " + "remains the gate, so committing backups to a private git repo extends " + "durability without weakening encryption (provided the auto-unlock " + "blob is NEVER co-located — `vault backup` refuses to write into a " + "directory that contains an auto-unlock-shaped sibling).")
   });
   QuotaConfigSchema = exports_external.object({
     weekly_budget_usd: exports_external.number().positive().optional().describe("Weekly USD spend budget. If unset, the greeting shows raw usage only."),
@@ -16031,7 +16035,7 @@ class VaultBroker {
           chownSync(abs, operatorUid, operatorUid);
         } catch {}
         const unlockServer = net.createServer((sock) => {
-          this._handleUnlockConnection(sock);
+          this._handleUnlockConnection(sock, true);
         });
         unlockServer.on("error", (err) => rejectP(err));
         unlockServer.listen(unlockAbs, () => {
@@ -17031,9 +17035,9 @@ class VaultBroker {
       socket.write(encodeResponse(errorResponse("INTERNAL", msg)));
     }
   }
-  _handleUnlockConnection(socket) {
+  _handleUnlockConnection(socket, isOperator = false) {
     let unlockPeer = null;
-    if (process.platform === "linux") {
+    if (!isOperator && process.platform === "linux") {
       unlockPeer = this.testOpts._testIdentify ? this.testOpts._testIdentify(this.unlockSocketPath, socket) : identify(this.unlockSocketPath, socket);
       if (unlockPeer === null) {
         this.auditLogger.write({
@@ -17048,9 +17052,9 @@ class VaultBroker {
         return;
       }
     }
-    const auditPid = unlockPeer?.pid ?? process.pid;
-    const auditCaller = unlockPeer !== null ? callerFromPeer(unlockPeer) : `pid:${process.pid}`;
-    const auditCgroup = unlockPeer?.systemdUnit ?? undefined;
+    const auditPid = isOperator ? process.pid : unlockPeer?.pid ?? process.pid;
+    const auditCaller = isOperator ? "operator" : unlockPeer !== null ? callerFromPeer(unlockPeer) : `pid:${process.pid}`;
+    const auditCgroup = isOperator ? undefined : unlockPeer?.systemdUnit ?? undefined;
     let buffer = "";
     socket.on("data", (chunk) => {
       buffer += chunk.toString("utf8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.12.19",
+  "version": "0.12.20",
   "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": {
@@ -26,7 +26,7 @@
     "test:vitest": "vitest run",
     "test:bun": "bun test src/watchdog/state.test.ts src/watchdog/policy.test.ts src/vault/grants.test.ts src/vault/write-grants.test.ts src/vault/broker/server-grants.test.ts src/vault/broker/server-write-grants.test.ts src/vault/broker/server-mint-grant-passphrase-attest.test.ts src/vault/broker/server-passphrase-attest.test.ts src/vault/broker/server-mint-grant-posture-attest.test.ts src/vault/broker/client-token.test.ts src/vault/broker/server-unlock.test.ts src/vault/broker/auto-unlock.test.ts src/vault/broker/drift-detection.test.ts tests/vault-broker-passphrase.test.ts src/cli/vault-get-broker.test.ts src/vault/resolver-via-broker.test.ts src/vault/broker/scope.test.ts src/vault/broker/server.test.ts src/drive/disconnect.test.ts src/drive/grants.test.ts src/drive/oauth.test.ts src/drive/onboarding.test.ts src/drive/reconciler.test.ts src/drive/vault-slots.test.ts src/drive/wrapper.test.ts src/vault/approvals/kernel.test.ts src/vault/approvals/schema-idempotent.test.ts src/vault/broker/server-approvals.test.ts telegram-plugin/tests/boot-probes.test.ts telegram-plugin/tests/boot-version-string.test.ts telegram-plugin/tests/history.test.ts telegram-plugin/tests/history-reaper.test.ts telegram-plugin/tests/ipc-server-client.test.ts telegram-plugin/tests/ipc-server-race.test.ts telegram-plugin/tests/gateway-bridge.test.ts telegram-plugin/tests/gateway-startup-mutex.test.ts telegram-plugin/tests/gateway-clean-shutdown-marker.test.ts telegram-plugin/tests/boot-card-dedupe.test.ts telegram-plugin/tests/boot-card-reason.test.ts telegram-plugin/tests/progress-update.test.ts telegram-plugin/tests/quota-cache.test.ts telegram-plugin/tests/silent-reply-guard.test.ts telegram-plugin/tests/unhandled-rejection-policy.test.ts telegram-plugin/tests/registry-turns.test.ts telegram-plugin/registry/subagents.test.ts telegram-plugin/tests/turns-writer.test.ts telegram-plugin/tests/resolve-calling-subagent.test.ts telegram-plugin/tests/gateway-update-placeholder-dispatch.test.ts telegram-plugin/tests/reaction-trigger.test.ts telegram-plugin/tests/reaction-trigger-flow.test.ts telegram-plugin/uat/load-env.test.ts",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs",
+    "lint": "tsc --noEmit && node scripts/check-plugin-references.mjs && bash scripts/check-bot-api-wrapping.sh && node scripts/check-bun-test-imports.mjs && node scripts/check-no-pii-secrets.mjs && node scripts/check-vault-test-hermeticity.mjs",
     "lint:tsc": "tsc --noEmit",
     "lint:plugin-references": "node scripts/check-plugin-references.mjs",
     "lint:bot-api-wrapping": "bash scripts/check-bot-api-wrapping.sh",

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

@@ -23929,7 +23929,11 @@ var init_schema = __esm(() => {
           path: ["approvalAuth"]
         });
       }
-    }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation.")
+    }).describe("Vault-broker daemon configuration. The broker holds the decrypted vault " + "in memory and serves secrets to cron scripts via a Unix socket, so the " + "vault passphrase is entered once at startup rather than per-cron invocation."),
+    backup: exports_external.object({
+      destination: exports_external.string().optional().describe("Destination directory for `switchroom vault backup`. " + "When unset, the CLI defaults to " + "`~/.switchroom-config/vault-backups/` if that operator config " + "repo exists, else `~/.switchroom/vault-backups/`. " + "Path is tilde-expanded at read time. " + "MUST NOT be `~/.switchroom/vault/` (the broker bind-mount dir, " + "validated by `switchroom apply` against an artifact allowlist)."),
+      retain: exports_external.number().int().nonnegative().default(30).describe("How many of the most-recent backups to keep in the destination dir. " + "Older ones are pruned after each new backup is written. Default 30 " + "= roughly a month at daily cadence.")
+    }).optional().describe("Configuration for `switchroom vault backup`. Optional \u2014 the CLI works " + "with built-in defaults if this block is absent. The backed-up file is " + "the AES-256-GCM-encrypted vault envelope; the operator passphrase " + "remains the gate, so committing backups to a private git repo extends " + "durability without weakening encryption (provided the auto-unlock " + "blob is NEVER co-located \u2014 `vault backup` refuses to write into a " + "directory that contains an auto-unlock-shaped sibling).")
   });
   QuotaConfigSchema = exports_external.object({
     weekly_budget_usd: exports_external.number().positive().optional().describe("Weekly USD spend budget. If unset, the greeting shows raw usage only."),
@@ -43725,6 +43729,27 @@ function createInboundSpool(opts) {
   };
 }
 
+// gateway/turn-state-purge.ts
+function purgeStaleTurnsForChat(chatId, keys, purger) {
+  if (!chatId)
+    return { purged: [] };
+  const purged = [];
+  const snapshot = [];
+  for (const k of keys)
+    snapshot.push(k);
+  for (const key of snapshot) {
+    const sep3 = key.indexOf(":");
+    if (sep3 < 0)
+      continue;
+    const keyChat = key.slice(0, sep3);
+    if (keyChat !== chatId)
+      continue;
+    purger(key);
+    purged.push(key);
+  }
+  return { purged };
+}
+
 // gateway/inbound-delivery-gate.ts
 function decideInboundDelivery(input) {
   if (input.turnInFlight && !input.isSteering)
@@ -47090,11 +47115,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.12.19";
-var COMMIT_SHA = "5f6810ed";
-var COMMIT_DATE = "2026-05-19T13:30:31Z";
-var LATEST_PR = 1559;
-var COMMITS_AHEAD_OF_TAG = 4;
+var VERSION = "0.12.20";
+var COMMIT_SHA = "5191cef3";
+var COMMIT_DATE = "2026-05-20T00:03:17Z";
+var LATEST_PR = 1565;
+var COMMITS_AHEAD_OF_TAG = 6;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -48071,6 +48096,12 @@ function purgeReactionTracking(key) {
     }
   }
 }
+function endCurrentTurnAtomic(turn) {
+  if (currentTurn !== turn)
+    return;
+  currentTurn = null;
+  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId));
+}
 function maybeProactiveCompact() {
   if (compactDispatching)
     return;
@@ -48912,6 +48943,7 @@ startTimer({
     preambleSuppressor.dropNow();
     endTurn(fbKey);
     purgeReactionTracking(fbKey);
+    const fbExtraPurge = purgeStaleTurnsForChat(fbChatId, activeTurnStartedAt.keys(), purgeReactionTracking);
     if (turnMatchesFallback && currentTurn === wedgedTurn)
       currentTurn = null;
     try {
@@ -48919,7 +48951,7 @@ startTimer({
     } catch {}
     const fbSelfAgent = process.env.SWITCHROOM_AGENT_NAME ?? "";
     const fbRedeliver = redeliverBufferedInbound(pendingInboundBuffer, fbSelfAgent, (m) => ipcServer.sendToAgent(fbSelfAgent, m), inboundSpool);
-    process.stderr.write(`telegram gateway: silence-poke framework-fallback ended wedged turn chat=${fbChatId} thread=${ctx.threadId ?? "-"} silence_ms=${ctx.silenceMs} currentTurn_nulled=${turnMatchesFallback} drained_buffered=${fbRedeliver.redelivered}/${fbRedeliver.drained}${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ""}
+    process.stderr.write(`telegram gateway: silence-poke framework-fallback ended wedged turn chat=${fbChatId} thread=${ctx.threadId ?? "-"} silence_ms=${ctx.silenceMs} currentTurn_nulled=${turnMatchesFallback} drained_buffered=${fbRedeliver.redelivered}/${fbRedeliver.drained}${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ""}${fbExtraPurge.purged.length > 0 ? ` extra_keys_purged=${fbExtraPurge.purged.length}` : ""}
 `);
   }
 });
@@ -50709,8 +50741,7 @@ function handleSessionEvent(ev) {
           turn.answerStream.stop();
           turn.answerStream = null;
         }
-        if (currentTurn === turn)
-          currentTurn = null;
+        endCurrentTurnAtomic(turn);
         preambleSuppressor.reset();
       }
       return;
@@ -50827,8 +50858,7 @@ function handleSessionEvent(ev) {
         lastPtyPreviewByChat.delete(statusKey(chatId, threadId));
         pendingPtyPartial = null;
         closeActivityLane(chatId, threadId);
-        if (currentTurn === turn)
-          currentTurn = null;
+        endCurrentTurnAtomic(turn);
         preambleSuppressor.dropNow();
         return;
       }
@@ -50843,8 +50873,7 @@ function handleSessionEvent(ev) {
         }) ?? { wasEmitted: false, turnKey: null };
         const backstopCardMessageId = cardTakeover.wasEmitted && cardTakeover.turnKey != null ? getPinnedProgressCardMessageId?.(cardTakeover.turnKey) ?? null : null;
         const backstopCardTurnKey = cardTakeover.turnKey;
-        if (currentTurn === turn)
-          currentTurn = null;
+        endCurrentTurnAtomic(turn);
         preambleSuppressor.dropNow();
         {
           const tKey = statusKey(chatId, threadId);
@@ -51009,8 +51038,7 @@ function handleSessionEvent(ev) {
         }
       }
       removeTurnActiveMarker(STATE_DIR);
-      if (currentTurn === turn)
-        currentTurn = null;
+      endCurrentTurnAtomic(turn);
       return;
     }
   }

package/telegram-plugin/gateway/gateway.ts

@@ -250,6 +250,7 @@ import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
 import { createInboundSpool } from './inbound-spool.js'
+import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import {
@@ -1318,6 +1319,32 @@ function purgeReactionTracking(key: string): void {
   }
 }
 
+/**
+ * Atomic null-and-purge for a wedged turn. Every site that ends a
+ * turn by nulling `currentTurn` MUST also clear the turn's statusKey
+ * from `activeTurnStartedAt` — else a dangling entry survives and
+ * `#1556`'s turn-gate holds every new inbound mid-turn forever
+ * (gymbro / klanker held-mid-turn symptom, 2026-05-20).
+ *
+ * Pre-this, three turn-end paths (silent-marker / turn-flush /
+ * `turn_end`) nulled `currentTurn` on code-paths whose
+ * `purgeReactionTracking` calls weren't reached on every branch,
+ * leaving sibling entries under the turn's statusKey that the
+ * silence-poke framework-fallback's `purgeReactionTracking(fbKey)`
+ * couldn't catch (different key shape). The fallback now also sweeps
+ * siblings for `fbChatId` (`turn-state-purge.ts`) as defense-in-depth,
+ * but THIS helper closes the leak at origin: null and purge are
+ * inseparable at every call site.
+ *
+ * Idempotent: a second purge is a no-op `.delete()` on a key already
+ * gone — handlers that already purge elsewhere are unharmed.
+ */
+function endCurrentTurnAtomic(turn: CurrentTurn): void {
+  if (currentTurn !== turn) return
+  currentTurn = null
+  purgeReactionTracking(statusKey(turn.sessionChatId, turn.sessionThreadId))
+}
+
 /**
  * Model-idle proactive-compaction check. Called ONLY from the
  * activeTurnStartedAt.size === 0 gate above (never mid-turn). Opt-in via
@@ -3011,6 +3038,23 @@ silencePoke.startTimer({
     // for this chat starts a fresh turn instead of queueing forever.
     silencePoke.endTurn(fbKey)
     purgeReactionTracking(fbKey)
+    // Defense-in-depth: the fallback's purgeReactionTracking above
+    // clears the canonical statusKey(chatId, threadId) for fbKey
+    // only. activeTurnStartedAt can hold sibling entries for the
+    // SAME chat (different threads, or a `null` vs `undefined`-thread
+    // variant left over from a normal turn-end path that nulled
+    // currentTurn without invoking purgeReactionTracking — the
+    // gymbro/klanker held-mid-turn symptom, 2026-05-20). Any sibling
+    // for fbChatId is by definition stale when THIS fallback fires
+    // (the chat has been silent ≥5 min); sweep them via the same
+    // purger. Multi-chat-safe — only touches keys for fbChatId, so
+    // #1546's intentional cross-chat safety guard is preserved.
+    // See turn-state-purge.ts.
+    const fbExtraPurge = purgeStaleTurnsForChat(
+      fbChatId,
+      activeTurnStartedAt.keys(),
+      purgeReactionTracking,
+    )
     // Null `currentTurn` if it's still pointing at the wedged turn —
     // when claude eventually fires a late `turn_end` for this session
     // (or never does), the handler's `const turn = currentTurn` snapshot
@@ -3044,7 +3088,8 @@ silencePoke.startTimer({
       `chat=${fbChatId} thread=${ctx.threadId ?? '-'} silence_ms=${ctx.silenceMs} ` +
       `currentTurn_nulled=${turnMatchesFallback} ` +
       `drained_buffered=${fbRedeliver.redelivered}/${fbRedeliver.drained}` +
-      `${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ''}\n`,
+      `${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ''}` +
+      `${fbExtraPurge.purged.length > 0 ? ` extra_keys_purged=${fbExtraPurge.purged.length}` : ''}\n`,
     )
   },
 })
@@ -5686,7 +5731,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           turn.answerStream = null
         }
         // Null the atom — this turn is being abandoned.
-        if (currentTurn === turn) currentTurn = null
+        endCurrentTurnAtomic(turn)
         // #549 fix — context-exhaustion teardown also resets preamble state.
         preambleSuppressor.reset()
       }
@@ -5884,7 +5929,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         // returns early at handler entry. A new `enqueue` swaps in a
         // fresh atom; the silent-turn teardown doesn't need to preserve
         // any of the prior turn's state.
-        if (currentTurn === turn) currentTurn = null
+        endCurrentTurnAtomic(turn)
         // #549 fix — silent-marker teardown drops any pending preamble.
         preambleSuppressor.dropNow()
         return
@@ -5918,7 +5963,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         // sendMessage await for this turn will see currentTurn == null
         // and bail; a new enqueue will swap in a fresh atom. The
         // `backstop*` locals above hold everything the IIFE needs.
-        if (currentTurn === turn) currentTurn = null
+        endCurrentTurnAtomic(turn)
         // #549 fix — turn-flush takes ownership of the captured-text
         // backup; reset the preamble buffer (its content is already in
         // the captured `capturedText`, which turn-flush is about to send).
@@ -6190,7 +6235,7 @@ function handleSessionEvent(ev: SessionEvent): void {
       // #1067: null the atom in one assignment, replacing the seven
       // field clears the pre-refactor version did. Any late-arriving
       // event for this turn will see currentTurn == null and bail.
-      if (currentTurn === turn) currentTurn = null
+      endCurrentTurnAtomic(turn)
       // #549 fix — preamble flush already happened at the TOP of this
       // turn_end handler (before turn.answerStream is nulled). See
       // comment near line 3431.

package/telegram-plugin/gateway/turn-state-purge.ts

@@ -0,0 +1,71 @@
+/**
+ * turn-state-purge.ts — defense-in-depth cleanup for the silence-poke
+ * framework-fallback (gateway.ts).
+ *
+ * The fallback's `purgeReactionTracking(fbKey)` clears the canonical
+ * `statusKey(chatId, threadId)` for the exact chat+thread that armed
+ * the silence-poke. But `activeTurnStartedAt` (and its siblings) can
+ * legitimately hold MORE than one entry for the same chat — e.g.:
+ *
+ *   - a normal turn-end handler null'd `currentTurn` but skipped
+ *     `purgeReactionTracking` on a code-path that didn't reach it
+ *     (gateway.ts:5887/5921/6193 — purgeReactionTracking calls in
+ *     those handlers are conditional/not on every branch), so
+ *     `activeTurnStartedAt[oldKey]` is dangling when the fallback
+ *     fires for a NEW key
+ *   - a multi-thread chat (topic-based group, or a `null` vs
+ *     `undefined` thread variant) has entries under different keys of
+ *     the SAME chat
+ *
+ * In either case, the fallback purges `fbKey` but a sibling key for
+ * the same chat remains → `activeTurnStartedAt.size > 0` persists →
+ * `#1556`'s turn-gate holds every new inbound forever → user sees
+ * "not responding" while claude is actually idle (gymbro + klanker,
+ * 2026-05-20).
+ *
+ * This helper sweeps any sibling keys for the firing chat after the
+ * canonical `purgeReactionTracking(fbKey)`, via the same purger.
+ * Multi-chat safe: it only touches keys whose chatId matches — other
+ * chats' active turns are untouched, preserving the deliberate
+ * multi-chat safety #1546 kept.
+ *
+ * Key shape: `statusKey(chatId, threadId)` emits
+ * `${chatId}:${threadId ?? '_'}`. Chat ids are numeric strings (no
+ * `:` inside), so `indexOf(':')` is a safe prefix delimiter. A
+ * "prefix-without-separator" false positive (e.g. chatId `123` vs key
+ * `1234:_`) is structurally impossible because the helper splits on
+ * `:` and equates the prefix, NOT a string-startsWith.
+ *
+ * Pure / dependency-free so the multi-chat-safety and key-shape logic
+ * are unit-testable without standing up a gateway — mirrors the
+ * `#1544 / #1546 / #1549 / #1558` pure-seam idiom.
+ */
+
+export interface PurgeStaleTurnsResult {
+  /** Keys for `chatId` that the helper purged via the callback. */
+  purged: string[]
+}
+
+export function purgeStaleTurnsForChat(
+  chatId: string,
+  keys: Iterable<string>,
+  purger: (key: string) => void,
+): PurgeStaleTurnsResult {
+  if (!chatId) return { purged: [] }
+  const purged: string[] = []
+  // Snapshot first — `purger` typically deletes from the same Map the
+  // caller is iterating; mutating during iteration is correct on JS
+  // Maps but a snapshot makes the contract explicit and lets the
+  // helper accept any iterable.
+  const snapshot: string[] = []
+  for (const k of keys) snapshot.push(k)
+  for (const key of snapshot) {
+    const sep = key.indexOf(':')
+    if (sep < 0) continue // malformed / non-statusKey shape — skip
+    const keyChat = key.slice(0, sep)
+    if (keyChat !== chatId) continue
+    purger(key)
+    purged.push(key)
+  }
+  return { purged }
+}

package/telegram-plugin/tests/turn-state-purge.test.ts

@@ -0,0 +1,109 @@
+/**
+ * turn-state-purge — the silence-poke fallback's defense-in-depth
+ * cleanup. Pins the multi-chat safety + key-shape correctness that
+ * the gymbro/klanker held-mid-turn fix (2026-05-20) depends on.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { purgeStaleTurnsForChat } from '../gateway/turn-state-purge.js'
+
+function statusKey(chatId: string, threadId?: number): string {
+  return `${chatId}:${threadId ?? '_'}`
+}
+
+describe('purgeStaleTurnsForChat', () => {
+  it('returns [] and calls nothing when keys is empty', () => {
+    let calls = 0
+    const r = purgeStaleTurnsForChat('123', [], () => calls++)
+    expect(r.purged).toEqual([])
+    expect(calls).toBe(0)
+  })
+
+  it('returns [] and calls nothing when chatId is empty (guard)', () => {
+    let calls = 0
+    const r = purgeStaleTurnsForChat('', [statusKey('123')], () => calls++)
+    expect(r.purged).toEqual([])
+    expect(calls).toBe(0)
+  })
+
+  it('purges the canonical DM key for the firing chat (typical case)', () => {
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '12345',
+      [statusKey('12345')],
+      (k) => purged.push(k),
+    )
+    expect(r.purged).toEqual(['12345:_'])
+    expect(purged).toEqual(['12345:_'])
+  })
+
+  it('purges every sibling key for the same chat (multi-thread / dangling)', () => {
+    // This is the gymbro/klanker symptom: a stale activeTurnStartedAt
+    // entry under a different thread of the same chat survives the
+    // canonical purgeReactionTracking(fbKey).
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '12345',
+      [
+        statusKey('12345'),       // DM, no thread
+        statusKey('12345', 42),    // thread 42
+        statusKey('12345', 99),    // thread 99
+      ],
+      (k) => purged.push(k),
+    )
+    expect(r.purged.sort()).toEqual(['12345:42', '12345:99', '12345:_'])
+    expect(purged).toHaveLength(3)
+  })
+
+  it('NEVER touches keys for OTHER chats (multi-chat safety — the #1546 guard)', () => {
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '12345',
+      [
+        statusKey('12345'),       // target chat — purge
+        statusKey('-1001234567890'),       // different chat — must NOT touch
+        statusKey('-1001234567890', 7),    // different chat thread — must NOT touch
+      ],
+      (k) => purged.push(k),
+    )
+    expect(r.purged).toEqual(['12345:_'])
+    expect(purged).toEqual(['12345:_']) // ONLY the target chat
+  })
+
+  it('does not false-match on a chatId-prefix superstring (e.g. 123 vs 1234)', () => {
+    // If we used a naive startsWith on the WHOLE key, chatId "123"
+    // would falsely match key "1234:_". The helper splits on `:` and
+    // equates the chatId slice, which prevents that.
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '123',
+      [statusKey('123'), statusKey('1234'), statusKey('12')],
+      (k) => purged.push(k),
+    )
+    expect(r.purged).toEqual(['123:_']) // ONLY the exact match
+  })
+
+  it('skips malformed keys (no `:`)', () => {
+    let calls = 0
+    const r = purgeStaleTurnsForChat(
+      '123',
+      ['malformed', '', 'no-colon-here', statusKey('123')],
+      () => calls++,
+    )
+    expect(r.purged).toEqual(['123:_'])
+    expect(calls).toBe(1)
+  })
+
+  it('accepts any iterable (snapshots before iteration — purger may delete)', () => {
+    // The real call site iterates `activeTurnStartedAt.keys()` and
+    // the purger deletes from that same Map. Snapshotting in the
+    // helper prevents iterator skew.
+    const map = new Map<string, number>()
+    map.set('123:_', 1)
+    map.set('123:7', 2)
+    map.set('999:_', 3)
+    const r = purgeStaleTurnsForChat('123', map.keys(), (k) => map.delete(k))
+    expect(r.purged.sort()).toEqual(['123:7', '123:_'])
+    expect([...map.keys()]).toEqual(['999:_']) // multi-chat safety preserved
+  })
+})