switchroom 0.12.20 → 0.12.22

package/dist/cli/switchroom.js

@@ -47247,8 +47247,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.12.20";
-var COMMIT_SHA = "5191cef3";
+var VERSION = "0.12.22";
+var COMMIT_SHA = "332e23e";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.12.20",
+  "version": "0.12.22",
   "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,12 +26,13 @@
     "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 && node scripts/check-vault-test-hermeticity.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 && node scripts/check-no-broadcast-delivery.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",
     "lint:bun-test-imports": "node scripts/check-bun-test-imports.mjs",
     "lint:no-pii": "node scripts/check-no-pii-secrets.mjs",
+    "lint:no-broadcast-delivery": "node scripts/check-no-broadcast-delivery.mjs",
     "prepublishOnly": "npm run build && npm run lint && npm test"
   },
   "dependencies": {

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

@@ -31461,7 +31461,8 @@ function createStreamController(cfg) {
 
 // pty-partial-handler.ts
 function streamKey(chatId, threadId) {
-  return `${chatId}:${threadId ?? "_"}`;
+  const t = threadId == null || threadId === 0 ? "_" : String(threadId);
+  return `${chatId}:${t}`;
 }
 function handlePtyPartialPure(text, state, deps) {
   if (state.currentSessionChatId == null) {
@@ -31547,7 +31548,8 @@ function buildAccentHeader(accent) {
   }
 }
 function streamKey2(chatId, threadId, lane, turnKey) {
-  const base = `${chatId}:${threadId ?? "_"}`;
+  const t = threadId == null || threadId === 0 ? "_" : String(threadId);
+  const base = `${chatId}:${t}`;
   const withLane = lane != null && lane.length > 0 ? `${base}:${lane}` : base;
   return turnKey != null && turnKey.length > 0 ? `${withLane}:${turnKey}` : withLane;
 }
@@ -43803,6 +43805,15 @@ function createPendingPermissionBuffer(opts = {}) {
   };
 }
 
+// gateway/chat-key.ts
+function chatKey(chatId, threadId) {
+  const t = threadId == null || threadId === 0 ? "_" : String(threadId);
+  return `${chatId}:${t}`;
+}
+function chatKeyWithSuffix(chatId, threadId, suffix) {
+  return `${chatKey(chatId, threadId)}:${suffix}`;
+}
+
 // gateway/vault-grant-inbound-builders.ts
 function buildVaultGrantApprovedInbound(opts) {
   const ts = opts.nowMs ?? Date.now();
@@ -47115,11 +47126,11 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-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;
+var VERSION = "0.12.22";
+var COMMIT_SHA = "332e23e";
+var COMMIT_DATE = "2026-05-20T02:55:00Z";
+var LATEST_PR = 1574;
+var COMMITS_AHEAD_OF_TAG = 2;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -48062,10 +48073,10 @@ var CONTEXT_EXHAUSTION_COOLDOWN_MS = 600000;
 var lastContextExhaustionWarningAt = 0;
 var pendingPtyPartial = null;
 function statusKey(chatId, threadId) {
-  return `${chatId}:${threadId ?? "_"}`;
+  return chatKey(chatId, threadId);
 }
 function streamKey3(chatId, threadId) {
-  return `${chatId}:${threadId ?? "_"}`;
+  return chatKey(chatId, threadId);
 }
 function purgeReactionTracking(key) {
   const msgInfo = activeReactionMsgIds.get(key);
@@ -50526,7 +50537,7 @@ function resetOrphanedReplyTimeout() {
   }
 }
 function closeActivityLane(chatId, threadId) {
-  const key = `${chatId}:${threadId ?? "_"}:activity`;
+  const key = chatKeyWithSuffix(chatId, threadId, "activity");
   const stream = activeDraftStreams.get(key);
   if (stream == null)
     return;
@@ -50535,7 +50546,7 @@ function closeActivityLane(chatId, threadId) {
   stream.finalize().catch(() => {});
 }
 function closeProgressLane(chatId, threadId) {
-  const prefix = `${chatId}:${threadId ?? "_"}:progress`;
+  const prefix = chatKeyWithSuffix(chatId, threadId, "progress");
   for (const [key, stream] of activeDraftStreams) {
     if (key.startsWith(prefix)) {
       activeDraftStreams.delete(key);
@@ -50575,7 +50586,8 @@ function handleSessionEvent(ev) {
         currentTurn = next;
         preambleSuppressor.reset();
         if (turnsDb != null) {
-          const turnKey = `${ev.chatId}:${ev.threadId ?? "_"}:${startedAt}`;
+          const evThreadIdNum = ev.threadId != null ? Number(ev.threadId) : null;
+          const turnKey = chatKeyWithSuffix(ev.chatId, evThreadIdNum, String(startedAt));
           next.registryKey = turnKey;
           const userPromptPreview = extractUserPromptPreview(ev.rawContent);
           try {
@@ -50808,7 +50820,7 @@ function handleSessionEvent(ev) {
       if (flushDecision.kind === "skip" && flushDecision.reason === "silent-marker") {
         process.stderr.write(`telegram gateway: silent-turn-suppression: chat=${chatId} turnKey=${turn.startedAt} reason=silent-marker
 `);
-        const suppressPrefix = `${chatId}:${threadId ?? "_"}:progress`;
+        const suppressPrefix = chatKeyWithSuffix(chatId, threadId, "progress");
         for (const [key] of activeDraftStreams) {
           if (key.startsWith(suppressPrefix)) {
             activeDraftStreams.delete(key);
@@ -51263,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);
@@ -51822,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/chat-key.ts

@@ -0,0 +1,67 @@
+/**
+ * Canonical chat-key construction with branded type.
+ *
+ * The gateway tracks per-chat state (active turn, draft stream, status
+ * reactions, progress throttle, etc.) in `Map<string, ...>` instances
+ * keyed by a string derived from `(chatId, threadId | null)`. Multiple
+ * callsites historically constructed those keys inline as
+ * `` `${chatId}:${threadId ?? '_'}` ``. That worked until PR #1564 hit
+ * the silence-poke wedge: an `activeTurnStartedAt` entry survived a
+ * turn-end because the entry was set under one rendering of the key
+ * (`null` thread → `_`) and the cleanup ran against another
+ * (`undefined` thread → `_`, but also `0` thread → `0`, which doesn't
+ * coalesce). The fallback's `purgeReactionTracking` cleared one
+ * statusKey at a time; sibling keys for the same chat persisted, so
+ * `activeTurnStartedAt.size > 0` stayed true forever and every
+ * subsequent inbound was held mid-turn.
+ *
+ * This module makes the bug class hard to reintroduce:
+ *
+ *   1. `chatKey()` is the canonical constructor for "this chat+thread"
+ *      keys. It collapses `null`, `undefined`, and `0` thread IDs
+ *      into the same token (`_`). All sites in `gateway.ts`,
+ *      `stream-reply-handler.ts`, and `pty-partial-handler.ts` route
+ *      through it (or mirror its expression inline).
+ *   2. The returned `ChatKey` is a branded string — a documentation
+ *      marker for human readers. `telegram-plugin/` is bun-bundled
+ *      and NOT in `tsconfig.json`'s `include`; `lint:plugin-references`
+ *      filters tsc output to reference-class errors only (TS2304/2552/
+ *      2722/2561). A future opt-in `Map<ChatKey, T>` migration could
+ *      provide enforcement teeth, but that requires either bringing
+ *      `telegram-plugin/` into the strict tsc check or rewriting the
+ *      lint to fail on TS2345 type-mismatch. Today the brand is a
+ *      nudge, not a fence.
+ *
+ * `chatKeyWithSuffix()` extends a ChatKey with a lane suffix
+ * (`activity`, `progress`, etc.) — same documentation brand.
+ *
+ * Non-ChatKey keyspaces (chat:message, chat:user, chat:sender:reason)
+ * are deliberately NOT branded — they have different shape and
+ * different invariants, see `deferredKey` / `inboundCoalesceKey` /
+ * the gate-dedup helper in `gateway.ts`.
+ */
+
+export type ChatKey = string & { readonly __brand: 'ChatKey' }
+
+export function chatKey(chatId: string, threadId?: number | null): ChatKey {
+  const t = threadId == null || threadId === 0 ? '_' : String(threadId)
+  return `${chatId}:${t}` as ChatKey
+}
+
+export function chatKeyWithSuffix(
+  chatId: string,
+  threadId: number | null | undefined,
+  suffix: string,
+): ChatKey {
+  return `${chatKey(chatId, threadId)}:${suffix}` as ChatKey
+}
+
+/**
+ * Extract the chatId portion of a ChatKey. Used by sibling-key sweeps
+ * (PR #1564's `purgeStaleTurnsForChat`) that need to enumerate every
+ * thread under a single chat.
+ */
+export function chatIdOfChatKey(key: ChatKey): string {
+  const idx = key.indexOf(':')
+  return idx === -1 ? key : key.slice(0, idx)
+}

package/telegram-plugin/gateway/gateway.ts

@@ -253,6 +253,7 @@ 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 { chatKey, chatKeyWithSuffix } from './chat-key.js'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
@@ -1026,6 +1027,7 @@ function checkApprovals(): void {
   try { files = readdirSync(APPROVED_DIR) } catch { return }
   for (const senderId of files) {
     const file = join(APPROVED_DIR, senderId)
+    // allow-raw-bot-api: Paired! sendMessage to DM senderId; no thread_id, cannot trigger THREAD_NOT_FOUND
     void bot.api.sendMessage(senderId, "Paired! Say hi to Claude.").then(
       () => rmSync(file, { force: true }),
       err => {
@@ -1248,12 +1250,18 @@ let lastContextExhaustionWarningAt = 0
 
 let pendingPtyPartial: string | null = null
 
-function statusKey(chatId: string, threadId?: number): string {
-  return `${chatId}:${threadId ?? '_'}`
+// statusKey + streamKey are thin re-exports of the canonical chatKey()
+// constructor (see telegram-plugin/gateway/chat-key.ts). chatKey()
+// collapses 0/null/undefined thread IDs to the same token (`_`),
+// closing the sibling-key class behind #1564 (where one site set the
+// entry under `null → _` and another cleared under `0 → 0`, leaving
+// activeTurnStartedAt non-empty forever).
+function statusKey(chatId: string, threadId?: number | null): string {
+  return chatKey(chatId, threadId)
 }
 
-function streamKey(chatId: string, threadId?: number): string {
-  return `${chatId}:${threadId ?? '_'}`
+function streamKey(chatId: string, threadId?: number | null): string {
+  return chatKey(chatId, threadId)
 }
 
 function purgeReactionTracking(key: string): void {
@@ -2675,6 +2683,7 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
       parse_mode: 'HTML' as const,
       ...(renderedKeyboard ? { reply_markup: renderedKeyboard } : {}),
     }
+    // allow-raw-bot-api: operator-event broadcast loop; opts has no message_thread_id
     void bot.api.sendMessage(chat_id, renderedText, opts as never).catch(e => {
       process.stderr.write(
         `telegram gateway: operator-event send to ${chat_id} failed agent=${agent} kind=${kind}: ${e}\n`,
@@ -3453,6 +3462,7 @@ const ipcServer: IpcServer = createIpcServer({
         .text(`🔁 Always allow ${alwaysRule.label}`, `perm:always:${requestId}`)
     }
     for (const chat_id of access.allowFrom) {
+      // allow-raw-bot-api: permission-request keyboard fan-out; reply_markup-only opts, no thread_id
       void bot.api.sendMessage(chat_id, text, { reply_markup: keyboard }).catch(e => {
         process.stderr.write(`telegram gateway: permission_request send to ${chat_id} failed: ${e}\n`)
       })
@@ -4069,6 +4079,7 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
           stripped.length > 0
             ? stripped
             : '⚠️ (a formatted fragment could not be rendered for Telegram)'
+        // allow-raw-bot-api: plaintext last-resort fallback; wrapping would re-enter the parse-mode policy that just rejected the payload
         const sent = await lockedBot.api.sendMessage(chat_id, plain, plainOpts as never)
         sentIds.push(sent.message_id)
         logOutbound('reply', chat_id, sent.message_id, plain.length, `chunk=${i + 1}/${chunks.length} plaintext-fallback`)
@@ -4090,6 +4101,7 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
           const retryOpts = { ...sendOpts }
           delete (retryOpts as any).message_thread_id
           try {
+            // allow-raw-bot-api: chunk-loop THREAD_NOT_FOUND fallback; thread already dropped, wrapping would re-enter the throw
             const sent = await lockedBot.api.sendMessage(chat_id, chunks[i], retryOpts as never)
             sentIds.push(sent.message_id)
           } catch (retryErr) {
@@ -5392,7 +5404,7 @@ function resetOrphanedReplyTimeout(): void {
 }
 
 function closeActivityLane(chatId: string, threadId: number | undefined): void {
-  const key = `${chatId}:${threadId ?? '_'}:activity`
+  const key = chatKeyWithSuffix(chatId, threadId, 'activity')
   const stream = activeDraftStreams.get(key)
   if (stream == null) return
   activeDraftStreams.delete(key)
@@ -5404,7 +5416,7 @@ function closeProgressLane(chatId: string, threadId: number | undefined): void {
   // Progress-card streams include a turnKey suffix in their key
   // (e.g. "chatId:_:progress:chatId:1"). Iterate and match by prefix
   // so the backstop actually finds the stream.
-  const prefix = `${chatId}:${threadId ?? '_'}:progress`
+  const prefix = chatKeyWithSuffix(chatId, threadId, 'progress')
   for (const [key, stream] of activeDraftStreams) {
     if (key.startsWith(prefix)) {
       activeDraftStreams.delete(key)
@@ -5460,7 +5472,11 @@ function handleSessionEvent(ev: SessionEvent): void {
         // progress-card-driver's per-chat sequence number (these are two
         // independent identifier schemes and don't need to align).
         if (turnsDb != null) {
-          const turnKey = `${ev.chatId}:${ev.threadId ?? '_'}:${startedAt}`
+          // ev.threadId is `string | null` (Telegram emits as string); convert
+          // to number for chatKeyWithSuffix. Number(null) = 0 which canonicalizes
+          // to '_' — same as the explicit `null` branch below.
+          const evThreadIdNum = ev.threadId != null ? Number(ev.threadId) : null
+          const turnKey = chatKeyWithSuffix(ev.chatId, evThreadIdNum, String(startedAt))
           next.registryKey = turnKey
           // Phase 1 of #332: capture first ~200 chars of the user's message.
           const userPromptPreview = extractUserPromptPreview(ev.rawContent)
@@ -5857,7 +5873,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         // Drop progress-card streams without finalising — the normal
         // closeProgressLane call below would call stream.finalize() which
         // sends a final "Done" edit to Telegram. Skip that for silent turns.
-        const suppressPrefix = `${chatId}:${threadId ?? '_'}:progress`
+        const suppressPrefix = chatKeyWithSuffix(chatId, threadId, 'progress')
         for (const [key] of activeDraftStreams) {
           if (key.startsWith(suppressPrefix)) {
             activeDraftStreams.delete(key)
@@ -6621,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)
@@ -7530,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'
   ) {
@@ -10978,6 +11033,7 @@ async function grantWizardStep2(ctx: Context, chatId: string, agent: string, wiz
   const kb = buildGrantKeysKeyboard(keys, selected)
   const text = `<b>Grant capability token — Step 2/3</b>\n\nWhich keys for <code>${escapeHtmlForTg(agent)}</code>?\n<i>Tap to toggle; tap Continue when done.</i>`
   if (wizardMsgId != null) {
+    // allow-raw-bot-api: vault grant wizard step 2/3; already .catch-swallows, tap-driven UI re-renders on retry
     await ctx.api.editMessageText(chatId, wizardMsgId, text, { parse_mode: 'HTML', reply_markup: kb }).catch(() => {})
   } else {
     const sent = await switchroomReply(ctx, text, { html: true, reply_markup: kb })
@@ -11001,6 +11057,7 @@ async function grantWizardStep3(ctx: Context, chatId: string, state: Extract<Pen
   const text = `<b>Grant capability token — Step 3/3</b>\n\nKeys for <code>${escapeHtmlForTg(state.agent!)}</code>:\n${keyList}\n\nHow long should this grant be valid?`
   const msgId = state.wizardMsgId
   if (msgId != null) {
+    // allow-raw-bot-api: vault grant wizard step 3/3 (TTL select); already .catch-swallows, tap-driven UI re-renders on retry
     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 })
@@ -11025,6 +11082,7 @@ async function grantWizardConfirm(ctx: Context, chatId: string, state: Extract<P
   ].join('\n')
   const msgId = state.wizardMsgId
   if (msgId != null) {
+    // allow-raw-bot-api: vault grant wizard confirm step; already .catch-swallows, tap-driven UI re-renders on retry
     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 })
@@ -13462,6 +13520,7 @@ function handleChecklistUpdate(
           ts: new Date(ts * 1000).toISOString(),
         },
       }
+      // allow-broadcast: informational checklist task notification, not turn-driving
       ipcServer.broadcast(inboundMsg)
       process.stderr.write(
         `telegram gateway: checklist ${kind}: chat_id=${chat_id} message_id=${message_id} task_id=${taskId} state=${state} user=${userName}\n`,
@@ -13913,7 +13972,7 @@ async function shutdown(signal: string): Promise<void> {
   // gateway no longer pre-allocates drafts on inbound, so there is
   // nothing to clear at SIGTERM time.
 
-  // Notify bridges so they can mark themselves disconnected.
+  // allow-broadcast: informational shutdown notify — bridges mark themselves disconnected
   ipcServer.broadcast({ type: 'status', status: 'gateway_shutting_down' })
 
   // Hard force-exit safety net at budget + 5s. systemd's TimeoutStopSec

package/telegram-plugin/pty-partial-handler.ts

@@ -94,7 +94,10 @@ export interface PtyHandlerDeps {
 }
 
 function streamKey(chatId: string, threadId?: number): string {
-  return `${chatId}:${threadId ?? '_'}`
+  // Canonical chat-key derivation lives in gateway/chat-key.ts — keep this
+  // expression in lockstep (treats 0/null/undefined the same). See #1564.
+  const t = threadId == null || threadId === 0 ? '_' : String(threadId)
+  return `${chatId}:${t}`
 }
 
 /**

package/telegram-plugin/stream-reply-handler.ts

@@ -313,7 +313,12 @@ function streamKey(
   lane?: string,
   turnKey?: string,
 ): string {
-  const base = `${chatId}:${threadId ?? '_'}`
+  // Canonical chat-key derivation lives in gateway/chat-key.ts — keep this
+  // expression in lockstep with that helper (treats 0/null/undefined the
+  // same), but inline here so this file doesn't introduce a cross-package
+  // import for one expression. See #1564 for the sibling-key bug class.
+  const t = threadId == null || threadId === 0 ? '_' : String(threadId)
+  const base = `${chatId}:${t}`
   const withLane = lane != null && lane.length > 0 ? `${base}:${lane}` : base
   return turnKey != null && turnKey.length > 0 ? `${withLane}:${turnKey}` : withLane
 }

package/telegram-plugin/tests/e2e.test.ts

@@ -50,7 +50,11 @@ function statusKey(chatId: string, threadId?: number): string {
 }
 
 function streamKey(chatId: string, threadId?: number): string {
-  return `${chatId}:${threadId ?? 'default'}`
+  // Mirrors production's canonical chat-key derivation (gateway/chat-key.ts):
+  // 0/null/undefined thread IDs all collapse to '_'. Diverging sentinels
+  // here would let the harness pass with a key shape production rejects.
+  const t = threadId == null || threadId === 0 ? '_' : String(threadId)
+  return `${chatId}:${t}`
 }
 
 interface PluginState {

package/telegram-plugin/tests/races.test.ts

@@ -29,7 +29,11 @@ function statusKey(chatId: string, threadId?: number): string {
   return `${chatId}:${threadId ?? '_'}`
 }
 function streamKey(chatId: string, threadId?: number): string {
-  return `${chatId}:${threadId ?? 'default'}`
+  // Mirrors production's canonical chat-key derivation (gateway/chat-key.ts):
+  // 0/null/undefined thread IDs all collapse to '_'. Diverging sentinels
+  // here would let the harness pass with a key shape production rejects.
+  const t = threadId == null || threadId === 0 ? '_' : String(threadId)
+  return `${chatId}:${t}`
 }
 
 interface PluginState {

package/telegram-plugin/uat/scenarios/jtbd-always-on-after-restart-dm.test.ts

@@ -0,0 +1,157 @@
+/**
+ * JTBD scenario — always-on vision: first message after restart replies
+ * quickly, NOT 5 minutes later via silence-poke fallback.
+ *
+ * Vision (`reference/vision.md`, see [[project_vision_reanchor_human_assistants]]):
+ * agents are always-on specialist exec-assistants. A 5-min blank
+ * window on the first message after restart is what BROKEN feels
+ * like to a user trying to use their assistant.
+ *
+ * ## The wedge this guards against
+ *
+ * Pre-v0.12.22, every agent restart produced ~5 min blank on the
+ * first user message in each thread:
+ *
+ *   1. User sends msg → handleInbound runs the fresh-turn branch
+ *      → activeTurnStartedAt.set(key, now) at gateway.ts:7357
+ *   2. The #1556 delivery gate further down (~7551) checks
+ *      activeTurnStartedAt.size > 0 to decide if a turn is "already
+ *      in flight" — sees the entry it just wrote → buffer-until-idle
+ *   3. Inbound stuck in pendingInboundBuffer. Bridge never sees it.
+ *      Claude never replies. activeTurnStartedAt[key] stays set.
+ *   4. ~300s later silence-poke framework-fallback fires, drains
+ *      the buffer, the reply finally lands — five minutes late.
+ *
+ * Documented in `feedback_5min_restart_wedge_violates_vision.md`.
+ * Fix is a one-line snapshot of the live size at receipt-time before
+ * the fresh-turn branch mutates the Map.
+ *
+ * ## What this UAT asserts
+ *
+ * After a deliberate restart, the FIRST message in a fresh thread
+ * gets a reply within a budget that excludes the silence-poke
+ * fallback floor (300s). Concretely we assert < 120s, which is
+ * generous for slow LLM replies but well below the wedge symptom.
+ *
+ * The test also makes a stricter observation log so a future
+ * regression that lands BETWEEN "wedge fixed" (~LLM latency) and
+ * "wedge present" (~5 min) is visible — e.g. some slow startup
+ * path that takes 60-90s would pass the contract but bear
+ * investigation.
+ *
+ * ## Why this scenario specifically
+ *
+ * - `smoke-dm-reply.test.ts` covers steady-state inbound→reply but
+ *   does NOT restart the agent first, so the wedge surfaces as a
+ *   "first message is slow" pattern that the smoke test would
+ *   silently absorb on warm runs.
+ * - `silent-end-recovery-dm.test.ts` covers mid-turn silent-end →
+ *   no-reply, but at 6 min budget — too generous to catch the
+ *   5-min wedge as a regression.
+ * - This is the FIRST UAT to explicitly tie the assertion to the
+ *   "always-on" vision and measure first-after-restart TTFO.
+ */
+
+import { describe, it, expect, beforeAll } from "vitest";
+import { execSync } from "node:child_process";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+
+// Budget for the marker-safe restart itself (per
+// feedback_agent_restart_needs_sudo_when_running.md, restart blocks
+// ~30s as the gateway's bridge reattaches).
+const RESTART_BUDGET_MS = 90_000;
+
+// Hard contract: first-after-restart reply must land in under 2 min.
+// This is generous for slow LLM replies but well below the 5-min
+// silence-poke fallback floor — a regression of the #1556 wedge
+// would trip on TTFO ≥ 300s and fail the test.
+const HARD_REPLY_BUDGET_MS = 120_000;
+
+// Vision-aligned target: real expectation is well under 30s on a
+// healthy fleet. A pass between 30-120s is yellow — covered by the
+// contract but worth logging for forensic visibility.
+const VISION_REPLY_BUDGET_MS = 30_000;
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function restartAgent(name: string): void {
+  // Marker-safe restart per memory feedback_compose_rollout.md +
+  // feedback_agent_restart_needs_sudo_when_running.md. Apply step
+  // self-elevates internally; restart needs the wrapper. We don't
+  // call apply here — the agent scaffolds are already current; only
+  // the in-memory state needs to reset.
+  execSync(
+    `sudo -n env PATH=$PATH HOME=$HOME switchroom agent restart ${name} --force`,
+    { stdio: ["ignore", "pipe", "pipe"], timeout: RESTART_BUDGET_MS },
+  );
+}
+
+// This scenario requires NOPASSWD sudo + the switchroom CLI on PATH on
+// the harness host. Skip on CI runners that don't expose those.
+const sudoOk = canShellSudo();
+
+(sudoOk ? describe : describe.skip)(
+  "uat: always-on after restart",
+  () => {
+    beforeAll(() => {
+      restartAgent(AGENT);
+      // Brief settle so the bridge sidecar finishes its reattach
+      // before we send the first inbound. The bridge-register log
+      // line is the earliest the agent can accept inbound.
+      return new Promise((r) => setTimeout(r, 5_000));
+    }, RESTART_BUDGET_MS + 10_000);
+
+    it(
+      "first message after fresh restart → reply within 2 min (NOT the 5-min wedge)",
+      async () => {
+        const sc = await spinUp({ agent: AGENT });
+        try {
+          const sendStart = Date.now();
+          await sc.sendDM("ping — JTBD always-on UAT");
+
+          const firstReply = await sc.expectMessage(/\S/, {
+            from: "bot",
+            timeout: HARD_REPLY_BUDGET_MS,
+          });
+          const ttfo = Date.now() - sendStart;
+
+          expect(firstReply.text.length).toBeGreaterThan(0);
+
+          // HARD CONTRACT: the wedge symptom is 300s+ TTFO. Anything
+          // ≥ HARD_REPLY_BUDGET_MS (120s) flags a regression of the
+          // #1556 self-blocking gate.
+          if (ttfo >= HARD_REPLY_BUDGET_MS) {
+            throw new Error(
+              `[always-on] first-post-restart reply took ${ttfo}ms — ` +
+              `matches the #1556 wedge symptom (5-min silence-poke fallback). ` +
+              `Vision broken; see feedback_5min_restart_wedge_violates_vision.md`,
+            );
+          }
+          expect(ttfo).toBeLessThan(HARD_REPLY_BUDGET_MS);
+
+          // Yellow-band log: passes the contract but degraded from the
+          // vision target. Worth investigating if this fires regularly.
+          if (ttfo >= VISION_REPLY_BUDGET_MS) {
+            console.warn(
+              `[always-on] first-post-restart TTFO=${ttfo}ms — passed ` +
+              `contract (${HARD_REPLY_BUDGET_MS}ms) but slower than the ` +
+              `vision target (${VISION_REPLY_BUDGET_MS}ms). Forensic flag.`,
+            );
+          }
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      HARD_REPLY_BUDGET_MS + 10_000,
+    );
+  },
+);