switchroom 0.18.8 → 0.18.9

package/telegram-plugin/gateway/gateway.ts

@@ -135,7 +135,17 @@ import {
   buildSecretRequestTimeoutInbound,
   buildMentalModelProposeTimeoutInbound,
 } from './approval-timeout-inbound-builders.js'
-import { expirePendingCard, sweepExpiredEntries } from './pending-card-expiry.js'
+import { expirePendingCard } from './pending-card-expiry.js'
+import { createSweepableCardStore } from './approval-card-stores.js'
+import {
+  createCallbackQueryHandlers,
+  type PendingVaultOp,
+  type DeferredSecret,
+  type PendingVaultRequestSave,
+  type PendingVaultRequestAccess,
+  type PendingMentalModelPropose,
+} from './callback-query-handlers.js'
+import { createSweepableStore, createPlainStore } from './pending-state-stores.js'
 import {
   isPermissionRearmEnabled,
   permissionRearmGraceMs,
@@ -173,8 +183,6 @@ import {
   createRetryApiCall,
   createSwallowingRetryApiCall,
   retryWithThreadFallback,
-  isHtmlParseRejectError,
-  isMessageTooLongError,
 } from '../retry-api-call.js'
 import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
 import { floodStatePath, makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
@@ -280,9 +288,16 @@ const REPLY_TO_TEXT_MAX = 200
 // #1161 silent-end fallback text now lives in ../silent-end.ts
 // (`silentEndFallbackText`, imported above) so the transport-boundary
 // tests exercise the real string — see PR #2892.
-import { splitMarkdownChunks, hardSliceToCap, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { splitMarkdownChunks, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, escapeMarkdown, hardenCardBreaks, RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { scrubVoice } from '../text-voice-scrub.js'
+import {
+  normalizeOutboundBody,
+  computeEffectiveText,
+  computeReplyChunks,
+  sendReplyChunks,
+  type ReplyChunkSendDeps,
+} from './outbound-send-path.js'
 import {
   validateInlineKeyboard,
   type AnyButton,
@@ -301,11 +316,8 @@ import {
   statusPairedText as buildStatusPairedText,
   statusPendingText as buildStatusPendingText,
   statusUnpairedText as buildStatusUnpairedText,
-  switchroomHelpText as buildSwitchroomHelpText,
   restartAckText as buildRestartAckText,
   newSessionAckText as buildNewSessionAckText,
-  TELEGRAM_BASE_COMMANDS,
-  TELEGRAM_SWITCHROOM_COMMANDS,
   type AgentMetadata, type AuthSummary, type StatusProbeRow,
 } from '../welcome-text.js'
 import {
@@ -405,6 +417,8 @@ import {
   type EffortCommandDeps,
   type EffortMenuReply,
 } from './effort-command.js'
+import { registerSwitchroomBotCommands } from './register-bot-commands.js'
+import { registerOpsInfoCommands } from './bot-commands-ops-info.js'
 import { applyEffort } from '../../src/agents/effort-picker.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
@@ -514,29 +528,13 @@ import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import { dispatchEffects, isDispatchEnabled } from './inbound-delivery-machine-dispatch.js'
 import { probeGateParity } from './gate-parity-probe.js'
 import { maybeFireWarmup } from './prefix-warmup.js'
-import {
-  buildVaultGrantApprovedInbound,
-  buildVaultGrantApprovedCardText,
-  buildVaultGrantDeniedInbound,
-  buildVaultSaveCompletedInbound,
-  buildVaultSaveFailedInbound,
-  buildVaultSaveDiscardedInbound,
-} from './vault-grant-inbound-builders.js'
 import { renderMentalModelProposeCard } from './mental-model-propose-card.js'
-import {
-  resolveMentalModelProposal,
-  type MentalModelPendingProposal,
-} from './mental-model-propose-resolve.js'
 import { readDeclaredMentalModelNames } from './mental-model-propose-diff.js'
 import {
-  parseSkillProposalCallback,
-  buildSkillProposalApplyInbound,
   renderSkillProposalCard,
   skillProposalKeyboard,
 } from './skill-proposal-card.js'
 import {
-  getProposal as getSkillProposal,
-  setProposalStatus as setSkillProposalStatus,
   enqueueProposal as enqueueSkillProposal,
   isSuppressed as isSkillProposalSuppressed,
 } from '../../src/self-improve/skill-proposals.js'
@@ -661,7 +659,7 @@ import {
   isLiveCorroboration,
 } from '../quota-watch.js'
 import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults } from '../auth-snapshot-format.js'
-import { maskUsername, maskVaultKey } from '../demo-mask.js'
+import { maskUsername } from '../demo-mask.js'
 import {
   writeTurnActiveMarker,
   touchTurnActiveMarker,
@@ -683,10 +681,8 @@ import {
   statusViaBroker,
   lockViaBroker,
   unlockViaBroker,
-  mintGrantViaBroker,
   listViaBroker,
   listGrantsViaBroker,
-  revokeGrantViaBroker,
 } from '../../src/vault/broker/client.js'
 import { emitLinearAgentActivity, createLinearIssue, buildLinearAuthDeadMessage, brokerRefreshIO, type LinearAuthDeadReason } from './linear-activity.js'
 import { runLinearAgentSetup } from './linear-setup.js'
@@ -698,7 +694,6 @@ import {
   approvalRecord,
 } from '../../src/vault/approvals/client.js'
 import { resolveVaultApprovalPosture } from '../vault-approval-posture.js'
-import { matchesAdminOnlyKey } from '../../src/vault/admin-only-keys.js'
 import {
   openTurnsDb,
   markOrphanedWithTimeoutClassification,
@@ -4939,24 +4934,8 @@ function probeAvailableReactions(chatId: string): void {
 // ─── Text chunking ────────────────────────────────────────────────────────
 const PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp'])
 
-function chunk(text: string, limit: number, mode: 'length' | 'newline'): string[] {
-  if (text.length <= limit) return [text]
-  const out: string[] = []
-  let rest = text
-  while (rest.length > limit) {
-    let cut = limit
-    if (mode === 'newline') {
-      const para = rest.lastIndexOf('\n\n', limit)
-      const line = rest.lastIndexOf('\n', limit)
-      const space = rest.lastIndexOf(' ', limit)
-      cut = para > limit / 2 ? para : line > limit / 2 ? line : space > 0 ? space : limit
-    }
-    out.push(rest.slice(0, cut))
-    rest = rest.slice(cut).replace(/^\n+/, '')
-  }
-  if (rest) out.push(rest)
-  return out
-}
+// The length/newline text splitter moved to outbound-send-path.ts (#2996) as
+// `chunkText`; the sole gateway caller now goes through `computeReplyChunks`.
 
 // ─── Typing indicator ─────────────────────────────────────────────────────
 // All four state maps re-keyed from `chat_id` to `chatKey(chat, thread)`
@@ -5409,14 +5388,15 @@ const PERMISSION_CARD_ORIGIN_MAX_AGE_MS = 30 * 60_000
 // other field finds no entry and falls through to a real operator card.
 // Single-shot (deleted on match) + 30s TTL sweep so a stale correlation
 // can't be replayed.
-const pendingAlwaysAllowCorrelations = new Map<string, { agentName: string; rule: string; unifiedDiff: string; createdAt: number }>()
 const ALWAYS_ALLOW_CORRELATION_TTL_MS = 30_000
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2): the
+// store owns the Map + co-locates the delete-past-TTL sweep. The TTL and its
+// comparison direction stay here in the injected predicate (byte-identical).
+const pendingAlwaysAllowCorrelations = createSweepableStore<{ agentName: string; rule: string; unifiedDiff: string; createdAt: number }>(
+  (entry, now) => now - entry.createdAt > ALWAYS_ALLOW_CORRELATION_TTL_MS,
+)
 function sweepStaleAlwaysAllowCorrelations(now = Date.now()): void {
-  for (const [key, entry] of pendingAlwaysAllowCorrelations) {
-    if (now - entry.createdAt > ALWAYS_ALLOW_CORRELATION_TTL_MS) {
-      pendingAlwaysAllowCorrelations.delete(key)
-    }
-  }
+  pendingAlwaysAllowCorrelations.sweep(now)
 }
 
 // Sibling of pendingAlwaysAllowCorrelations for the agent-proposes →
@@ -5439,16 +5419,17 @@ function sweepStaleAlwaysAllowCorrelations(now = Date.now()): void {
 // slow-but-valid tap, dropping the auto-approve and surfacing a SECOND card
 // for an edit the operator already approved. Size it to the hostd budget.
 const MENTAL_MODEL_CORRELATION_TTL_MS = 720_000
-const pendingMentalModelCorrelations = new Map<string, { agentName: string; unifiedDiff: string; createdAt: number }>()
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2). Same
+// pattern as pendingAlwaysAllowCorrelations, but the predicate closes over the
+// larger 720s TTL that must outlive the whole config-edit approval budget.
+const pendingMentalModelCorrelations = createSweepableStore<{ agentName: string; unifiedDiff: string; createdAt: number }>(
+  (entry, now) => now - entry.createdAt > MENTAL_MODEL_CORRELATION_TTL_MS,
+)
 function mentalModelCorrelationKey(agentName: string, unifiedDiff: string): string {
   return `${agentName}::${createHash('sha256').update(unifiedDiff).digest('hex')}`
 }
 function sweepStaleMentalModelCorrelations(now = Date.now()): void {
-  for (const [key, entry] of pendingMentalModelCorrelations) {
-    if (now - entry.createdAt > MENTAL_MODEL_CORRELATION_TTL_MS) {
-      pendingMentalModelCorrelations.delete(key)
-    }
-  }
+  pendingMentalModelCorrelations.sweep(now)
 }
 
 // Scoped-approval store: the 30-min window that backs the "✅ Allow" tap for
@@ -5486,10 +5467,19 @@ interface PendingAskUser {
   timer: ReturnType<typeof setTimeout>
   startedAt: number
 }
-const pendingAskUser = new Map<string, PendingAskUser>()
-
-// Reauth flows
-const pendingReauthFlows = new Map<string, { agent: string; startedAt: number }>()
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2). Plain
+// store (no TTL sweep): entries are bounded by per-entry timers and cleared on
+// resolution / shutdown / chat-close, not by the reaper.
+const pendingAskUser = createPlainStore<PendingAskUser>()
+
+// Reauth flows. Storage extracted to pending-state-stores.ts (#2996 Phase 3
+// step 2): the store owns the Map + co-locates the delete-past-TTL sweep the
+// reaper drove inline. Direction preserved: now - startedAt > TTL. The sweep
+// call stays in the SAME reaper position (first, ahead of the OAuth-code
+// cluster) so the awaitingAuthCodeAt contiguity pin is unaffected.
+const pendingReauthFlows = createSweepableStore<{ agent: string; startedAt: number }>(
+  (v, now) => now - v.startedAt > REAUTH_INTERCEPT_TTL_MS,
+)
 const REAUTH_INTERCEPT_TTL_MS = 10 * 60_000
 
 // #710: per-message agent-button metadata (ack_text / single_use). Keyed by
@@ -5501,7 +5491,11 @@ const REAUTH_INTERCEPT_TTL_MS = 10 * 60_000
 // design: when this map is empty (e.g. fresh process) the defaults apply
 // (`'✓ received'` toast + strip keyboard) — the agent only loses any
 // custom ack_text override.
-const agentButtonMeta = new Map<string, Map<string, AgentButtonMeta>>()
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2). Plain
+// store (no TTL sweep): bounded by the AGENT_BUTTON_META_MAX LRU cap enforced
+// in rememberAgentButtonMeta, not the reaper. keys().next().value gives the
+// oldest insertion for eviction — Map-surface parity preserved.
+const agentButtonMeta = createPlainStore<Map<string, AgentButtonMeta>>()
 const AGENT_BUTTON_META_MAX = 1000
 function rememberAgentButtonMeta(
   chatId: string | number,
@@ -5519,7 +5513,11 @@ function rememberAgentButtonMeta(
 }
 
 // Vault
-const vaultPassphraseCache = new Map<string, { passphrase: string; expiresAt: number }>()
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2). Absolute
+// expiry: the sweep deletes when now > expiresAt (direction preserved verbatim).
+const vaultPassphraseCache = createSweepableStore<{ passphrase: string; expiresAt: number }>(
+  (v, now) => now > v.expiresAt,
+)
 const VAULT_PASSPHRASE_TTL_MS = 30 * 60 * 1000
 
 /**
@@ -5599,249 +5597,70 @@ export function initVaultApprovalPosture(): void {
 const VAULT_KEY_REGEX = /^[A-Za-z0-9_./-]{1,200}$/
 /** Human-readable label embedded in error messages and rename prompts. */
 const VAULT_KEY_REGEX_LABEL = "[A-Za-z0-9_./-]{1,200}"
-type PendingVaultOp =
-  | { kind: 'passphrase'; op: 'list' | 'get' | 'delete' | 'set'; key?: string; startedAt: number }
-  | { kind: 'value'; op: 'set'; key: string; passphrase: string; startedAt: number }
-  // Issue #44: passphrase entry triggered by tapping "🔓 Unlock vault & save"
-  // on a deferred-secret card. After the passphrase is cached we look up the
-  // held secret by deferKey and write it directly — no re-paste required.
-  | {
-      kind: 'passphrase-for-deferred'
-      deferKey: string
-      cardChatId: string
-      cardMessageId: number
-      startedAt: number
-    }
-  // Issue #158: passphrase collected for /vault unlock — sent directly to the
-  // broker unlock socket, never logged or cached beyond the op itself.
-  | { kind: 'unlock'; startedAt: number }
-  // Issue #227: inline-keyboard wizard for /vault grant
-  | {
-      kind: 'grant-wizard'
-      step: 'agent' | 'keys' | 'duration' | 'confirm'
-      wizardMsgId?: number      // message to edit for each step
-      agent?: string
-      selectedKeys?: string[]   // keys toggled on in step 2
-      availableKeys?: string[]  // list fetched from broker
-      ttlSeconds?: number | null // null = never expires
-      expiresLabel?: string     // human-readable label for confirmation
-      description?: string
-      awaitingCustomDuration?: boolean  // true while waiting for text reply
-      /**
-       * Approval-kernel request_id minted at the wizard confirm step
-       * (MIGRATION.md §2, Phase 1 dual-dispatch — audit-only, advisory).
-       * When set, `vg:generate` ALSO consumes + records an `allow_once`
-       * decision on the kernel; `vg:cancel` records a `deny`. Cards in
-       * flight from before this PR landed have it `undefined` and the
-       * legacy `mintGrantViaBroker` runs alone — no kernel write. After
-       * 1-2 releases the legacy-only branch can be removed (#833 Phase 2
-       * is the enforcing flip).
-       */
-      kernel_request_id?: string
-      startedAt: number
-    }
-  // Issue #228: waiting for confirmation before revoking a grant.
-  | { kind: 'revoke_confirm'; grantId: string; agent: string; keys: string[]; startedAt: number }
-  // Issue #969 P1a: user tapped "Rename" on a vault_request_save card;
-  // the next message becomes the new key name for the staged save.
-  | { kind: 'rename-vault-save'; stageId: string; startedAt: number }
-  // Issue #1012 Phase 2 follow-up: operator tapped Approve on a
-  // vault_request_access card without first unlocking the vault. The
-  // next message becomes the passphrase — we cache it, delete the
-  // passphrase message, and auto-resume the approval mint flow without
-  // making the operator tap Approve a second time. Mirrors the
-  // `passphrase-for-deferred` flow from #44.
-  //
-  // #1051: `items` is a queue so concurrent Approve taps (operator
-  // taps card 2 before typing passphrase for card 1) don't strand
-  // earlier stages. On passphrase reply we process all queued items
-  // sequentially. Each item carries its own stageId + card refs;
-  // they're all in the same chat by construction (pendingVaultOps
-  // map is keyed by chat_id).
-  | {
-      kind: 'passphrase-for-access-approve'
-      items: Array<{
-        stageId: string
-        cardChatId: string
-        cardMessageId: number
-        senderId: string
-      }>
-      startedAt: number
-    }
+// PendingVaultOp moved to callback-query-handlers.ts (#2996 Phase 5).
 const VAULT_INPUT_TTL_MS = 5 * 60 * 1000
-const pendingVaultOps = new Map<string, PendingVaultOp>()
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2): the
+// store owns the Map + co-locates the delete-past-TTL sweep the reaper drove
+// inline. TTL + direction stay here (byte-identical: now - startedAt > TTL).
+const pendingVaultOps = createSweepableStore<PendingVaultOp>(
+  (v, now) => now - v.startedAt > VAULT_INPUT_TTL_MS,
+)
 
 // Secret-detection staging: ambiguous hits the user must confirm before we
 // store/delete. Also holds the deferred "we need a passphrase before we can
 // store this high-confidence hit" cases so the re-run after passphrase entry
 // is seamless.
 const secretStaging = new StagingMap()
-interface DeferredSecret {
-  chat_id: string
-  original_message_id: number
-  text: string
-  staged_at: number
-  /**
-   * Slug suggested by the detector at the time we deferred the secret.
-   * Captured up-front so the post-unlock auto-write doesn't have to re-run
-   * detection (which would have to handle the no-detection-fired case for
-   * Channel B context-rule defers — issue #44). Falls back to a generic
-   * slug if detection didn't fire.
-   */
-  suggested_slug: string
-  /**
-   * Approval-kernel request_id minted alongside the bespoke deferred-secret
-   * card (MIGRATION.md §1, Phase 1 dual-dispatch). When set, the
-   * `vd:unlock` / `vd:cancel` callback handler ALSO records the user's
-   * decision on the kernel side via `approvalConsume` + `approvalRecord`,
-   * so the audit log captures the unlock event.
-   *
-   * `undefined` on cards built before this PR landed (in-flight at deploy
-   * time) — the legacy handler runs alone, no kernel record. After ~1-2
-   * releases the legacy-only branch can be removed (separate cleanup PR).
-   */
-  kernel_request_id?: string
-}
-const deferredSecrets = new Map<string, DeferredSecret>()
+// DeferredSecret moved to callback-query-handlers.ts (#2996 Phase 5).
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2). The
+// isExpired predicate reads DEFERRED_SECRET_TTL_MS lazily at sweep time (it is
+// declared below this const but only referenced when the reaper sweeps, so the
+// TDZ never bites). Direction preserved: now - staged_at > TTL.
+const deferredSecrets = createSweepableStore<DeferredSecret>(
+  (v, now) => now - v.staged_at > DEFERRED_SECRET_TTL_MS,
+)
 
-/**
- * Agent-initiated save staging (issue #969 P1a). When an agent calls the
- * `vault_request_save` MCP tool, we stage the value here, render an
- * approval card to the user, and write to vault only on tap. The value
- * is held in gateway memory ONLY — never echoed back to the agent and
- * never logged.
- */
-interface PendingVaultRequestSave {
-  /** Agent that requested the save (process.env.SWITCHROOM_AGENT_NAME). */
-  agent: string
-  /** Chat to edit when the user taps. */
-  chat_id: string
-  /** Card message id (filled in after we send the card). */
-  card_message_id?: number
-  /** Supergroup forum topic the agent was working in when it requested the
-   *  save — carried into the save-outcome inbound so the resumed reply lands
-   *  back in that topic, not General. */
-  threadId?: number
-  /** Currently-suggested slug; may be renamed by the user. */
-  key: string
-  /** Storage shape — 'string' (default) or 'binary'. */
-  kind: 'string' | 'binary'
-  /** The secret value, held in memory until the user approves/discards. */
-  value: string
-  /** Optional rationale shown on the card. */
-  why?: string
-  /** Unix-ms timestamp; entries are reaped after VAULT_REQUEST_SAVE_TTL_MS. */
-  staged_at: number
-  /** Set on entries RESTORED from disk after a gateway restart. The staged
-   *  secret `value` is held in memory only (never persisted — secrets
-   *  hygiene), so a restored entry has an empty value and cannot complete the
-   *  write. A Save tap on such a card degrades gracefully: it tells the agent
-   *  the value was lost to a restart instead of writing an empty secret. */
-  restoredWithoutValue?: boolean
-}
-const pendingVaultRequestSaves = new Map<string, PendingVaultRequestSave>()
+// PendingVaultRequestSave moved to callback-query-handlers.ts (#2996 Phase 5).
 // Gateway-side reap window for a staged vault-save card. Tracks the operator
 // approval-card lifetime (config-driven, 60-min default) so the reap never
 // races ahead of the card the operator is still looking at.
 const VAULT_REQUEST_SAVE_TTL_MS = approvalTtlMs()
-function sweepPendingVaultRequestSaves(now = Date.now()): void {
-  sweepExpiredEntries(
-    pendingVaultRequestSaves,
-    (v, n) => v.staged_at < n - VAULT_REQUEST_SAVE_TTL_MS,
-    expireVaultSaveCard,
-    now,
-    cardExpiryLog,
-  )
-}
+// Storage extracted to approval-card-stores.ts (#2996 Phase 3): the store owns
+// the Map + co-locates the TTL sweep (`.sweep(now)`); expiry LOGIC
+// (expireVaultSaveCard) is still gateway-side, injected as a thunk. Call sites
+// (get/set/delete/iteration/restore) are byte-identical — same variable, same
+// Map surface.
+const pendingVaultRequestSaves = createSweepableCardStore<PendingVaultRequestSave>({
+  isExpired: (v, n) => v.staged_at < n - VAULT_REQUEST_SAVE_TTL_MS,
+  expire: () => expireVaultSaveCard,
+  log: () => cardExpiryLog,
+})
 
-/**
- * Issue #1012 — agent-initiated vault ACL request. The agent calls
- * `vault_request_access` when it hits VAULT-BROKER-DENIED (or
- * preemptively, when it knows it'll need a key it doesn't yet have).
- * The card carries [Approve] / [Deny] inline buttons; only the
- * operator can mint the grant (same authorization gate as the
- * existing /vault audit one-tap allow flow). The agent never sees
- * the grant token directly — `mintGrantViaBroker` writes it to the
- * agent's `.vault-token` file, which the agent's CLI reads on the
- * next vault request.
- *
- * Mirrors PendingVaultRequestSave above (#969 P1a). No secret
- * material is staged here — only the request metadata.
- */
-interface PendingVaultRequestAccess {
-  /** Agent that initiated the request (process.env.SWITCHROOM_AGENT_NAME). */
-  agent: string
-  /** Chat the card was rendered into; edited on tap. */
-  chat_id: string
-  /** Card message id (filled in after we send the card). */
-  card_message_id?: number
-  /** Supergroup forum topic the agent was working in when it requested (the
-   *  card's originating thread). Carried into the grant-outcome inbound so the
-   *  resumed reply lands back in that topic, not General. */
-  threadId?: number
-  /** Vault key the agent wants to read. */
-  key: string
-  /** 'read' (default) or 'write'. */
-  scope: 'read' | 'write'
-  /** Optional rationale the agent supplied; rendered on the card. */
-  reason?: string
-  /** Grant TTL in seconds (max 90 days; null = never, refused). */
-  ttl_seconds: number
-  /** Unix-ms timestamp; entries are reaped after VAULT_REQUEST_ACCESS_TTL_MS. */
-  staged_at: number
-}
-const pendingVaultRequestAccesses = new Map<string, PendingVaultRequestAccess>()
+// PendingVaultRequestAccess moved to callback-query-handlers.ts (#2996 Phase 5).
 // Gateway-side reap window for a staged vault-access card. Tracks the operator
 // approval-card lifetime (config-driven, 60-min default) — see approvalTtlMs.
 const VAULT_REQUEST_ACCESS_TTL_MS = approvalTtlMs()
-function sweepPendingVaultRequestAccesses(now = Date.now()): void {
-  sweepExpiredEntries(
-    pendingVaultRequestAccesses,
-    (v, n) => v.staged_at < n - VAULT_REQUEST_ACCESS_TTL_MS,
-    expireVaultAccessCard,
-    now,
-    cardExpiryLog,
-  )
-}
+// Storage extracted to approval-card-stores.ts (#2996 Phase 3) — see the
+// vault-save store above for the pattern.
+const pendingVaultRequestAccesses = createSweepableCardStore<PendingVaultRequestAccess>({
+  isExpired: (v, n) => v.staged_at < n - VAULT_REQUEST_ACCESS_TTL_MS,
+  expire: () => expireVaultAccessCard,
+  log: () => cardExpiryLog,
+})
 
-/**
- * Staged agent-initiated MENTAL MODEL proposal (hindsight Phase 5). The agent
- * calls `mental_model_propose`; the operator taps Approve/Deny on the card.
- * Mirrors PendingVaultRequestAccess — no memory content is staged here, only
- * the proposed DECLARATION (name + source_query + optional knobs). On Approve
- * the model becomes a first-class declared model in memory.mental_models[] via
- * the operator-approved config-edit path; on Deny nothing is written.
- */
-interface PendingMentalModelPropose {
-  agent: string
-  chat_id: string
-  card_message_id?: number
-  threadId?: number
-  /** Proposed declaration, snake_case (matches memory.mental_models[] schema). */
-  spec: {
-    name: string
-    source_query: string
-    refresh_after_consolidation?: boolean
-    max_tokens?: number
-  }
-  reason?: string
-  staged_at: number
-}
-const pendingMentalModelProposes = new Map<string, PendingMentalModelPropose>()
+// PendingMentalModelPropose moved to callback-query-handlers.ts (#2996 Phase 5).
 const MENTAL_MODEL_PROPOSE_TTL_MS = approvalTtlMs()
-// Sweep expired pending proposals. For any entry past its TTL we ALSO edit the
-// posted card's keyboard away, so a stale card left in the chat can't be tapped
-// into a "Card expired" answer — the operator sees the ⌛ expiry inline instead.
-// Best-effort: card edits are fire-and-forget (the entry is removed regardless).
-function sweepPendingMentalModelProposes(now = Date.now()): void {
-  sweepExpiredEntries(
-    pendingMentalModelProposes,
-    (v, n) => v.staged_at < n - MENTAL_MODEL_PROPOSE_TTL_MS,
-    expireMentalModelProposeCard,
-    now,
-    cardExpiryLog,
-  )
-}
+// Storage extracted to approval-card-stores.ts (#2996 Phase 3). The store's
+// `.sweep(now)` expires past-TTL proposals; for any expired entry the injected
+// expireMentalModelProposeCard ALSO edits the posted card's keyboard away, so a
+// stale card left in the chat can't be tapped into a "Card expired" answer — the
+// operator sees the ⌛ expiry inline instead. Best-effort: card edits are
+// fire-and-forget (the entry is removed regardless).
+const pendingMentalModelProposes = createSweepableCardStore<PendingMentalModelPropose>({
+  isExpired: (v, n) => v.staged_at < n - MENTAL_MODEL_PROPOSE_TTL_MS,
+  expire: () => expireMentalModelProposeCard,
+  log: () => cardExpiryLog,
+})
 
 // Sliding-window rate limit for mental-model proposals: at most
 // MENTAL_MODEL_PROPOSE_MAX_PER_WINDOW cards per MENTAL_MODEL_PROPOSE_WINDOW_MS.
@@ -6026,9 +5845,10 @@ const DEFERRED_SECRET_TTL_MS = 24 * 60 * 60_000 // 24 h — ignored one-tap card
 // Freshness throttle for `auth:refresh` taps. Keyed by `<chat_id>:<message_id>`
 // so two different snapshot messages throttle independently. Each refresh
 // fan-fires N live api.anthropic.com probes (one per account), so we cap
-// rapid re-taps to one per AUTH_REFRESH_THROTTLE_MS.
+// rapid re-taps to one per AUTH_REFRESH_THROTTLE_MS (the constant moved to
+// callback-query-handlers.ts with the handler; this map's 60s reaper stays
+// gateway-side below).
 const lastAuthRefreshAtMs = new Map<string, number>()
-const AUTH_REFRESH_THROTTLE_MS = 5_000
 
 // ─── TTL reaper ───────────────────────────────────────────────────────────
 // Pending state maps above all grow whenever a flow starts and only shrink
@@ -6285,9 +6105,9 @@ function expireMentalModelProposeCard(stageId: string, v: PendingMentalModelProp
 // per-entry guarded via sweepExpiredEntries, so one throwing expiry (dead IPC
 // socket, store IO error) can't skip the remaining entries or families.
 function sweepExpiredApprovalCards(now: number): void {
-  sweepPendingVaultRequestAccesses(now)
-  sweepPendingVaultRequestSaves(now)
-  sweepPendingMentalModelProposes(now)
+  pendingVaultRequestAccesses.sweep(now)
+  pendingVaultRequestSaves.sweep(now)
+  pendingMentalModelProposes.sweep(now)
   sweepSecretRequests(now)
 }
 
@@ -6371,9 +6191,7 @@ function restorePendingApprovalCards(): number {
 const pendingStateReaper = setInterval(() => {
   const now = Date.now()
   // OAuth-code state grouped first (pinned by secret-detect-oauth-code.test.ts).
-  for (const [k, v] of pendingReauthFlows) {
-    if (now - v.startedAt > REAUTH_INTERCEPT_TTL_MS) pendingReauthFlows.delete(k)
-  }
+  pendingReauthFlows.sweep(now)
   for (const [k, v] of pendingAuthAddFlows) {
     if (now - v.startedAt > REAUTH_INTERCEPT_TTL_MS) {
       cancelAccountAuthSession(v)
@@ -6404,9 +6222,7 @@ const pendingStateReaper = setInterval(() => {
   for (const [k, v] of pendingAuthRmFlows) {
     if (now >= v.expiresAt) pendingAuthRmFlows.delete(k)
   }
-  for (const [k, v] of pendingVaultOps) {
-    if (now - v.startedAt > VAULT_INPUT_TTL_MS) pendingVaultOps.delete(k)
-  }
+  pendingVaultOps.sweep(now)
   for (const [k, v] of pendingPermissions) {
     // hostd gated fleet-mutation verbs get a longer (30-min) human-scale
     // decision window than the 10-min default (Bug 2 fix #2).
@@ -6485,9 +6301,7 @@ const pendingStateReaper = setInterval(() => {
   for (const [sig, at] of permissionTimeoutSignatures) {
     if (now - at > PERMISSION_DUPLICATE_WINDOW_MS) permissionTimeoutSignatures.delete(sig)
   }
-  for (const [k, v] of vaultPassphraseCache) {
-    if (now > v.expiresAt) vaultPassphraseCache.delete(k)
-  }
+  vaultPassphraseCache.sweep(now)
   // Drop expired "⏱ 30 min" scoped grants. (Lookup already fails closed on
   // expiry; this just keeps the map from accumulating dead entries.) Persist
   // the removal so a restart between sweeps can't resurrect a swept grant —
@@ -6497,9 +6311,7 @@ const pendingStateReaper = setInterval(() => {
   if (countScopedGrants(scopedGrants) !== scopedGrantsBefore) {
     scopedGrantStore.save(scopedGrants)
   }
-  for (const [k, v] of deferredSecrets) {
-    if (now - v.staged_at > DEFERRED_SECRET_TTL_MS) deferredSecrets.delete(k)
-  }
+  deferredSecrets.sweep(now)
   // Agent-initiated approval cards (vault_request_access / vault_request_save /
   // request_secret / mental_model_propose): expire past-TTL entries and WAKE
   // the parked agent (timeout synthetic + missed-approvals re-offer). This is
@@ -10998,37 +10810,23 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // Repair LLM JSON-escape bungles, then promote lone prose paragraph breaks
   // into GFM hard breaks so the rich path doesn't collapse them (lists/tables/
   // code are left untouched — see normalizeParagraphBreaks).
-  let text = normalizeParagraphBreaks(repairEscapedWhitespace(rawText))
-  // Outbound secret scrub (#2044): mask any secret the agent echoed BEFORE
-  // the stderr preview below, the dedup key, the send, and the history
-  // record. Mutates `text` so every downstream consumer sees the masked
-  // value, exactly like the voice scrub that follows. Runs BEFORE the
-  // punctuation/bold normalizers so a secret containing an em-dash or `**`
-  // is matched literally by the redactor before any mutation.
-  text = redactOutboundText(text, 'reply')
-  // Fleet-wide consistent formatting: normalize dashes/bullets and trip the
-  // over-bold guard deterministically, on code-masked text (same contract on
-  // reply / edit / stream paths). Runs before scrubVoice below so dashes get
-  // the comma treatment on every path; scrubVoice's dash telemetry
-  // (voice_scrub_applied) drops to ~zero here as a result — deliberate.
-  text = stripExcessBold(normalizePunctuation(text))
-  // Voice scrub (#1683): replace em / en dashes with commas / periods.
-  // Runs BEFORE outboundDedup so retries see the scrubbed key, and on the
-  // raw markdown text (the scrubber does its own code-region parking so
-  // dashes inside fences/inline code are preserved). Kill switch:
-  // `SWITCHROOM_DISABLE_VOICE_SCRUB=1`.
-  {
-    const scrub = scrubVoice(text)
-    if (scrub.replaced > 0) {
-      text = scrub.scrubbed
-      emitRuntimeMetric({
-        kind: 'voice_scrub_applied',
-        chatKey: statusKey(chat_id, args.message_thread_id != null
-          ? Number(args.message_thread_id) : undefined),
-        replaced: scrub.replaced,
-        site: 'reply',
-      })
-    }
+  // Outbound text pipeline (#2996 §3B): normalize → redact → punctuation/bold
+  // → voice-scrub, extracted verbatim into outbound-send-path.ts. The order is
+  // load-bearing (secret scrub BEFORE the punctuation/bold normalizers so a
+  // secret with an em-dash or `**` is matched literally; voice scrub last so
+  // retries see the scrubbed dedup key). The metric side effect (fired on a
+  // non-zero voice-scrub replacement) stays here — the pure module returns the
+  // replacement count and the gateway emits.
+  const _normalized = normalizeOutboundBody(rawText, 'reply', redactOutboundText)
+  let text = _normalized.text
+  if (_normalized.voiceReplaced > 0) {
+    emitRuntimeMetric({
+      kind: 'voice_scrub_applied',
+      chatKey: statusKey(chat_id, args.message_thread_id != null
+        ? Number(args.message_thread_id) : undefined),
+      replaced: _normalized.voiceReplaced,
+      site: 'reply',
+    })
   }
   process.stderr.write(`telegram channel: reply: invoked chatId=${chat_id} charCount=${text.length} preview=${JSON.stringify(text.slice(0, 80))}\n`)
   // #2527: emit time_to_first_text_reply_ms on the FIRST text reply of each
@@ -11249,7 +11047,7 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // jammed together — unlike the old HTML path. Inject a visible blank-line
   // spacer into prose `\n\n` gaps on the rich path only. The literal
   // (`format:'text'`) path must stay byte-exact, so it is left untouched.
-  const effectiveText: string = literalText ? text : addParagraphSpacers(text)
+  const effectiveText: string = computeEffectiveText(text, literalText)
 
   assertAllowedChat(chat_id)
 
@@ -11313,9 +11111,12 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
 
   const limit = Math.max(1, Math.min(access.textChunkLimit ?? RICH_MESSAGE_MAX_CHARS, MAX_CHUNK_LIMIT))
   const replyMode = access.replyToMode ?? 'first'
-  const chunks = literalText
-    ? chunk(effectiveText, limit, access.chunkMode ?? 'length')
-    : splitMarkdownChunks(effectiveText, limit)
+  const chunks = computeReplyChunks({
+    effectiveText,
+    literalText,
+    limit,
+    chunkMode: access.chunkMode ?? 'length',
+  })
   const sentIds: number[] = []
 
   // Outbound TTS synthesis (PR-C2). Done BEFORE the text send so a
@@ -11700,162 +11501,83 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     }
   }
 
+  // #2996 step 1 — the chunk-send loop (with its THREAD_NOT_FOUND / oversize
+  // re-split / parse-reject fallback ladder and partial-failure contract) is
+  // relocated verbatim to outbound-send-path.ts's `sendReplyChunks` so it is
+  // unit-testable against a fake bot API (gateway.ts is not importable —
+  // Bun.listen + boot logic run at import). The raw `bot.api.*` calls stay HERE
+  // as thin injected adapters (retry wrapping + allow-raw-bot-api markers
+  // preserved), so the module is bot-agnostic and the check-bot-api-wrapping
+  // allowlist is unchanged. The caller still builds the per-chunk option shape
+  // (byte-identical). `sentIds` is threaded by reference; `threadId` /
+  // `previewMessageId` come back for the file-send + history code below.
+  const chunkSendDeps: ReplyChunkSendDeps = {
+    sendRich: (opts, body, tid) =>
+      robustApiCall(
+        // allow-raw-bot-api: injected chunk-loop adapter — sendRichMessage routed through robustApiCall; THREAD_NOT_FOUND handled by sendReplyChunks' fallback ladder
+        () => lockedBot.api.sendRichMessage(chat_id, body as never, opts as never),
+        { threadId: tid, chat_id },
+      ),
+    sendLiteral: (opts, txt, tid) =>
+      robustApiCall(
+        // allow-raw-bot-api: injected chunk-loop adapter — literal format:'text' send routed through robustApiCall; THREAD_NOT_FOUND handled by sendReplyChunks
+        () => lockedBot.api.sendMessage(chat_id, txt, opts as never),
+        { threadId: tid, chat_id },
+      ),
+    sendLiteralRaw: (opts, txt) =>
+      // allow-raw-bot-api: literal last-resort fallback (plaintext parse-reject / length re-split); wrapping would re-enter the parse/length policy that just rejected the payload
+      lockedBot.api.sendMessage(chat_id, txt, opts as never),
+    sendRichRaw: (opts, body) =>
+      // allow-raw-bot-api: rich length-error re-split last resort; wrapping would re-enter the chunk-loop's own classification on an already-classified length failure
+      lockedBot.api.sendRichMessage(chat_id, body as never, opts as never),
+    editPreview: (mid, body, opts, tid) =>
+      robustApiCall(
+        // allow-raw-bot-api: preview edit-in-place routed through robustApiCall; thread fallback handled by sendReplyChunks
+        () => lockedBot.api.editMessageText(chat_id, mid, body as never, opts as never),
+        { threadId: tid, chat_id },
+      ),
+    richMessage,
+    logOutbound,
+    deleteStalePreview,
+    stderr: (s: string) => { process.stderr.write(s) },
+  }
   try {
-    for (let i = 0; i < chunks.length; i++) {
-      // PR-C2: voice-only mode with a successful synthesis suppresses the
-      // text body — the spoken voice note IS the reply. Bail before the
-      // first chunk send (sentIds stays empty for text); the voice send
-      // below lands the answer. Any other mode (voice+text, or voice-only
-      // that fell back) sends the text chunks as normal.
-      if (suppressText) break
-      const shouldReplyTo =
-        reply_to != null && replyMode !== 'off' && (replyMode === 'all' || i === 0)
-      const isLastChunk = i === chunks.length - 1
-      const sendOpts = {
-        ...(shouldReplyTo
-          ? {
-              reply_parameters: {
-                message_id: reply_to,
-                ...(quoteText != null ? { quote: { text: quoteText, position: 0 } } : {}),
-              },
-            }
-          : {}),
-        ...(threadId != null ? { message_thread_id: threadId } : {}),
-        ...(disableLinkPreview ? { link_preview_options: { is_disabled: true } } : {}),
-        ...(replyMarkup != null && isLastChunk ? { reply_markup: replyMarkup } : {}),
-        ...(protectContent ? { protect_content: true } : {}),
-        ...(disableNotification ? { disable_notification: true } : {}),
-      }
-
-      // The body argument for send/edit: a rich-markdown wrapper on the
-      // default path, or the literal string for `format:'text'` (#2669).
-      const richOrPlain = (s: string) => (literalText ? s : richMessage(s))
-
-      if (i === 0 && previewMessageId != null) {
+    const _sendResult = await sendReplyChunks(chunkSendDeps, {
+      chatId: chat_id,
+      chunks,
+      literalText,
+      suppressText,
+      threadId,
+      previewMessageId,
+      sentIds,
+      buildSendOpts: (i, isLastChunk, tid) => {
+        const shouldReplyTo =
+          reply_to != null && replyMode !== 'off' && (replyMode === 'all' || i === 0)
+        return {
+          ...(shouldReplyTo
+            ? {
+                reply_parameters: {
+                  message_id: reply_to,
+                  ...(quoteText != null ? { quote: { text: quoteText, position: 0 } } : {}),
+                },
+              }
+            : {}),
+          ...(tid != null ? { message_thread_id: tid } : {}),
+          ...(disableLinkPreview ? { link_preview_options: { is_disabled: true } } : {}),
+          ...(replyMarkup != null && isLastChunk ? { reply_markup: replyMarkup } : {}),
+          ...(protectContent ? { protect_content: true } : {}),
+          ...(disableNotification ? { disable_notification: true } : {}),
+        }
+      },
+      buildPreviewEditOpts: (isLastChunk) => {
         const editOpts: Record<string, unknown> = {}
         if (disableLinkPreview) editOpts.link_preview_options = { is_disabled: true }
         if (replyMarkup != null && isLastChunk) editOpts.reply_markup = replyMarkup
-        try {
-          await robustApiCall(
-            () => lockedBot.api.editMessageText(chat_id, previewMessageId!, richOrPlain(chunks[i]), editOpts),
-            { threadId, chat_id },
-          )
-          sentIds.push(previewMessageId!)
-          previewMessageId = null
-          continue
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err)
-          if (/not modified/i.test(msg)) {
-            sentIds.push(previewMessageId!)
-            previewMessageId = null
-            continue
-          }
-          process.stderr.write(`telegram gateway: preview edit-in-place failed (${msg}), sending fresh\n`)
-          await deleteStalePreview(previewMessageId!)
-          previewMessageId = null
-        }
-      }
-
-      // Last-resort: resend this chunk as plain text (no rich wrapper, so
-      // the markdown parser never runs). Keeps thread / reply / markup
-      // params; only the formatting is sacrificed. Used when Telegram
-      // rejects our markdown — better an unformatted answer than a
-      // vanished one. The raw markdown source is itself readable prose, so
-      // we send it verbatim rather than strip anything.
-      const sendChunkPlainText = async (opts: Record<string, unknown>): Promise<void> => {
-        const plain =
-          chunks[i].length > 0
-            ? chunks[i]
-            : '⚠️ (a fragment could not be rendered for Telegram)'
-        // allow-raw-bot-api: plaintext last-resort fallback; wrapping would re-enter the parse policy that just rejected the payload
-        const sent = await lockedBot.api.sendMessage(chat_id, plain, opts as never)
-        sentIds.push(sent.message_id)
-        logOutbound('reply', chat_id, sent.message_id, plain.length, `chunk=${i + 1}/${chunks.length} plaintext-fallback`)
-        process.stderr.write(
-          `telegram gateway: markdown parse-reject — resent chunk ${i + 1}/${chunks.length} as plain text\n`,
-        )
-      }
-
-      // Literal `format:'text'` sends bypass the rich parser entirely
-      // (plain sendMessage, no markdown). The default path ships rich
-      // markdown via sendRichMessage. Both resolve to a Message with a
-      // message_id, which is all the caller reads.
-      const sendChunk = (opts: Record<string, unknown>): Promise<{ message_id: number }> => {
-        if (literalText) {
-          // allow-raw-bot-api: literal format:'text' send; the chunk-loop's own THREAD_NOT_FOUND + parse-reject handling wraps this
-          return lockedBot.api.sendMessage(chat_id, chunks[i], opts as never)
-        }
-        // sendRichMessage does NOT accept link_preview_options (rich messages
-        // control previews via entity detection) — drop it for the rich path.
-        const richOpts = { ...opts }
-        delete (richOpts as { link_preview_options?: unknown }).link_preview_options
-        // allow-raw-bot-api: sendRichMessage is not in the THREAD_NOT_FOUND blast pattern; thread fallback handled in the catch below
-        return lockedBot.api.sendRichMessage(chat_id, richMessage(chunks[i]), richOpts as never)
-      }
-
-      // Length-error recovery: a single pre-computed chunk can still exceed the
-      // wire cap when splitMarkdownChunks hit an indivisible region and emitted
-      // it whole (a giant fenced block, a no-boundary blob). Telegram answers
-      // with RICH_MESSAGE_TEXT_TOO_LONG / MESSAGE_TOO_LONG. Re-split this chunk
-      // at a harder boundary and send each piece, rather than misclassifying it
-      // as a parse-reject (which would resend the same oversized payload as
-      // plain text) or surfacing the raw 400.
-      const sendChunkResplit = async (opts: Record<string, unknown>): Promise<void> => {
-        // Re-split at the same cap; for a truly indivisible block this still
-        // yields one oversized piece, but a hard character-cut on the rendered
-        // markdown at least keeps each delivered piece under the wire cap.
-        const subPieces = splitMarkdownChunks(chunks[i], RICH_MESSAGE_MAX_CHARS)
-        const pieces =
-          subPieces.length > 1
-            ? subPieces
-            : hardSliceToCap(chunks[i], RICH_MESSAGE_MAX_CHARS)
-        for (let p = 0; p < pieces.length; p++) {
-          let sent: { message_id: number }
-          if (literalText) {
-            // allow-raw-bot-api: length-error re-split last resort (literal text); wrapping would re-enter the chunk-loop's own classification on an already-classified length failure.
-            sent = await lockedBot.api.sendMessage(chat_id, pieces[p], opts as never)
-          } else {
-            const ro = { ...opts }
-            delete (ro as { link_preview_options?: unknown }).link_preview_options
-            // allow-raw-bot-api: length-error re-split last resort (rich); wrapping would re-enter the chunk-loop's own classification on an already-classified length failure.
-            sent = await lockedBot.api.sendRichMessage(chat_id, richMessage(pieces[p]), ro as never)
-          }
-          sentIds.push(sent.message_id)
-          logOutbound('reply', chat_id, sent.message_id, pieces[p].length, `chunk=${i + 1}/${chunks.length} resplit=${p + 1}/${pieces.length}`)
-        }
-        process.stderr.write(
-          `telegram gateway: rich body too long — re-split chunk ${i + 1}/${chunks.length} into ${pieces.length} piece(s)\n`,
-        )
-      }
-
-      try {
-        const sent = await robustApiCall(() => sendChunk(sendOpts), { threadId, chat_id })
-        sentIds.push(sent.message_id)
-        logOutbound('reply', chat_id, sent.message_id, chunks[i].length, `chunk=${i + 1}/${chunks.length}`)
-      } catch (err) {
-        if (err instanceof Error && err.message === 'THREAD_NOT_FOUND') {
-          threadId = undefined
-          const retryOpts = { ...sendOpts }
-          delete (retryOpts as any).message_thread_id
-          try {
-            const sent = await sendChunk(retryOpts)
-            sentIds.push(sent.message_id)
-          } catch (retryErr) {
-            // Thread dropped, AND another failure: length → re-split,
-            // parse-reject → plain text, else propagate.
-            if (isMessageTooLongError(retryErr)) await sendChunkResplit(retryOpts)
-            else if (isHtmlParseRejectError(retryErr)) await sendChunkPlainText(retryOpts)
-            else throw retryErr
-          }
-        } else if (isMessageTooLongError(err)) {
-          await sendChunkResplit(sendOpts)
-        } else if (isHtmlParseRejectError(err)) {
-          await sendChunkPlainText(sendOpts)
-        } else {
-          throw err
-        }
-      }
-    }
+        return editOpts
+      },
+    })
+    threadId = _sendResult.threadId
+    previewMessageId = _sendResult.previewMessageId
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
     throw new Error(`reply failed after ${sentIds.length} of ${chunks.length} chunk(s) sent: ${msg}`)
@@ -12699,7 +12421,7 @@ async function executeVaultRequestSave(args: Record<string, unknown>): Promise<{
     staged_at: Date.now(),
   }
   pendingVaultRequestSaves.set(stageId, pending)
-  sweepPendingVaultRequestSaves()
+  pendingVaultRequestSaves.sweep(Date.now())
 
   // Send the approval card. #1075: route through retryWithThreadFallback
   // so a deleted topic still lands the card on the main chat instead of
@@ -12767,29 +12489,32 @@ interface PendingSecretRequest {
    *  in that topic, not General. */
   threadId?: number
 }
-// stageId -> request (lives until tapped or TTL).
-const pendingSecretRequests = new Map<string, PendingSecretRequest>()
 // chat_id -> the armed capture: the operator's NEXT message in this chat is
 // the value for `key`. Set when [Provide securely] is tapped.
 interface ArmedSecretCapture { key: string; agent: string; stageId: string; armed_at: number; threadId?: number }
-const armedSecretCaptures = new Map<string, ArmedSecretCapture>()
+// Storage extracted to pending-state-stores.ts (#2996 Phase 3 step 2). Swept by
+// sweepSecretRequests (below) — a plain delete-past-TTL, no wake (transient
+// post-tap window). Direction preserved: now - armed_at > TTL.
+const armedSecretCaptures = createSweepableStore<ArmedSecretCapture>(
+  (v, now) => now - v.armed_at > ARMED_SECRET_CAPTURE_TTL_MS,
+)
 const PENDING_SECRET_REQUEST_TTL_MS = 30 * 60_000 // card lifetime
 const ARMED_SECRET_CAPTURE_TTL_MS = 10 * 60_000   // window to send the value after tapping
+// stageId -> request (lives until tapped or TTL). Storage extracted to
+// approval-card-stores.ts (#2996 Phase 3): the store owns the Map + co-locates
+// the TTL sweep; expireSecretRequestCard (the wake logic) stays gateway-side.
+const pendingSecretRequests = createSweepableCardStore<PendingSecretRequest>({
+  isExpired: (v, n) => n - v.staged_at > PENDING_SECRET_REQUEST_TTL_MS,
+  expire: () => expireSecretRequestCard,
+  log: () => cardExpiryLog,
+})
 
 function sweepSecretRequests(now = Date.now()): void {
-  sweepExpiredEntries(
-    pendingSecretRequests,
-    (v, n) => n - v.staged_at > PENDING_SECRET_REQUEST_TTL_MS,
-    expireSecretRequestCard,
-    now,
-    cardExpiryLog,
-  )
+  pendingSecretRequests.sweep(now)
   // armedSecretCaptures is a TRANSIENT post-tap window (never persisted): it's
   // only set after the operator taps [Provide securely], and the request is
   // no longer parked-on-a-card. Just drop stale ones — no wake needed.
-  for (const [k, v] of armedSecretCaptures) {
-    if (now - v.armed_at > ARMED_SECRET_CAPTURE_TTL_MS) armedSecretCaptures.delete(k)
-  }
+  armedSecretCaptures.sweep(now)
 }
 
 function buildSecretRequestKeyboard(stageId: string): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
@@ -13189,7 +12914,7 @@ async function executeVaultRequestAccess(args: Record<string, unknown>): Promise
     staged_at: Date.now(),
   }
   pendingVaultRequestAccesses.set(stageId, pending)
-  sweepPendingVaultRequestAccesses()
+  pendingVaultRequestAccesses.sweep(Date.now())
 
   // renderVaultRequestAccessCard self-hardens its field line breaks (this card
   // is sent direct, bypassing the switchroomReply chokepoint).
@@ -13371,7 +13096,7 @@ async function executeMentalModelPropose(args: Record<string, unknown>): Promise
     staged_at: Date.now(),
   }
   pendingMentalModelProposes.set(stageId, pending)
-  sweepPendingMentalModelProposes()
+  pendingMentalModelProposes.sweep(Date.now())
 
   const text = renderMentalModelProposeCard({
     agent: agentSlug,
@@ -18039,13 +17764,20 @@ async function handleInbound(
   // isSteering is now the real classification (computed at ~line 16289), so
   // the machine correctly distinguishes a mid-turn steer (delivered, no new
   // turn) from a fresh turn.
-  shadowEmit({
+  // PR3c cutover (#2794 / #2996): the payload now carries the REAL
+  // ipc-protocol InboundMessage (previously null) so the machine's
+  // deliverToBridge / bufferInbound / persistInbound effects are executable,
+  // and the returned effects are CAPTURED — under the cutover they are
+  // dispatched below and become the authoritative deliver-vs-buffer routing.
+  // The machine treats the payload as opaque, so the kill-switch shadow
+  // trace is unchanged.
+  const machineInboundEffects = shadowEmit({
     kind: 'inbound',
     key: statusKey(chat_id, messageThreadId) as _ChatKey,
     msg: {
       msgId: msgId ?? 0,
       isSteering,
-      payload: null,
+      payload: inboundMsg,
     },
     at: Date.now(),
   })
@@ -18059,6 +17791,72 @@ async function handleInbound(
     effectiveText,
   })
 
+  // ── PR3c inbound cutover (#2794 / #2996 item 1) ────────────────────────
+  // The machine's effect list is now AUTHORITATIVE for the deliver-vs-buffer
+  // routing when the cutover is on: the effects captured at the emit above
+  // are executed through `dispatchEffects` (wired to real executors in
+  // #3006) instead of the imperative twin below. The twin stays fully
+  // intact as the kill-switch fallback (`SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0`
+  // restores the exact legacy path) and is deleted in PR4 after the 48h bake.
+  //
+  // Two carve-outs fall back to the imperative twin even with the cutover on
+  // (both documented in the RFC as un-modeled by the machine; the twin's
+  // behavior is the contract until the machine grows the events):
+  //   1. `!`-interrupt while the machine reads in_turn — the twin's
+  //      interrupt carve-out delivers (the SIGINT'd turn may never emit
+  //      turn_complete, so buffering would strand the body; see
+  //      decideInboundDelivery). The machine has no interrupt concept yet
+  //      and would buffer.
+  //   2. machine reads bridge_dead — the twin attempts the send and, on
+  //      miss, applies the shouldTrackDelivery carve-outs (steering /
+  //      interrupt / sourced bodies are dropped, not replayed orphaned
+  //      after restart) + posts the restart notice. The machine's
+  //      unconditional buffer+persist would replay a steer as a fresh turn.
+  const machineDelivers = machineInboundEffects.some((e) => e.kind === 'deliverToBridge')
+  const machineBuffers = machineInboundEffects.some((e) => e.kind === 'bufferInbound')
+  // ANCHORED STRING — must match the machine's bridge-dead inbound trace
+  // stage verbatim (see the anchor comment at its emit site in
+  // inbound-delivery-machine.ts + the pin test in
+  // inbound-delivery-cutover-flip.test.ts). Deleted in PR4 with the twin.
+  const machineBridgeDead = machineInboundEffects.some(
+    (e) => e.kind === 'logTrace' && e.stage === 'inbound_bridge_dead_buffer',
+  )
+  const machineAuthoritative =
+    isDeliveryCutoverEnabled() &&
+    isDispatchEnabled() &&
+    !machineBridgeDead &&
+    (machineDelivers || (machineBuffers && interrupt.isInterrupt !== true))
+  if (machineAuthoritative && machineBuffers) {
+    // Machine says: mid-turn non-steering inbound → buffer until idle (the
+    // #1556 contract). dispatchEffects executes bufferInbound (+ the
+    // idempotent persistInbound — push() already spools when a spool is
+    // attached) + the logTrace. The queued-status UX below is presentation,
+    // not routing — it stays imperative on both paths until PR4.
+    dispatchEffects(machineInboundEffects, {
+      selfAgent,
+      ipcServer,
+      pendingInboundBuffer,
+      inboundSpool: inboundSpool ?? null,
+      pendingPermissionBuffer,
+    })
+    process.stderr.write(
+      `telegram gateway: inbound held mid-turn (machine) agent=${selfAgent} ` +
+      `chat=${chat_id} msg=${msgId ?? '-'} — will flush on turn-complete\n`,
+    )
+    const inFlightThreadM = currentTurn?.sessionThreadId
+    const crossTopicQueuedCardM =
+      QUEUED_STATUS_UX_ENABLED &&
+      !isDmChatId(chat_id) &&
+      messageThreadId != null &&
+      messageThreadId !== inFlightThreadM
+    if (crossTopicQueuedCardM) {
+      postQueuedStatus(chat_id, messageThreadId, inFlightThreadM)
+    } else {
+      maybePostBusyAck('buffer-until-idle', chat_id, messageThreadId ?? undefined)
+    }
+    return
+  }
+
   // #2917: read the gate LIVE (not the receipt snapshot) on the default path
   // so a sibling same-chat inbound delivered during THIS handler's async
   // lead-in is observed here. Reading `claudeBusyKeys` live is self-block-safe:
@@ -18084,7 +17882,10 @@ async function handleInbound(
     // the freshly-killed bridge.
     isInterrupt: interrupt.isInterrupt,
   })
-  if (deliveryGate.decision === 'buffer-until-idle') {
+  // PR3c: the legacy buffer branch runs ONLY when the machine is not
+  // authoritative (kill switch / carve-out fallback) — the machine buffer
+  // path above already returned for machine-routed buffering.
+  if (!machineAuthoritative && deliveryGate.decision === 'buffer-until-idle') {
     pendingInboundBuffer.push(selfAgent, inboundMsg)
     process.stderr.write(
       `telegram gateway: inbound held mid-turn agent=${selfAgent} ` +
@@ -18125,8 +17926,12 @@ async function handleInbound(
   // other's async lead-in and race to the bridge, reordering the replies.
   // Only fresh-turn deliveries reserve (steering/interrupt amend a running
   // turn and must not). Released below if the send misses (bridge offline).
+  // PR3c: skipped when the machine is authoritative — the inbound event at
+  // DEFERRED_INBOUND_EMIT advanced the machine SYNCHRONOUSLY (idle→in_turn),
+  // so the machine itself is the pre-await reservation; the busy-key mirror
+  // is stamped by the setTurnStarted effect in the dispatch below.
   let reservedBusyKey: string | null = null
-  if (deliveryGate.reserve && SERIALIZE_INBOUND_DELIVERY_ENABLED && machineInTurnAtReceipt == null) {
+  if (!machineAuthoritative && deliveryGate.reserve && SERIALIZE_INBOUND_DELIVERY_ENABLED && machineInTurnAtReceipt == null) {
     reservedBusyKey = markClaudeBusyForInbound(inboundMsg)
   }
 
@@ -18157,6 +17962,104 @@ async function handleInbound(
     }
   }
 
+  // ── PR3c machine deliver path (#2794) ──────────────────────────────────
+  // The machine said deliver (fresh turn: setTurnStarted + deliverToBridge;
+  // steer: deliverToBridge only). dispatchEffects executes the send; the
+  // post-send branches below mirror the imperative twin bit-for-bit:
+  // delivered → steer ack + busy-mark (idempotent, same lifecycle the twin
+  // stamps) + delivery-confirm tracking; miss → release the busy mirror in
+  // lockstep, durable-buffer per the shouldTrackDelivery carve-outs, and
+  // post the restart notice. NOTE the machine already advanced to in_turn
+  // at the emit; a send-miss therefore leaves the machine in_turn until the
+  // TTL tick clears it — identical to today's cutover behavior (the emit
+  // has always preceded the send attempt), not a regression of this flip.
+  if (machineAuthoritative) {
+    let machineDelivered = false
+    // Key stamped by THIS dispatch's setTurnStarted effect (fresh turn only —
+    // a mid-turn steer emits deliverToBridge WITHOUT setTurnStarted). The
+    // miss branch below may only release a key THIS dispatch stamped: on a
+    // steer-miss the chat's busy key belongs to the ORIGINAL in-flight turn
+    // (mirroring the twin, which only ever releases reservedBusyKey and never
+    // reserves for steers). An unconditional delete would wipe the running
+    // turn's key → false machine_over_holds parity drift during the bake +
+    // the pending-restart gate (claudeBusyKeys.size) could green-light a
+    // mid-turn restart.
+    let machineStampedKey: string | null = null
+    dispatchEffects(machineInboundEffects, {
+      selfAgent,
+      ipcServer,
+      pendingInboundBuffer,
+      inboundSpool: inboundSpool ?? null,
+      pendingPermissionBuffer,
+      // Busy-key mirror: same lockstep add markClaudeBusyForInbound does —
+      // keeps the kill-switch fallback + gate-parity-probe + pending-restart
+      // gate (claudeBusyKeys.size) coherent while the twins remain live.
+      onSetTurnStarted: (k, at) => {
+        machineStampedKey = k
+        markBusyKeyLockstep(claudeBusyKeys, claudeBusyKeySince, k, at)
+      },
+      onDeliverResult: (_k, ok) => {
+        machineDelivered = ok
+      },
+    })
+    if (machineDelivered) {
+      if (isSteering) {
+        maybePostBusyAck('steer', chat_id, messageThreadId ?? undefined)
+      }
+      // Mirror the twin: EVERY delivered inbound stamps the busy key
+      // (steer/interrupt included — idempotent lockstep re-stamp), and the
+      // returned key is what the delivery-confirm tracker matches acks on.
+      const busyKey = markClaudeBusyForInbound(inboundMsg)
+      if (
+        DELIVERY_CONFIRM_ENABLED &&
+        shouldTrackDelivery({
+          isSteering,
+          isInterrupt: interrupt.isInterrupt,
+          hasSource: inboundMsg.meta?.source != null,
+          effectiveText,
+        })
+      ) {
+        trackDelivery(deliveryQueue, busyKey, inboundMsg, Date.now(), String(inboundMsg.messageId))
+      }
+    } else {
+      // Send missed while the machine read bridge-alive. Release ONLY a busy
+      // mirror THIS dispatch's setTurnStarted stamped (lockstep with the
+      // twin's reservedBusyKey release). A steer-miss stamped nothing — the
+      // chat key belongs to the original in-flight turn and must survive
+      // (see machineStampedKey above). Then buffer per the carve-outs, notify.
+      //
+      // Known behavior delta (documented, accepted for the bake): the
+      // machine already advanced to in_turn at the emit, so until the TTL
+      // tick / bridge-flap clears it, SUBSEQUENT inbounds are machine-
+      // buffered ("queued" busy-ack) instead of the legacy per-message send
+      // attempt + restart notice. See the RFC carve-out row + PR body.
+      if (machineStampedKey != null) {
+        claudeBusyKeys.delete(machineStampedKey)
+        claudeBusyKeySince.delete(machineStampedKey)
+      }
+      if (
+        shouldTrackDelivery({
+          isSteering,
+          isInterrupt: interrupt.isInterrupt,
+          hasSource: inboundMsg.meta?.source != null,
+          effectiveText,
+        })
+      ) {
+        pendingInboundBuffer.push(selfAgent, inboundMsg)
+      }
+      const threadOptsM = messageThreadId != null ? { message_thread_id: messageThreadId } : {}
+      void swallowingApiCall(
+        () => bot.api.sendMessage(chat_id, '⏳ Agent is restarting — your message is queued and will be processed when it reconnects.', { ...threadOptsM }),
+        {
+          chat_id,
+          verb: 'agent-restarting-notice',
+          ...(messageThreadId != null ? { threadId: messageThreadId } : {}),
+        },
+      )
+    }
+    return
+  }
+
   const delivered = ipcServer.sendToAgent(selfAgent, inboundMsg)
   if (delivered) {
     // #2995 — a steer delivered mid-turn while the turn is stuck inside one
@@ -22123,2233 +22026,100 @@ function resolveAgentDirForName(agent: string): string | null {
   return null
 }
 
-/**
- * Handle a callback_query from an auth dashboard button. Parses the
- * callback_data, runs the matching action, acknowledges the tap with a
- * toast, and refreshes the dashboard in-place via editMessageText.
- */
-/**
- * Handle op:<action>:<encoded-agent> callbacks from operator-events.ts
- * renderOperatorEvent(). Phase 4b — closes the "buttons do nothing" gap.
- *
- * Actions:
- *   dismiss   — clear keyboard + toast
- *   restart   — systemctl --user restart switchroom-<agent>
- *   reauth    — delegate to runSwitchroomAuthCommand (same flow as /auth reauth)
- *   logs      — post last 30 lines of journalctl for the agent
- *   slot management buttons — removed (E5); use /auth use or /auth add instead.
- */
-/**
- * Issue #44: handle taps on the deferred-secret card's inline buttons.
- *
- *   `vd:unlock:<deferKey>` — register a `passphrase-for-deferred` pending
- *      vault op and edit the card to ask the user for their passphrase.
- *      The text-handler picks the passphrase up via the existing
- *      pendingVaultOps intercept and calls `executeDeferredSecretSave`
- *      to write the held secret directly. No re-paste required.
- *
- *   `vd:cancel:<deferKey>` — drop the deferred secret and clear the card.
- *      The held bytes are evicted from the in-memory `deferredSecrets`
- *      map (they were never written to disk) so the secret vanishes.
- *
- * Authorization mirrors the operator-event callback: only senders on the
- * configured allowlist get to act on the buttons.
- */
-/**
- * Issue #969 P1a — handle the agent-initiated vault-save approval card
- * (`vault_request_save` MCP tool).
- *
- * Callbacks:
- *   vrs:save:<stageId>     — confirm save; write to vault using broker put
- *                            with operator-passphrase attestation (#969 P1a)
- *                            so even new keys go through in one tap.
- *   vrs:discard:<stageId>  — drop the staged secret; never touches disk.
- *   vrs:rename:<stageId>   — set up a pending-op intercept so the user's
- *                            next message is taken as a new key name.
- */
-/**
- * Issue #969 P2b — handle a tap on the "🔓 Allow <key>" button posted by
- * `/vault audit <agent>`'s Recent denials section. Mints a 30-day
- * read-grant for the agent + key via the broker.
- *
- * The grant also unioning into the agent's existing token if one is
- * already present is out of scope for this PR — the operator can
- * re-mint with a wider key list if they want consolidation.
- */
-async function handleVaultRecentDenialCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-  // vrd:<agent>:<key>  — parse, validate both halves against the strict
-  // slug regex before doing anything else.
-  const parts = data.split(':')
-  if (parts.length !== 3) {
-    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
-    return
-  }
-  const [, agentName, keyName] = parts
-  if (!/^[a-z][a-z0-9-]{0,62}$/i.test(agentName)) {
-    await ctx.answerCallbackQuery({ text: 'Invalid agent name' }).catch(() => {})
-    return
-  }
-  // #1047: same canonical key shape as vault_request_save /
-  // vault_request_access — namespaced keys like `fatsecret/client_id`
-  // must round-trip through the /vault audit one-tap Allow flow too,
-  // not just the agent-initiated approval cards.
-  if (!VAULT_KEY_REGEX.test(keyName)) {
-    await ctx.answerCallbackQuery({ text: 'Invalid key name' }).catch(() => {})
-    return
-  }
-  await ctx.answerCallbackQuery({ text: '⏳ Minting 30-day read grant…' }).catch(() => {})
+// ─── Callback-query handler families (#2996 Phase 5, remaining item 2) ─────
+// Extracted verbatim to callback-query-handlers.ts behind an injected deps
+// object (see that module's header for what moved and what deliberately
+// stayed). Destructuring keeps every call site below byte-identical.
+const callbackQueryHandlers = createCallbackQueryHandlers({
+  bot,
+  lockedBot,
+  loadAccess,
+  escapeHtmlForTg,
+  switchroomReply,
+  resolveThreadId,
+  deliverResumeSyntheticOrBuffer,
+  expireMentalModelProposeCard,
+  readLiveSwitchroomConfigText,
+  mentalModelCorrelationKey,
+  getMyAgentName,
+  triggerSelfRestart,
+  runSwitchroomAuthCommand,
+  switchroomExecJson,
+  assertSafeAgentName,
+  buildDeferredSecretKeyboard,
+  recordDeferredSecretKernelDecision,
+  mintGrantWizardKernelRequest,
+  recordGrantWizardKernelDecision,
+  robustApiCall,
+  swallowingApiCall,
+  pendingVaultRequestAccesses,
+  pendingVaultRequestSaves,
+  pendingMentalModelProposes,
+  pendingCardStore,
+  pendingMentalModelCorrelations,
+  pendingVaultOps,
+  vaultPassphraseCache,
+  deferredSecrets,
+  pendingReauthFlows,
+  secretStaging,
+  lastAuthRefreshAtMs,
+  // Mutable module `let`s — injected as getters so the startup config
+  // assignment (and any later reload) stays observable from the module.
+  getVaultApprovalAuthMode: () => VAULT_APPROVAL_AUTH_MODE,
+  getAdminOnlyKeys: () => ADMIN_ONLY_KEYS,
+  vaultKeyRegex: VAULT_KEY_REGEX,
+  mentalModelProposeTtlMs: MENTAL_MODEL_PROPOSE_TTL_MS,
+})
+const {
+  handleVaultRecentDenialCallback,
+  performVaultAccessApproval,
+  handleSkillProposalCallback,
+  handleMentalModelProposeCallback,
+  handleVaultRequestAccessCallback,
+  handleVaultRequestSaveCallback,
+  handleVaultDeferCallback,
+  parseGrantDuration,
+  startGrantWizardStep1,
+  grantWizardConfirm,
+  handleVaultGrantCallback,
+  executeDeferredSecretSave,
+  handleOperatorEventCallback,
+  handleAuthDashboardCallback,
+} = callbackQueryHandlers
 
-  const result = await mintGrantViaBroker({
-    agent: agentName,
-    keys: [keyName],
-    ttl_seconds: 30 * 24 * 60 * 60,
-    description: `auto-mint via /vault audit one-tap (#969 P2b)`,
-  })
+// /reauth was removed in v0.6.13 — the `/auth` dashboard's
+// `🔄 Reauth default` button fires the same flow (the `case 'reauth':`
+// callback dispatch calls `runSwitchroomAuthCommand` and seeds
+// `pendingReauthFlows`). The OAuth code paste-back is caught by the
+// generic message intercept that watches `pendingReauthFlows` —
+// pasting the code into chat now Just Works without a typed entry
+// point. Removed surfaces in this PR:
+//   - bot.command('reauth', ...)              → use /auth → 🔄 Reauth
+//   - /reauth <code|url>  paste-back          → paste into chat
+//   - /reauth <other-agent> targeting         → use that agent's /auth
 
-  if (result.kind === 'unreachable') {
-    await switchroomReply(ctx, `🔴 Broker unreachable: ${escapeHtmlForTg(result.msg)}`, { html: true })
-    return
-  }
-  if (result.kind === 'error') {
-    await switchroomReply(ctx, `**mint_grant failed:** ${escapeHtmlForTg(result.msg)}`, { html: true })
-    return
-  }
-  // Write the token to the agent's .vault-token file — same flow as the
-  // vault grant wizard. The agent restarts in the background pick up
-  // the new token via SWITCHROOM_AGENT_NAME on next CLI invocation.
-  const { token, id } = result
-  const tokenPath = join(homedir(), '.switchroom', 'agents', agentName, '.vault-token')
-  try {
-    mkdirSync(join(homedir(), '.switchroom', 'agents', agentName), { recursive: true })
-    writeFileSync(tokenPath, token, { mode: 0o600 })
-  } catch (err) {
-    await switchroomReply(
-      ctx,
-      `**Grant created (${escapeHtmlForTg(id)}) but token write failed:** ` +
-      `${escapeHtmlForTg(String(err))}\n` +
-      `_Recover with: \`switchroom vault grant ${escapeHtmlForTg(agentName)} ` +
-      `--keys ${escapeHtmlForTg(keyName)} --duration 30d\` on the host._`,
-      { html: true },
-    )
-    return
-  }
-  // #1150 audit: P0 fix — pre-fix the audit-listing message kept its
-  // tappable [Always allow ...] buttons after a successful mint, so
-  // the operator could re-tap the same denial and re-mint the grant
-  // (broker idempotency saves us from a duplicate write but the
-  // operator experience was "did anything happen? let me tap again").
-  // Strip the entire audit-listing keyboard on first tap + append a
-  // status line so the action is visible. Operator re-runs `/vault
-  // audit` to act on remaining denials — that's the documented flow.
-  // HTML-escape the source text before concatenation. `ctx.callbackQuery.
-  // message.text` returns the body with entities STRIPPED (Telegram
-  // decodes the original HTML), so any raw `<`, `>`, `&` in agent/key
-  // names that survived the original audit-listing's escape pass would
-  // now break the HTML re-parse — and finalizeCallback's catch swallows
-  // the failure, leaving the keyboard tappable. Caught in PR #1158 review
-  // for the operator-event card; the same fix applies here.
-  const sourceMsg = ctx.callbackQuery?.message
-  const baseText = sourceMsg && 'text' in sourceMsg && sourceMsg.text
-    ? escapeHtmlForTg(sourceMsg.text)
-    : ''
-  const statusLine =
-    `\n\n✅ **${escapeHtmlForTg(agentName)}** granted read access to ` +
-    `\`${keyName}\` for 30 days ` +
-    `(grant \`${id}\`). ` +
-    `Re-run /vault audit to act on remaining denials.`
-  await finalizeCallback(ctx, {
-    ackText: '✅ Grant minted',
-    newText: baseText ? `${baseText}${statusLine}` : statusLine,
-    // No synthInbound — operator-only flow. The granted agent picks
-    // up the token via .vault-token file on next CLI invocation; no
-    // turn-wake needed.
-  })
-}
-
-/**
- * Issue #1012 — handle a tap on the vault_request_access approval card.
- *   vra:approve:<stageId> — mint a scoped grant token via the broker,
- *                           write the token to the agent's
- *                           `.vault-token` file, edit card to success.
- *   vra:deny:<stageId>    — drop the staged request, edit card to denied.
- *
- * Same authorization gate as the recent-denials one-tap handler:
- * sender must be on the gateway's allowFrom list.
- */
-/**
- * Mint the scoped grant + write the token file for an approved
- * `vault_request_access` request. Factored out so both the direct
- * approve-tap (passphrase already cached) and the
- * `passphrase-for-access-approve` resume flow (passphrase captured
- * via text-message intercept after tap-on-locked) drive identical
- * minting behaviour. #1012 Phase 2 + follow-up.
- */
-/**
- * #1115 follow-up: caller-supplied attestation. Either a real operator
- * passphrase (when the operator typed it in chat) or a posture flag
- * that tells the broker to use its own retained passphrase under
- * `vault.broker.approvalAuth: telegram-id`. The passphrase variant
- * never crosses into telegram-id callsites; the posture variant
- * never crosses into passphrase-mode callsites.
- */
-type AccessApprovalAttestation =
-  | { kind: 'passphrase'; passphrase: string }
-  | { kind: 'posture' }
-
-async function performVaultAccessApproval(
-  ctx: Context,
-  pending: PendingVaultRequestAccess,
-  stageId: string,
-  senderId: string,
-  attestation: AccessApprovalAttestation,
-): Promise<void> {
-  const brokerAuthOpts =
-    attestation.kind === 'passphrase'
-      ? { passphrase: attestation.passphrase }
-      : { attest_via_posture: true as const }
-
-  // Fix B (#1487 follow-up), operator-tap guard. Defense-in-depth for a
-  // card staged before the key became standing-ACL-covered (config edit
-  // / #1487 deploy / drift): if the agent's standing ACL ALREADY covers
-  // this read key, do NOT mint — minting writes a `.vault-token` that
-  // shadows the standing ACL and is redundant. Authoritative broker
-  // probe AS THIS AGENT (no-token list over the per-agent socket — same
-  // rationale as executeVaultRequestAccess; never a gateway-side config
-  // read). Read scope only. Fail-open on probe error (mint as before).
-  if (pending.scope === 'read') {
-    try {
-      const visible = await listViaBroker()
-      if (visible !== null && visible.includes(pending.key)) {
-        pendingVaultRequestAccesses.delete(stageId)
-        pendingCardStore.remove(stageId)
-        if (pending.card_message_id != null) {
-          await ctx.api
-            .editMessageText(
-              pending.chat_id,
-              pending.card_message_id,
-              `ℹ️ **${escapeHtmlForTg(pending.agent)}** already has standing-ACL access to ` +
-              `\`${pending.key}\` (schedule.secrets[]). ` +
-              `**No grant minted** — a token would shadow the standing ACL. ` +
-              richMessage(`The agent can read it directly.`),
-              { reply_markup: { inline_keyboard: [] } },
-            )
-            .catch(() => {})
-        }
-        return
-      }
-    } catch {
-      // Probe failed: fall through and mint as before (fail-open).
-    }
-  }
-
-  // #1051: union the new key with the agent's existing active grant
-  // before minting. Without this, each fresh Approve OVERWRITES the
-  // agent's `.vault-token` file with a single-key grant — the
-  // previous approval's grant is still in the broker DB but the
-  // agent can no longer authenticate against it (the CLI reads the
-  // file's current token, the broker validates it, sees the new key
-  // isn't in the OLD grant's key_allow, and denies).
-  //
-  // Solution: list the agent's existing non-expired grants
-  // (passphrase-attested per #1051's broker-side gate widening),
-  // find the active read-grant (most recent non-revoked,
-  // non-expired), and pass its keys ∪ new_key as `keys` to the
-  // mint call. Old grant ages out via TTL — no explicit revoke
-  // needed.
-  let existingReadKeys: string[] = [];
-  let existingWriteKeys: string[] = [];
-  if (pending.scope === 'read' || pending.scope === 'write') {
-    const list = await listGrantsViaBroker(pending.agent, brokerAuthOpts);
-    if (list.kind === 'ok') {
-      const now = Math.floor(Date.now() / 1000);
-      // Prefer the MOST RECENT non-revoked, non-expired grant. The
-      // broker's listGrants returns ALL non-revoked, but we still
-      // filter expires_at locally as defence-in-depth + sort by
-      // created_at desc for stability.
-      const active = list.grants
-        .filter((g) => g.expires_at === null || g.expires_at > now)
-        // Reviewer-flagged on #1058 (Q4): `created_at` is
-        // seconds-granularity, so two grants minted in the same
-        // wall-clock second tie. Secondary sort by `id` (vg_<6hex>)
-        // makes the ordering stable so item 2's drain reliably picks
-        // up item 1's just-minted grant rather than an unrelated
-        // same-second grant.
-        .sort((a, b) => {
-          const dt = (b.created_at ?? 0) - (a.created_at ?? 0);
-          if (dt !== 0) return dt;
-          return b.id.localeCompare(a.id);
-        });
-      if (active.length > 0) {
-        existingReadKeys = active[0]!.key_allow ?? [];
-        existingWriteKeys = active[0]!.write_allow ?? [];
-      }
-    }
-    // If list fails (broker unreachable / error), proceed without
-    // union — better to mint a single-key grant than fail closed
-    // entirely. The agent loses the prior coverage in that edge
-    // case, same as today, but the new key is granted.
-  }
-
-  // Compute the unioned key sets. Use Set to dedupe.
-  const readKeys = new Set<string>(existingReadKeys);
-  const writeKeys = new Set<string>(existingWriteKeys);
-  if (pending.scope === 'read') readKeys.add(pending.key);
-  if (pending.scope === 'write') writeKeys.add(pending.key);
-
-  const mintArgs: Parameters<typeof mintGrantViaBroker>[0] = {
-    agent: pending.agent,
-    keys: Array.from(readKeys),
-    ttl_seconds: pending.ttl_seconds,
-    description:
-      `auto-mint via vault_request_access (#1012, scope=${pending.scope}, by op ${senderId}` +
-      (existingReadKeys.length + existingWriteKeys.length > 0
-        ? `, unioned with prior grant`
-        : ``) +
-      `)`,
-    ...(writeKeys.size > 0 ? { write_keys: Array.from(writeKeys) } : {}),
-    ...brokerAuthOpts,
-  }
-  const result = await mintGrantViaBroker(mintArgs)
-  if (result.kind === 'unreachable') {
-    await switchroomReply(ctx, `🔴 Broker unreachable: ${escapeHtmlForTg(result.msg)}`, { html: true })
-    return
-  }
-  if (result.kind === 'error') {
-    // Mint refused (most likely wrong passphrase). Drop the staged
-    // request so a re-attempt starts cleanly. The operator can ask
-    // the agent to re-issue, or the broker error message will tell
-    // them the next step.
-    pendingVaultRequestAccesses.delete(stageId)
-    pendingCardStore.remove(stageId)
-    if (pending.card_message_id != null) {
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage(`**mint_grant failed:** ${escapeHtmlForTg(result.msg)}`),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  const { token, id } = result
-  const tokenPath = join(homedir(), '.switchroom', 'agents', pending.agent, '.vault-token')
-  try {
-    mkdirSync(join(homedir(), '.switchroom', 'agents', pending.agent), { recursive: true })
-    writeFileSync(tokenPath, token, { mode: 0o600 })
-  } catch (err) {
-    await switchroomReply(
-      ctx,
-      `**Grant created (${escapeHtmlForTg(id)}) but token write failed:** ` +
-      `${escapeHtmlForTg(String(err))}\n` +
-      `_Recover with: \`switchroom vault grant ${escapeHtmlForTg(pending.agent)} ` +
-      `--keys ${escapeHtmlForTg(pending.key)} --duration ${Math.round(pending.ttl_seconds / 86400)}d\` on the host._`,
-      { html: true },
-    )
-    return
-  }
-
-  pendingVaultRequestAccesses.delete(stageId)
-  pendingCardStore.remove(stageId)
-  if (pending.card_message_id != null) {
-    const days = Math.round(pending.ttl_seconds / 86400)
-    const footer =
-      VAULT_APPROVAL_AUTH_MODE === 'telegram-id'
-        ? `\n_Approver verified by Telegram identity — broker auto-unlocked at startup._`
-        : ''
-    await ctx.api
-      .editMessageText(
-        pending.chat_id,
-        pending.card_message_id,
-        richMessage(
-          buildVaultGrantApprovedCardText({
-            agentEscaped: escapeHtmlForTg(pending.agent),
-            scope: pending.scope,
-            key: pending.key,
-            days,
-            grantId: id,
-            footer,
-          }),
-        ),
-        { reply_markup: { inline_keyboard: [] } },
-      )
-      .catch(() => {})
-  }
-
-  // #1052: deliver a synthetic inbound message back to the agent so
-  // the task that fired vault_request_access auto-resumes — without
-  // this, the agent's turn ended after the tool call ("waiting for
-  // approval") and the operator has to send a fresh message to kick
-  // it back into action.
-  //
-  // Uses the existing inject_inbound primitive (cron's pattern from
-  // dispatch.ts:180-206). The bridge sees a normal channel event,
-  // renders it as `<channel source="vault_grant_approved">`, and the
-  // agent starts a new turn with the context that the operator just
-  // approved.
-  //
-  // The synthetic message text is concise + actionable so the agent
-  // knows (a) which key was approved, (b) at what scope, (c) what to
-  // do next. Meta carries the structured fields for forensics + for
-  // future filters that want to suppress these in the chat tail.
-  const synthetic = buildVaultGrantApprovedInbound({
-    ctx: {
-      agent: pending.agent,
-      key: pending.key,
-      scope: pending.scope,
-      chat_id: pending.chat_id,
-      ttl_seconds: pending.ttl_seconds,
-      ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-    },
-    grantId: id,
-    stageId,
-    operatorId: senderId,
-  })
-  // Turn-gated via deliverResumeSyntheticOrBuffer: mid-turn → buffer
-  // (flushed at turn-end) so the resume never strands in claude's
-  // composer (#1556); idle → deliver; bridge-down → buffer (#1150).
-  const delivered = deliverResumeSyntheticOrBuffer(pending.agent, synthetic)
-  process.stderr.write(
-    `telegram gateway: vault_grant_approved injection agent=${pending.agent} ` +
-    `key=${pending.key} stage=${stageId} delivered=${delivered}\n`,
-  )
-}
-
-/**
- * #2670 — handle an Approve / Dismiss tap on a one-tap skill-improvement
- * proposal card.
- *
- *   Approve → mark the proposal approved + inject a synthetic
- *             `skill_proposal_apply` turn instructing the live agent to
- *             write the stored draft through `skill_*_personal` (so the
- *             secret-scan pipeline runs; agent never self-applies).
- *   Dismiss → mark rejected + write a rejection fingerprint so the weekly
- *             synthesis cron doesn't re-propose it.
- */
-async function handleSkillProposalCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-  const parsed = parseSkillProposalCallback(data)
-  if (parsed == null) {
-    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
-    return
-  }
-  const stateDir = process.env.TELEGRAM_STATE_DIR
-  const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
-  if (stateDir == null || stateDir.length === 0) {
-    await ctx.answerCallbackQuery({ text: 'State dir unset — cannot apply.' }).catch(() => {})
-    return
-  }
-  const proposal = getSkillProposal(stateDir, parsed.id)
-  if (proposal == null) {
-    await ctx.answerCallbackQuery({ text: 'Proposal expired or already actioned.' }).catch(() => {})
-    if (ctx.callbackQuery?.message) {
-      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {})
-    }
-    return
-  }
-  if (proposal.status !== 'pending') {
-    await ctx.answerCallbackQuery({ text: `Already ${proposal.status}.` }).catch(() => {})
-    if (ctx.callbackQuery?.message) {
-      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {})
-    }
-    return
-  }
-
-  const cbChatId = String(ctx.chat?.id ?? ctx.from?.id ?? '')
-  const cbThreadId = resolveThreadId(cbChatId, ctx.callbackQuery?.message?.message_thread_id)
-
-  if (parsed.action === 'deny') {
-    setSkillProposalStatus(stateDir, parsed.id, 'rejected')
-    await ctx.answerCallbackQuery({ text: '🚫 Dismissed — won’t be proposed again.' }).catch(() => {})
-    if (ctx.callbackQuery?.message && 'text' in ctx.callbackQuery.message) {
-      await ctx
-        .editMessageText(
-          `${escapeHtmlForTg(ctx.callbackQuery.message.text ?? '')}\n\n🚫 <i>Dismissed.</i>`,
-          { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  // Approve.
-  setSkillProposalStatus(stateDir, parsed.id, 'approved')
-  const synthetic = buildSkillProposalApplyInbound({
-    ctx: {
-      agent,
-      chat_id: cbChatId,
-      ...(cbThreadId != null ? { threadId: cbThreadId } : {}),
-    },
-    proposalId: proposal.id,
-    skillSlug: proposal.skill_slug,
-    isNew: proposal.is_new,
-    operatorId: senderId,
-  })
-  const delivered = deliverResumeSyntheticOrBuffer(agent, synthetic)
-  await ctx.answerCallbackQuery({ text: '✅ Applying the skill…' }).catch(() => {})
-  if (ctx.callbackQuery?.message && 'text' in ctx.callbackQuery.message) {
-    await ctx
-      .editMessageText(
-        `${escapeHtmlForTg(ctx.callbackQuery.message.text ?? '')}\n\n✅ <i>Approved — applying.</i>`,
-        { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
-      )
-      .catch(() => {})
-  }
-  process.stderr.write(
-    `telegram gateway: skill_proposal_apply injection agent=${agent} ` +
-    `proposal=${proposal.id} slug=${proposal.skill_slug} delivered=${delivered}\n`,
-  )
-}
-
-/**
- * hindsight Phase 5 — handle a tap on the mental-model PROPOSAL card.
- *   mmp:approve:<stageId> — declare the model: append it to the agent's
- *                           memory.mental_models[] via the operator-approved
- *                           config-edit path (reused config_propose_edit
- *                           apply+reconcile; reconcile ensures it), then wake
- *                           the agent with an "applied" inbound.
- *   mmp:deny:<stageId>    — drop the proposal; NOTHING is written; wake the
- *                           agent with a "denied" inbound.
- *
- * Authorization: the tapper MUST be on the gateway's allowFrom list — an agent
- * can PROPOSE but can never self-approve (identical gate to the vault flow).
- */
-async function handleMentalModelProposeCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    // Self-approve is impossible: only an allow-listed operator can resolve
-    // the card. A tap from anyone else (incl. a compromised agent identity) is
-    // refused here.
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-  const parts = data.split(':')
-  if (parts.length < 3) {
-    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
-    return
-  }
-  const action = parts[1]
-  const stageId = parts.slice(2).join(':')
-  const pending = pendingMentalModelProposes.get(stageId)
-  if (!pending) {
-    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-propose.' }).catch(() => {})
-    if (ctx.callbackQuery?.message) {
-      await ctx.api
-        .editMessageText(
-          ctx.callbackQuery.message.chat.id,
-          ctx.callbackQuery.message.message_id,
-          richMessage('⌛ _This mental-model proposal card expired before you tapped. Ask the agent to re-propose if it still stands._'),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-  if (action !== 'approve' && action !== 'deny') {
-    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
-    return
-  }
-  // Enforce the TTL at TAP time, not just on the next propose's sweep. Without
-  // this, a card left untapped past its TTL is still resolvable if no fresh
-  // proposal has run the sweep — an operator could approve a stale proposal.
-  if (Date.now() - pending.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS) {
-    // Expired between post and tap: route through the shared expiry path so the
-    // parked agent is WOKEN (timeout synthetic + missed-approvals re-offer) and
-    // the durable store entry is cleared — not just a silent map delete.
-    expireMentalModelProposeCard(stageId, pending, Date.now())
-    await ctx.answerCallbackQuery({ text: 'Card expired — the agent was notified.' }).catch(() => {})
-    return
-  }
-  // Single-shot: remove the pending entry immediately so a double-tap can't
-  // resolve twice.
-  pendingMentalModelProposes.delete(stageId)
-  pendingCardStore.remove(stageId)
-
-  const proposal: MentalModelPendingProposal = {
-    agent: pending.agent,
-    chat_id: pending.chat_id,
-    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-    spec: pending.spec,
-    ...(pending.reason ? { reason: pending.reason } : {}),
-  }
-
-  const resolveDeps = {
-    readConfigText: () => readLiveSwitchroomConfigText(),
-    registerPreApproval: (agent: string, diff: string) => {
-      pendingMentalModelCorrelations.set(mentalModelCorrelationKey(agent, diff), {
-        agentName: agent,
-        unifiedDiff: diff,
-        createdAt: Date.now(),
-      })
-    },
-    clearPreApproval: (agent: string, diff: string) => {
-      pendingMentalModelCorrelations.delete(mentalModelCorrelationKey(agent, diff))
-    },
-    dispatchConfigEdit: async (a: { agent: string; diff: string; reason: string }) => {
-      const req: HostdRequest = {
-        v: 1,
-        op: 'config_propose_edit',
-        request_id: hostdRequestId('gw-mental-model'),
-        args: {
-          unified_diff: a.diff,
-          reason: a.reason,
-          target_path: '/state/config/switchroom.yaml',
-        },
-      }
-      // config_propose_edit blocks on validate→approve→apply→reconcile
-      // (5-10 min on a busy host) — allow 12 min. The operator already
-      // approved on the proposal card, so hostd's config-approval callback
-      // auto-resolves via the pre-registered correlation (no second card).
-      const resp = await tryHostdDispatch(a.agent, req, 720_000)
-      if (resp === 'not-configured') {
-        return { state: 'error' as const, reason: 'hostd config-edit is not configured (host_control disabled or socket absent)' }
-      }
-      if (resp.result === 'completed') return { state: 'applied' as const }
-      if (resp.result === 'denied') return { state: 'denied' as const, reason: resp.error ?? 'operator/host denied the edit' }
-      return { state: 'error' as const, reason: resp.error ?? `hostd returned '${resp.result}'` }
-    },
-    // Ensure is delegated to reconcile: config_propose_edit's apply triggers a
-    // reconcile which runs ensureDeclaredMentalModels (#2874) for the newly
-    // declared model — the authoritative, correctly-scoped ensure. We
-    // deliberately do NOT add a redundant gateway-side ensure (it would need
-    // the agent's bank id + a reachable Hindsight endpoint from the gateway).
-    injectInbound: (inbound: InboundMessage) => {
-      deliverResumeSyntheticOrBuffer(pending.agent, inbound)
-    },
-    log: (m: string) => process.stderr.write(`telegram gateway: ${m}\n`),
-  }
-
-  if (action === 'deny') {
-    await ctx.answerCallbackQuery({ text: '🚫 Denied' }).catch(() => {})
-    await resolveMentalModelProposal('deny', proposal, stageId, senderId, resolveDeps)
-    if (pending.card_message_id != null) {
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage(`🚫 _Denied. **${escapeHtmlForTg(pending.agent)}**'s mental model \`${pending.spec.name}\` was not declared._`),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  // Approve. Ack immediately + show an interim state, then persist in the
-  // background (config_propose_edit can take minutes), then edit the card with
-  // the real outcome. The turn resumes via the synthetic inbound injected by
-  // resolveMentalModelProposal — not by this card edit.
-  await ctx.answerCallbackQuery({ text: '✅ Declaring the model…' }).catch(() => {})
-  if (pending.card_message_id != null) {
-    await ctx.api
-      .editMessageText(
-        pending.chat_id,
-        pending.card_message_id,
-        richMessage(`⏳ _Declaring **${escapeHtmlForTg(pending.agent)}**'s mental model \`${pending.spec.name}\` — appending to config + ensuring…_`),
-        { reply_markup: { inline_keyboard: [] } },
-      )
-      .catch(() => {})
-  }
-  void (async () => {
-    let result
-    try {
-      result = await resolveMentalModelProposal('approve', proposal, stageId, senderId, resolveDeps)
-    } catch (err) {
-      process.stderr.write(`telegram gateway: mental_model_propose approve threw: ${(err as Error).message}\n`)
-      result = { outcome: 'failed' as const, reason: (err as Error).message }
-    }
-    if (pending.card_message_id != null) {
-      const label =
-        result.outcome === 'applied'
-          ? `✅ **Declared** ${escapeHtmlForTg(pending.agent)}'s mental model \`${pending.spec.name}\` — appended to \`memory.mental_models[]\` and ensured. Restart the agent to load it if it isn't picked up automatically.`
-          : `⚠️ **Did NOT declare** \`${pending.spec.name}\`${'reason' in result && result.reason ? ` — ${escapeHtmlForTg(result.reason)}` : ''}. Nothing was written.`
-      await ctx.api
-        .editMessageText(pending.chat_id, pending.card_message_id, richMessage(label), {
-          reply_markup: { inline_keyboard: [] },
-          link_preview_options: { is_disabled: true },
-        })
-        .catch(() => {})
-    }
-  })()
-}
-
-async function handleVaultRequestAccessCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-  const parts = data.split(':')
-  if (parts.length < 3) {
-    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
-    return
-  }
-  const action = parts[1]
-  const stageId = parts.slice(2).join(':')
-  const pending = pendingVaultRequestAccesses.get(stageId)
-  if (!pending) {
-    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-request.' }).catch(() => {})
-    if (ctx.callbackQuery?.message) {
-      await ctx.api
-        .editMessageText(
-          ctx.callbackQuery.message.chat.id,
-          ctx.callbackQuery.message.message_id,
-          richMessage('⌛ _This access-request card expired before you tapped. Ask the agent to re-issue if the need still stands._'),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  if (action === 'deny') {
-    pendingVaultRequestAccesses.delete(stageId)
-    pendingCardStore.remove(stageId)
-    await ctx.answerCallbackQuery({ text: '🚫 Denied' }).catch(() => {})
-    if (pending.card_message_id != null) {
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage(`🚫 _Denied. **${escapeHtmlForTg(pending.agent)}** will not get access to \`${pending.key}\`._`),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    // #1150 sibling: invariant-3 was missing on the deny path too. The
-    // agent originally ended its turn after `vault_request_access` and
-    // waits for the gateway to wake it. On approve we already inject
-    // `vault_grant_approved` (#1052); now we mirror that for deny so
-    // the agent can pick the fallback path (apologise to the user,
-    // try a different approach, skip the feature) instead of staying
-    // wedged forever. Buffer-on-failure so a mid-reconnect bridge
-    // still receives this on its next register.
-    const denyInbound = buildVaultGrantDeniedInbound({
-      ctx: {
-        agent: pending.agent,
-        key: pending.key,
-        scope: pending.scope,
-        chat_id: pending.chat_id,
-        ttl_seconds: pending.ttl_seconds,
-        ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-      },
-      stageId,
-      operatorId: senderId,
-    })
-    const denyDelivered = deliverResumeSyntheticOrBuffer(pending.agent, denyInbound)
-    process.stderr.write(
-      `telegram gateway: vault_grant_denied injection agent=${pending.agent} ` +
-      `key=${pending.key} stage=${stageId} delivered=${denyDelivered}\n`,
-    )
-    return
-  }
-
-  if (action === 'approve') {
-    // Admin-only credentials (`vault.broker.adminOnlyKeys`) are held to a
-    // higher bar: ONLY the admin operator (allowFrom[0]) may approve, and
-    // the grant must be minted with the operator passphrase — never
-    // posture, even under telegram-id mode (the broker enforces the same
-    // rule, so a posture mint would just be rejected). So for an
-    // admin-only key we (a) reject taps from any non-admin allowFrom
-    // member, and (b) skip the telegram-id posture branch below, falling
-    // through to the passphrase-prompt path. The card + buttons stay
-    // intact on a non-admin tap so the admin can still approve.
-    const isAdminOnly = matchesAdminOnlyKey(pending.key, ADMIN_ONLY_KEYS)
-    if (isAdminOnly && senderId !== access.allowFrom[0]) {
-      await ctx
-        .answerCallbackQuery({
-          text: '🔒 Admin-only credential — only the owner can approve this.',
-        })
-        .catch(() => {})
-      return
-    }
-
-    // Posture: telegram-id (opt-in single-factor). The broker is
-    // auto-unlocked and we silently hold the passphrase in memory; skip
-    // the passphrase-cache lookup + prompt entirely and mint directly.
-    // Allowlist check above already attested the operator's Telegram ID.
-    // Admin-only keys are excluded — they take the passphrase path below.
-    if (!isAdminOnly && VAULT_APPROVAL_AUTH_MODE === 'telegram-id') {
-      const username = ctx.from?.username ?? ctx.from?.first_name ?? `id=${senderId}`
-      if (pending.card_message_id != null) {
-        await ctx.api
-          .editMessageText(
-            pending.chat_id,
-            pending.card_message_id,
-            richMessage(`✅ Approved by @${escapeHtmlForTg(username)} — minting…`),
-            { reply_markup: { inline_keyboard: [] } },
-          )
-          .catch(() => {})
-      }
-      await ctx.answerCallbackQuery({ text: '⏳ Minting grant…' }).catch(() => {})
-      await performVaultAccessApproval(ctx, pending, stageId, senderId, { kind: 'posture' })
-      return
-    }
-
-    // Tap-to-unlock-and-approve: if the operator hasn't unlocked the
-    // vault in this chat yet, capture the passphrase via a pending op
-    // intercept and resume the approve flow automatically once it
-    // arrives — no second tap, no separate /vault unlock detour.
-    // Mirrors the `passphrase-for-deferred` flow from #44.
-    const cached = vaultPassphraseCache.get(pending.chat_id)
-    if (!cached || cached.expiresAt <= Date.now()) {
-      if (pending.card_message_id == null) {
-        await ctx
-          .answerCallbackQuery({ text: 'Card missing — ask the agent to re-issue.' })
-          .catch(() => {})
-        return
-      }
-      // #1051: if there's ALREADY a passphrase-for-access-approve
-      // pending op for this chat (operator tapped Approve on a
-      // sibling card before typing the passphrase), APPEND this
-      // stage to the existing queue instead of overwriting. When
-      // the passphrase reply lands the text-handler drains every
-      // queued stage — both cards get their grant minted off one
-      // passphrase entry. Without this, the second Approve tap
-      // orphans the first stage.
-      const existing = pendingVaultOps.get(pending.chat_id)
-      const newItem = {
-        stageId,
-        cardChatId: pending.chat_id,
-        cardMessageId: pending.card_message_id,
-        senderId,
-      }
-      const items =
-        existing?.kind === 'passphrase-for-access-approve'
-          ? [...existing.items.filter((it) => it.stageId !== stageId), newItem]
-          : [newItem]
-      pendingVaultOps.set(pending.chat_id, {
-        kind: 'passphrase-for-access-approve',
-        items,
-        startedAt: existing?.kind === 'passphrase-for-access-approve' ? existing.startedAt : Date.now(),
-      })
-      // Card text differs slightly when joining an existing batch so
-      // the operator isn't confused by two "Reply with passphrase"
-      // cards open at once.
-      const joiningBatch = items.length > 1
-      await ctx.answerCallbackQuery({ text: joiningBatch ? `🔐 Queued — one passphrase covers ${items.length} cards` : '🔐 Send your passphrase…' }).catch(() => {})
-
-      // Strip the buttons on the ORIGINAL card and mark it "waiting" so it
-      // can't be re-tapped, but do NOT overload it as the passphrase prompt.
-      // An in-place edit fires no notification and stays pinned to the card's
-      // old position in the chat, so a busy topic buries it and the operator
-      // never sees the passphrase ask — the exact admin-key miss this fixes
-      // (v0.16.45: the prompt scrolled off, the passphrase never arrived, the
-      // grant was never minted). The prompt goes out as a fresh message below.
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage(`🔐 _Approved — waiting for your vault passphrase. See the prompt below._`),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-
-      // The passphrase prompt as a NEW rich message. Three fixes vs. the old
-      // in-place edit, all of which the reported bug needed:
-      //   1. Real bold/italic — rendered through the sanctioned `richMessage`
-      //      GFM path (`sendRichMessage`), never a raw string. The old admin
-      //      and joining-batch branches passed raw markdown to editMessageText
-      //      (parse_mode=none), so `**`/`_` rendered as literal characters;
-      //      the "locked" branch even concatenated a string with a
-      //      `richMessage()` object (→ `[object Object]`). All three are gone.
-      //   2. It lands at the BOTTOM of the chat, not stapled to an old card
-      //      that later messages bury.
-      //   3. It fires a notification — `disable_notification` is deliberately
-      //      NOT set — so the operator is actually pinged to act.
-      // Attention-grabbing header, short lines, key in code formatting.
-      const promptText = joiningBatch
-        ? `**⚠️🔐 ACTION NEEDED: passphrase required**\n\n` +
-          `Type your vault passphrase as your **next message**.\n` +
-          `One entry covers **${items.length}** pending approvals in this chat, no re-type per card.\n\n` +
-          `_We delete the passphrase message the moment we read it._`
-        : isAdminOnly
-        ? `**⚠️🔐 ACTION NEEDED: passphrase required**\n\n` +
-          `\`${pending.key}\` is an **admin-only credential**.\n` +
-          `Type your vault passphrase as your **next message** to mint the grant for **${escapeHtmlForTg(pending.agent)}**.\n\n` +
-          `_The passphrase is what proves it's you. An agent can never mint this key on its own. We delete the passphrase message the moment we read it._`
-        : `**⚠️🔐 ACTION NEEDED: passphrase required**\n\n` +
-          `Your vault is locked.\n` +
-          `Reply with your passphrase as your **next message** to unlock and mint the grant for **${escapeHtmlForTg(pending.agent)}**.\n\n` +
-          `_Mint authority stays operator-only: the broker only accepts the grant when the passphrase matches. We delete the passphrase message the moment we read it._`
-
-      // #1075: deleted-topic safe — fall back to the main chat. Wrapped
-      // through robustApiCall for flood-wait retries, mirroring the card send.
-      await retryWithThreadFallback<{ message_id: number }>(
-        robustApiCall,
-        (tid) =>
-          lockedBot.api.sendRichMessage(pending.chat_id, richMessage(promptText), {
-            ...(tid != null && Number.isFinite(tid) ? { message_thread_id: tid } : {}),
-          }),
-        { threadId: pending.threadId, chat_id: pending.chat_id, verb: 'vault_request_access.passphrase_prompt' },
-      ).catch(() => {})
-      return
-    }
-
-    await ctx.answerCallbackQuery({ text: '⏳ Minting grant…' }).catch(() => {})
-    await performVaultAccessApproval(ctx, pending, stageId, senderId, { kind: 'passphrase', passphrase: cached.passphrase })
-    return
-  }
-
-  await ctx.answerCallbackQuery({ text: 'Unknown action' }).catch(() => {})
-}
-
-async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-
-  const parts = data.split(':')
-  if (parts.length < 3) {
-    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
-    return
-  }
-  const action = parts[1]
-  const stageId = parts.slice(2).join(':')
-  const pending = pendingVaultRequestSaves.get(stageId)
-  if (!pending) {
-    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-send.' }).catch(() => {})
-    if (ctx.callbackQuery?.message) {
-      await ctx.api
-        .editMessageText(
-          ctx.callbackQuery.message.chat.id,
-          ctx.callbackQuery.message.message_id,
-          richMessage('⌛ _This vault-save card expired before you tapped. Ask the agent to re-issue if you still want to save._'),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  if (action === 'discard') {
-    pendingVaultRequestSaves.delete(stageId)
-    pendingCardStore.remove(stageId)
-    await ctx.answerCallbackQuery({ text: '🚫 Discarded' }).catch(() => {})
-    if (pending.card_message_id != null) {
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage(`🚫 _Discarded. The secret was not written to the vault._`),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    // Wake the agent that called vault_request_save — symmetric with
-    // the vra: approve/deny path (#1052/#1150/#1156). Without this the
-    // tool returned "waiting for operator", the turn ended, and a
-    // Discard left the agent silently idle forever.
-    const discardInbound = buildVaultSaveDiscardedInbound({
-      ctx: {
-        agent: pending.agent,
-        key: pending.key,
-        chat_id: pending.chat_id,
-        ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-      },
-      stageId,
-      operatorId: senderId,
-    })
-    const dDelivered = deliverResumeSyntheticOrBuffer(pending.agent, discardInbound)
-    process.stderr.write(
-      `telegram gateway: vault_save_discarded injection agent=${pending.agent} ` +
-      `key=${pending.key} stage=${stageId} delivered=${dDelivered}\n`,
-    )
-    return
-  }
-
-  if (action === 'rename') {
-    // Set up a pending-op intercept so the user's next message is read
-    // as the new key name. Same shape as the existing /vault set value
-    // capture (gateway.ts uses pendingVaultOps for this).
-    pendingVaultOps.set(pending.chat_id, {
-      kind: 'rename-vault-save',
-      stageId,
-      startedAt: Date.now(),
-    } as PendingVaultOp)
-    // #1150 audit P0: pre-fix the [Save once][Discard][Rename] keyboard
-    // stayed live after the rename tap so the operator could re-tap
-    // Save with the old key name mid-rename — a Save tap fires the
-    // write immediately, racing the rename intercept. Strip the
-    // keyboard atomically with a status line that names the rename
-    // mode + the proposed new-key prompt. No synthInbound — the
-    // agent's `vault_request_save` tool already returned "waiting
-    // for operator," and the eventual save success/failure flows
-    // its own wake-up below.
-    const sourceMsg = ctx.callbackQuery?.message
-    const baseText = sourceMsg && 'text' in sourceMsg && sourceMsg.text
-      ? escapeHtmlForTg(sourceMsg.text)
-      : ''
-    const statusLine =
-      `\n\n✏️ **Rename mode** — send the new key name as your next message. ` +
-      `The current proposed key is \`${pending.key}\`.`
-    await finalizeCallback(ctx, {
-      ackText: 'Send the new key name as your next message.',
-      newText: baseText ? `${baseText}${statusLine}` : statusLine,
-    })
-    return
-  }
-
-  if (action === 'save') {
-    // Acknowledge the tap immediately so Telegram doesn't show a
-    // stale "spinning" state on the button while we run the write.
-    await ctx.answerCallbackQuery({ text: '⏳ Saving…' }).catch(() => {})
-
-    // Restored-after-restart guard: the staged secret VALUE is held in gateway
-    // memory only and is never persisted (secrets hygiene). If this card was
-    // restored from disk after a gateway restart, the value is gone — we CANNOT
-    // complete the write. Degrade gracefully: strip the card, wake the agent
-    // with a save-failed (value-lost) synthetic so it re-requests, and stop.
-    if (pending.restoredWithoutValue || pending.value.length === 0) {
-      pendingVaultRequestSaves.delete(stageId)
-      pendingCardStore.remove(stageId)
-      if (pending.card_message_id != null) {
-        await ctx.api
-          .editMessageText(
-            pending.chat_id,
-            pending.card_message_id,
-            richMessage(`⚠️ _The staged value for \`${escapeHtmlForTg(pending.key)}\` was lost to a gateway restart — nothing was saved. Ask **${escapeHtmlForTg(pending.agent)}** to re-issue \`vault_request_save\` if you still want to store it._`),
-            { reply_markup: { inline_keyboard: [] } },
-          )
-          .catch(() => {})
-      }
-      const lostInbound = buildVaultSaveFailedInbound({
-        ctx: {
-          agent: pending.agent,
-          key: pending.key,
-          chat_id: pending.chat_id,
-          ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-        },
-        stageId,
-        operatorId: senderId,
-        reason: 'staged value lost to a gateway restart — re-request the save',
-      })
-      const lDelivered = deliverResumeSyntheticOrBuffer(pending.agent, lostInbound)
-      process.stderr.write(
-        `telegram gateway: vault_request_save value lost to restart — wake agent=${pending.agent} ` +
-        `key=${pending.key} stage=${stageId} delivered=${lDelivered}\n`,
-      )
-      return
-    }
-
-    // #1115 follow-up: the save-approve flow now mirrors the access-
-    // approve flow under telegram-id mode — broker `put` accepts
-    // `attest_via_posture: true` (server.ts:1448-1500), so the
-    // gateway can attest the write without a cached passphrase.
-    // Closes the UX gap where tapping Save surfaced a misleading
-    // "🔒 Vault is locked" message even when the broker had been
-    // auto-unlocked at boot.
-    //
-    // Branch: under telegram-id mode use the posture-attested put;
-    // under passphrase mode keep the existing cached-passphrase +
-    // shell-to-CLI path (operator must `/vault unlock` once per
-    // chat session to populate `vaultPassphraseCache`).
-    let write: { ok: boolean; output: string }
-    if (VAULT_APPROVAL_AUTH_MODE === 'telegram-id') {
-      // Posture-attested broker put. No passphrase needed. The broker
-      // verifies (a) telegram-id mode, (b) per-agent peer, (c) broker
-      // unlocked — see server.ts:1448-1500.
-      write = await defaultVaultWritePosture(pending.key, pending.value)
-    } else {
-      // Passphrase mode — fetch the cached passphrase for this chat.
-      // If the gateway hasn't seen the user unlock the vault yet, we
-      // can't attest the write — surface the unlock prompt.
-      const cached = vaultPassphraseCache.get(pending.chat_id)
-      if (!cached || cached.expiresAt <= Date.now()) {
-        if (pending.card_message_id != null) {
-          await ctx.api
-            .editMessageText(
-              pending.chat_id,
-              pending.card_message_id,
-              richMessage(`🔒 **Passphrase not cached for this chat.** Run \`/vault unlock\` (or any /vault command) to cache it, then tap Save again on the next card.`),
-              { reply_markup: { inline_keyboard: [] } },
-            )
-            .catch(() => {})
-        }
-        pendingVaultRequestSaves.delete(stageId)
-        pendingCardStore.remove(stageId)
-        return
-      }
-      // defaultVaultWrite spawns `switchroom vault set <key>` with the
-      // passphrase env set; the CLI forwards the passphrase to the
-      // broker put as operator-attestation (#969 P1a), which authorizes
-      // new-key creation.
-      write = defaultVaultWrite(pending.key, pending.value, cached.passphrase)
-    }
-
-    if (!write.ok) {
-      // Route through the structured-error renderer from #969 P0b so
-      // failures show the actionable host hint instead of a raw blob.
-      const parsed = parseVaultCliError(write.output)
-      const rendered = renderVaultCliError(parsed, { verb: 'save', key: pending.key })
-      const body = rendered.suppressRaw
-        ? rendered.html
-        : `⚠️ vault write failed:\n\`\`\`\n${write.output}\n\`\`\``
-      if (pending.card_message_id != null) {
-        await ctx.api
-          .editMessageText(
-            pending.chat_id,
-            pending.card_message_id,
-            richMessage(`${body}\n\n_Tap a fresh card after fixing the underlying issue._`),
-            { reply_markup: { inline_keyboard: [] } },
-          )
-          .catch(() => {})
-      }
-      // Leave the staged secret in memory until TTL — operator might
-      // retry by re-invoking the same MCP tool, but the value will be
-      // re-staged with a new ID. Drop the current stage.
-      pendingVaultRequestSaves.delete(stageId)
-      pendingCardStore.remove(stageId)
-      // Wake the waiting agent with the failure (symmetric with the
-      // success/discard paths) so it doesn't assume vault:<key> exists.
-      const failReason =
-        (write.output || 'vault write error').split('\n')[0]!.slice(0, 200)
-      const failInbound = buildVaultSaveFailedInbound({
-        ctx: {
-          agent: pending.agent,
-          key: pending.key,
-          chat_id: pending.chat_id,
-          ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-        },
-        stageId,
-        operatorId: senderId,
-        reason: failReason,
-      })
-      const fDelivered = deliverResumeSyntheticOrBuffer(pending.agent, failInbound)
-      process.stderr.write(
-        `telegram gateway: vault_save_failed injection agent=${pending.agent} ` +
-        `key=${pending.key} stage=${stageId} delivered=${fDelivered}\n`,
-      )
-      return
-    }
-
-    // Success — mask the value in the card for visual confirmation.
-    pendingVaultRequestSaves.delete(stageId)
-    pendingCardStore.remove(stageId)
-    if (pending.card_message_id != null) {
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage(`✅ saved as \`vault:${escapeHtmlForTg(pending.key)}\` (masked: \`${escapeHtmlForTg(maskToken(pending.value))}\`)\n_The agent can now reference this as \`vault:${escapeHtmlForTg(pending.key)}\`._`),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    // Wake the agent that called vault_request_save so it resumes the
-    // task that was blocked on this credential (symmetric with the
-    // vra: approve path; buffered if the bridge is mid-reconnect).
-    const okInbound = buildVaultSaveCompletedInbound({
-      ctx: {
-        agent: pending.agent,
-        key: pending.key,
-        chat_id: pending.chat_id,
-        ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
-      },
-      stageId,
-      operatorId: senderId,
-    })
-    const okDelivered = deliverResumeSyntheticOrBuffer(pending.agent, okInbound)
-    process.stderr.write(
-      `telegram gateway: vault_save_completed injection agent=${pending.agent} ` +
-      `key=${pending.key} stage=${stageId} delivered=${okDelivered}\n`,
-    )
-    return
-  }
-
-  await ctx.answerCallbackQuery({ text: 'Unknown action' }).catch(() => {})
-}
-
-async function handleVaultDeferCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-  // vd:<action>:<deferKey>. deferKey itself contains a colon (chat:msgId)
-  // so we slice rather than split — only the first two segments are
-  // structural; the rest is the deferKey verbatim.
-  const rest = data.slice('vd:'.length)
-  const colon = rest.indexOf(':')
-  if (colon < 0) {
-    await ctx.answerCallbackQuery({ text: 'Malformed callback.' }).catch(() => {})
-    return
-  }
-  const action = rest.slice(0, colon)
-  const deferKey = rest.slice(colon + 1)
-  const deferred = deferredSecrets.get(deferKey)
-  if (!deferred) {
-    await ctx.answerCallbackQuery({ text: 'This card expired. Re-send the secret.' }).catch(() => {})
-    await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {})
-    return
-  }
-
-  const cardChatId = String(ctx.chat?.id ?? '')
-  const cardMessageId = ctx.callbackQuery?.message?.message_id
-
-  if (action === 'cancel') {
-    // Kernel-side dual-dispatch (MIGRATION.md §1): record the deny decision
-    // BEFORE the legacy handler clears state, so the audit log captures it
-    // even if the editMessageText below races with another tap. Best-effort
-    // — broker unreachable falls back to legacy-only.
-    await recordDeferredSecretKernelDecision(
-      deferred.kernel_request_id,
-      'deny',
-      ctx.from?.id ?? 0,
-      access.allowFrom,
-    )
-    deferredSecrets.delete(deferKey)
-    await ctx.answerCallbackQuery({ text: 'Discarded.' }).catch(() => {})
-    if (cardMessageId != null) {
-      await ctx
-        .editMessageText('🗑 Discarded — secret was not saved.', {
-          reply_markup: { inline_keyboard: [] },
-        })
-        .catch(() => {})
-    }
-    return
-  }
-
-  if (action === 'unlock') {
-    // Kernel-side dual-dispatch (MIGRATION.md §1): record the allow_once
-    // decision when the user taps unlock. The actual passphrase capture +
-    // vault write still happens via the legacy path below — the kernel
-    // decision is for audit/state, not secret material (per RFC B). We
-    // record at tap-time rather than after passphrase entry so a kernel
-    // record exists even if the user abandons the passphrase prompt.
-    await recordDeferredSecretKernelDecision(
-      deferred.kernel_request_id,
-      'allow_once',
-      ctx.from?.id ?? 0,
-      access.allowFrom,
-    )
-    // #1115 follow-up: telegram-id mode silent-defer-save was withdrawn
-    // (same reason as the save-callback above — the in-memory
-    // passphrase short-circuit became a bypass surface). The
-    // deferred-secret save falls through to the cached-passphrase
-    // path under all postures. Routing executeDeferredSecretSave
-    // through broker-IPC attest_via_posture is a tracked follow-up.
-
-    // If a passphrase is already cached we can skip straight to the write.
-    // Covers the case where the user had unlocked separately between
-    // detection and tap.
-    const cached = vaultPassphraseCache.get(cardChatId)
-    if (cached && cached.expiresAt > Date.now()) {
-      await ctx.answerCallbackQuery({ text: 'Saving…' }).catch(() => {})
-      await executeDeferredSecretSave(ctx, deferKey, cached.passphrase, cardMessageId)
-      return
-    }
-
-    if (cardMessageId == null) {
-      await ctx.answerCallbackQuery({ text: 'Missing card context.' }).catch(() => {})
-      return
-    }
-    pendingVaultOps.set(cardChatId, {
-      kind: 'passphrase-for-deferred',
-      deferKey,
-      cardChatId,
-      cardMessageId,
-      startedAt: Date.now(),
-    })
-    await ctx.answerCallbackQuery({ text: 'Send your passphrase…' }).catch(() => {})
-    await ctx
-      .editMessageText(
-        richMessage('🔐 Send your vault passphrase as your next message — we\'ll save the held secret automatically and delete the passphrase message.'),
-        { reply_markup: { inline_keyboard: [] } },
-      )
-      .catch(() => {})
-    return
-  }
-
-  await ctx.answerCallbackQuery({ text: 'Unknown action.' }).catch(() => {})
-}
-
-// ─── Grant wizard helpers (Issue #227) ──────────────────────────────────────
-// TODO: these helpers duplicate server.ts — extract to a shared module in a
-// future refactor once the two entrypoints are proven stable in production.
-
-/** Parse a duration string like "30d", "7h", "365d" into seconds. */
-function parseGrantDuration(s: string): number | null {
-  const m = /^(\d+)([dh])$/i.exec(s.trim())
-  if (!m) return null
-  const n = parseInt(m[1]!, 10)
-  if (n <= 0) return null
-  return m[2]!.toLowerCase() === 'd' ? n * 86400 : n * 3600
-}
-
-/** Format seconds as a human-readable expiry label. */
-function formatGrantExpiry(ttlSeconds: number | null, now: Date = new Date()): string {
-  if (ttlSeconds === null) return 'Never'
-  const exp = new Date(now.getTime() + ttlSeconds * 1000)
-  return exp.toISOString().slice(0, 10)
-}
-
-/** Build the Step 1 keyboard: agent selection. */
-function buildGrantAgentKeyboard(agents: string[]): InlineKeyboard {
-  const kb = new InlineKeyboard()
-  // Max 3 per row to keep buttons readable on mobile
-  for (let i = 0; i < agents.length; i++) {
-    if (i > 0 && i % 3 === 0) kb.row()
-    kb.text(agents[i]!, `vg:agent:${agents[i]!}`)
-  }
-  kb.row().text('Cancel', 'vg:cancel')
-  return kb
-}
-
-/** Build the Step 2 keyboard: key multi-select toggle. */
-function buildGrantKeysKeyboard(keys: string[], selected: Set<string>): InlineKeyboard {
-  const kb = new InlineKeyboard()
-  for (const k of keys) {
-    const check = selected.has(k) ? '☑' : '☐'
-    kb.row().text(`${check} ${k}`, `vg:key:${k}`)
-  }
-  kb.row()
-    .text('Continue', 'vg:keys-continue')
-    .text('Cancel', 'vg:cancel')
-  return kb
-}
-
-/** Build the Step 3 keyboard: duration selection. */
-function buildGrantDurationKeyboard(): InlineKeyboard {
-  return new InlineKeyboard()
-    .text('30 days', 'vg:dur:30d')
-    .text('90 days', 'vg:dur:90d')
-    .text('1 year', 'vg:dur:1y')
-    .row()
-    .text('Custom…', 'vg:dur:custom')
-    .text('No expiry', 'vg:dur:never')
-    .row()
-    .text('Back', 'vg:back:duration')
-    .text('Cancel', 'vg:cancel')
-}
-
-/** Build the Confirm keyboard. */
-function buildGrantConfirmKeyboard(): InlineKeyboard {
-  return new InlineKeyboard()
-    .text('Generate', 'vg:generate')
-    .text('Cancel', 'vg:cancel')
-}
-
-/** Start the grant wizard (step 1: pick agent). */
-async function startGrantWizardStep1(ctx: Context, chatId: string): Promise<void> {
-  type AgentListResp = { agents: Array<{ name: string }> }
-  const data = switchroomExecJson<AgentListResp>(['agent', 'list'])
-  const agents = data?.agents?.map(a => a.name).filter(Boolean) ?? []
-  if (agents.length === 0) {
-    await switchroomReply(ctx, '⚠️ No agents found in switchroom.yaml.', { html: true })
-    return
-  }
-  const kb = buildGrantAgentKeyboard(agents)
-  const sent = await switchroomReply(ctx, '**Grant capability token — Step 1/3**\n\nWhich agent?', { html: true, reply_markup: kb })
-  const wizardMsgId = (sent as unknown as { message_id?: number })?.message_id
-  pendingVaultOps.set(chatId, {
-    kind: 'grant-wizard',
-    step: 'agent',
-    wizardMsgId,
-    startedAt: Date.now(),
-  })
-}
-
-/** Advance grant wizard to step 2 (pick keys). */
-async function grantWizardStep2(ctx: Context, chatId: string, agent: string, wizardMsgId: number | undefined): Promise<void> {
-  const keys = await listViaBroker()
-  if (!keys) {
-    await switchroomReply(ctx, '🔴 Broker is not running (or unreachable). Cannot list vault keys.', { html: true })
-    pendingVaultOps.delete(chatId)
-    return
-  }
-  if (keys.length === 0) {
-    await switchroomReply(ctx, '⚠️ No vault keys found. Add secrets first with \`/vault set\`.', { html: true })
-    pendingVaultOps.delete(chatId)
-    return
-  }
-  const selected = new Set<string>()
-  const kb = buildGrantKeysKeyboard(keys, selected)
-  const text = `**Grant capability token — Step 2/3**\n\nWhich keys for \`${agent}\`?\n_Tap to toggle; tap Continue when done._`
-  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, richMessage(text), { reply_markup: kb }).catch(() => {})
-  } else {
-    const sent = await switchroomReply(ctx, text, { html: true, reply_markup: kb })
-    wizardMsgId = (sent as unknown as { message_id?: number })?.message_id
-  }
-  pendingVaultOps.set(chatId, {
-    kind: 'grant-wizard',
-    step: 'keys',
-    agent,
-    selectedKeys: [],
-    availableKeys: keys,
-    wizardMsgId,
-    startedAt: Date.now(),
-  })
-}
-
-/** Advance grant wizard to step 3 (pick duration). */
-async function grantWizardStep3(ctx: Context, chatId: string, state: Extract<PendingVaultOp, { kind: 'grant-wizard' }>): Promise<void> {
-  const kb = buildGrantDurationKeyboard()
-  const keyList = state.selectedKeys!.map(k => `• \`${k}\``).join('\n')
-  const text = `**Grant capability token — Step 3/3**\n\nKeys for \`${state.agent!}\`:\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, richMessage(text), { reply_markup: kb }).catch(() => {})
-  } else {
-    const sent = await switchroomReply(ctx, text, { html: true, reply_markup: kb })
-    state.wizardMsgId = (sent as unknown as { message_id?: number })?.message_id
-  }
-  pendingVaultOps.set(chatId, { ...state, step: 'duration' })
-}
-
-/** Advance grant wizard to confirmation step. */
-async function grantWizardConfirm(ctx: Context, chatId: string, state: Extract<PendingVaultOp, { kind: 'grant-wizard' }>): Promise<void> {
-  const kb = buildGrantConfirmKeyboard()
-  const expiresLabel = formatGrantExpiry(state.ttlSeconds!)
-  const keyList = state.selectedKeys!.map(k => `• \`${k}\``).join('\n')
-  const text = [
-    '**Confirm grant**',
-    '',
-    `Agent: \`${state.agent!}\``,
-    `Keys:\n${keyList}`,
-    `Expires: **${escapeHtmlForTg(expiresLabel)}**`,
-    '',
-    'Tap **Generate** to mint the token.',
-  ].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, richMessage(text), { reply_markup: kb }).catch(() => {})
-  } else {
-    const sent = await switchroomReply(ctx, text, { html: true, reply_markup: kb })
-    state.wizardMsgId = (sent as unknown as { message_id?: number })?.message_id
-  }
-  // Mint kernel decision row at the confirm step (MIGRATION.md §2,
-  // audit-only Phase 1). We do it here rather than at executeGrantWizard
-  // so a kernel row exists even if the user taps Cancel from the confirm
-  // card — the deny verdict on cancel is then recorded against the same
-  // request_id. If the kernel/broker is unreachable, request_id stays
-  // undefined and the wizard runs legacy-only (no behaviour change).
-  const kernelRequestId = await mintGrantWizardKernelRequest(
-    state.agent!,
-    loadAccess().allowFrom,
-    state.selectedKeys!,
-    state.ttlSeconds ?? null,
-  )
-  pendingVaultOps.set(chatId, {
-    ...state,
-    step: 'confirm',
-    expiresLabel,
-    kernel_request_id: kernelRequestId ?? state.kernel_request_id,
-  })
-}
-
-/** Execute the grant: call broker mint_grant, write token, reply. */
-async function executeGrantWizard(ctx: Context, chatId: string, state: Extract<PendingVaultOp, { kind: 'grant-wizard' }>): Promise<void> {
-  pendingVaultOps.delete(chatId)
-  // Kernel-side dual-dispatch (MIGRATION.md §2, audit-only Phase 1):
-  // record the allow_once decision when the user taps Generate. The
-  // legacy `mintGrantViaBroker` below still drives the actual grant
-  // mint + token write — the kernel row is informational, not
-  // enforcing, in Phase 1 (issue #833 will flip to enforcing).
-  // We record at tap-time rather than after mint_grant succeeds so a
-  // kernel row exists even if the legacy mint fails (audit captures
-  // intent regardless of downstream outcome).
-  await recordGrantWizardKernelDecision(
-    state.kernel_request_id,
-    'allow_once',
-    ctx.from?.id ?? 0,
-    loadAccess().allowFrom,
-  )
-  // Defence-in-depth: state.agent flows from callback_data into a path
-  // join below. A crafted vg:agent:../../etc payload would produce a
-  // path traversal. Validate against the same regex the rest of the
-  // file uses; on failure, drop silently — the wizard message has
-  // already been finalized.
-  try { assertSafeAgentName(state.agent!) } catch { return }
-  const result = await mintGrantViaBroker({
-    agent: state.agent!,
-    keys: state.selectedKeys!,
-    ttl_seconds: state.ttlSeconds ?? null,
-    description: state.description,
-  })
-  if (result.kind === 'unreachable') {
-    await switchroomReply(ctx, `🔴 Broker unreachable: ${escapeHtmlForTg(result.msg)}`, { html: true })
-    return
-  }
-  if (result.kind === 'error') {
-    await switchroomReply(ctx, `**mint_grant failed:** ${escapeHtmlForTg(result.msg)}`, { html: true })
-    return
-  }
-  // Write token to the agent's .vault-token file
-  const { token, id } = result
-  const tokenPath = join(homedir(), '.switchroom', 'agents', state.agent!, '.vault-token')
-  try {
-    mkdirSync(join(homedir(), '.switchroom', 'agents', state.agent!), { recursive: true })
-    writeFileSync(tokenPath, token, { mode: 0o600 })
-  } catch (err) {
-    await switchroomReply(ctx, `**Grant created but token write failed:** ${escapeHtmlForTg(String(err))}`, { html: true })
-    return
-  }
-  // Collapse wizard message to just the outcome.
-  // #1150 audit: P0 fix — pre-fix this `editMessageText` call omitted
-  // `reply_markup: { inline_keyboard: [] }` so the wizard's [Generate]
-  // / [Cancel] buttons stayed tappable on the success card. Operator
-  // could re-tap [Generate] and mint a second redundant grant.
-  // Strip the keyboard atomically with the success text via the
-  // finalizeCallback helper.
-  const msgId = state.wizardMsgId
-  const successText = `✅ Grant \`${id}\` created. Written to \`~/.switchroom/agents/${escapeHtmlForTg(state.agent!)}/.vault-token\``
-  if (msgId != null) {
-    await finalizeCallback(ctx, {
-      ackText: '✅ Grant created',
-      newText: successText,
-      // No synthInbound — operator-only flow.
-    })
-  } else {
-    // Fallback when wizard message id was lost (rare; e.g. operator
-    // deleted the card). Send a fresh reply with the success text;
-    // no keyboard to strip in this branch.
-    await switchroomReply(ctx, successText, { html: true })
-  }
-}
-
-/**
- * Issue #228: handle vault grant management callbacks.
- *
- *   `vg:revoke:<grantId>`  — fetch grant details and show confirmation card.
- *   `vg:confirm:<grantId>` — call broker revoke_grant, reply with success.
- *   `vg:cancel:<grantId>`  — dismiss (clear keyboard, no broker call).
- *
- * Issue #227: also handles /vault grant wizard callbacks.
- *
- *   `vg:cancel`            — cancel wizard at any step.
- *   `vg:agent:<name>`      — step 1: select agent.
- *   `vg:key:<name>`        — step 2: toggle key selection.
- *   `vg:keys-continue`     — step 2 → 3.
- *   `vg:dur:<value>`       — step 3: duration selection.
- *   `vg:back:duration`     — step 3 → back to step 2.
- *   `vg:generate`          — confirm and mint token.
- */
-async function handleVaultGrantCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-
-  const revokeMatch = /^vg:revoke:(.+)$/.exec(data)
-  if (revokeMatch) {
-    const grantId = revokeMatch[1]!
-    const result = await listGrantsViaBroker(undefined)
-    if (result.kind !== 'ok') {
-      await ctx.answerCallbackQuery({ text: 'Broker unreachable.' }).catch(() => {})
-      return
-    }
-    const grant = result.grants.find(g => g.id === grantId)
-    if (!grant) {
-      await ctx.answerCallbackQuery({ text: 'Grant not found (already revoked?).' }).catch(() => {})
-      await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {})
-      return
-    }
-    const cardText =
-      `🗑 Revoke \`${grantId}\`?\n` +
-      `Agent: **${escapeHtmlForTg(grant.agent_slug)}**\n` +
-      `Keys: \`${escapeHtmlForTg(grant.key_allow.join(', '))}\``
-    const confirmKeyboard = new InlineKeyboard()
-      .text('✅ Confirm Revoke', `vg:confirm:${grantId}`)
-      .text('❌ Cancel', `vg:cancel:${grantId}`)
-    await ctx.answerCallbackQuery().catch(() => {})
-    await ctx.editMessageText(richMessage(cardText), {
-      reply_markup: confirmKeyboard,
-    }).catch(async () => {
-      const chatId = String(ctx.chat?.id ?? ctx.from?.id ?? '')
-      const threadId = ctx.callbackQuery?.message?.message_thread_id
-      if (chatId) {
-        // #1075: thread-id-bearing — swallow on THREAD_NOT_FOUND.
-        await swallowingApiCall(
-          () =>
-            bot.api.sendRichMessage(chatId, richMessage(cardText), {
-              reply_markup: confirmKeyboard,
-              ...(threadId != null ? { message_thread_id: threadId } : {}),
-            }),
-          {
-            chat_id: chatId,
-            verb: 'vault-revoke-confirm-fallback',
-            ...(threadId != null ? { threadId } : {}),
-          },
-        )
-      }
-    })
-    return
-  }
-
-  const confirmMatch = /^vg:confirm:(.+)$/.exec(data)
-  if (confirmMatch) {
-    const grantId = confirmMatch[1]!
-    const revokeResult = await revokeGrantViaBroker(grantId)
-    if (revokeResult.kind === 'unreachable') {
-      await ctx.answerCallbackQuery({ text: 'Broker unreachable.' }).catch(() => {})
-      return
-    }
-    if (revokeResult.kind === 'error') {
-      await ctx.answerCallbackQuery({ text: `Revoke failed: ${revokeResult.msg}` }).catch(() => {})
-      return
-    }
-    await ctx.answerCallbackQuery({ text: '✅ Revoked' }).catch(() => {})
-    await ctx.editMessageText(
-      richMessage(`✅ Grant \`${grantId}\` revoked. Token file removed.`),
-      { reply_markup: { inline_keyboard: [] } },
-    ).catch(() => {})
-    return
-  }
-
-  const cancelMatch = /^vg:cancel:(.+)$/.exec(data)
-  if (cancelMatch) {
-    await ctx.answerCallbackQuery({ text: 'Cancelled.' }).catch(() => {})
-    await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {})
-    return
-  }
-
-  // #227 grant wizard callbacks (vg:cancel bare, vg:agent:*, vg:key:*, vg:keys-continue,
-  // vg:dur:*, vg:back:*, vg:generate). These come after the management callbacks above
-  // because management uses vg:cancel:<id> (with trailing id) while the wizard uses
-  // bare vg:cancel — the cancelMatch above only matches the id-suffixed form.
-  //
-  // Note: pre-#265 fix this function did `await ctx.answerCallbackQuery().catch(() => {})`
-  // unconditionally up front. That meant the `vg:keys-continue` branch's
-  // toast call (`Select at least one key.`) hit a Telegram error
-  // ("query is too old or query ID is invalid") because the query was
-  // already answered, and the toast never reached the user. Each branch
-  // now owns its own ack.
-  const chatId = String(ctx.chat?.id ?? ctx.from?.id ?? '')
-  const ackSilently = () => ctx.answerCallbackQuery().catch(() => {})
-
-  // Cancel at any wizard step
-  if (data === 'vg:cancel') {
-    // Kernel-side dual-dispatch (MIGRATION.md §2, audit-only Phase 1):
-    // if the user got as far as the confirm step, a kernel request_id
-    // will be on the wizard state — record the deny decision so the
-    // audit log captures the abandonment. No-op if the user cancelled
-    // before the confirm step (or if the kernel was unreachable).
-    const cancelState = pendingVaultOps.get(chatId)
-    if (cancelState && cancelState.kind === 'grant-wizard') {
-      await recordGrantWizardKernelDecision(
-        cancelState.kernel_request_id,
-        'deny',
-        ctx.from?.id ?? 0,
-        loadAccess().allowFrom,
-      )
-    }
-    pendingVaultOps.delete(chatId)
-    const msg = ctx.callbackQuery?.message
-    if (msg && 'text' in msg) {
-      await ctx.editMessageText('❌ Grant wizard cancelled.').catch(() => {})
-    }
-    await ackSilently()
-    return
-  }
-
-  const state = pendingVaultOps.get(chatId)
-  if (!state || state.kind !== 'grant-wizard') {
-    await ctx.editMessageText('⚠️ Wizard session expired. Run /vault grant to start again.').catch(() => {})
-    await ackSilently()
-    return
-  }
-
-  // vg:agent:<name> — step 1 selection
-  if (data.startsWith('vg:agent:')) {
-    const agent = data.slice('vg:agent:'.length)
-    const msgId = (ctx.callbackQuery?.message as { message_id?: number })?.message_id ?? state.wizardMsgId
-    await grantWizardStep2(ctx, chatId, agent, msgId)
-    await ackSilently()
-    return
-  }
-
-  // vg:key:<name> — step 2 toggle
-  if (data.startsWith('vg:key:')) {
-    const key = data.slice('vg:key:'.length)
-    if (state.step !== 'keys') { await ackSilently(); return }
-    const selectedSet = new Set(state.selectedKeys ?? [])
-    if (selectedSet.has(key)) {
-      selectedSet.delete(key)
-    } else {
-      selectedSet.add(key)
-    }
-    const updatedState = { ...state, selectedKeys: [...selectedSet] }
-    pendingVaultOps.set(chatId, updatedState)
-    const kb = buildGrantKeysKeyboard(state.availableKeys ?? [], selectedSet)
-    await ctx.editMessageReplyMarkup({ reply_markup: kb }).catch(() => {})
-    await ackSilently()
-    return
-  }
-
-  // vg:keys-continue — step 2 → 3
-  if (data === 'vg:keys-continue') {
-    if (state.step !== 'keys') { await ackSilently(); return }
-    if (!state.selectedKeys || state.selectedKeys.length === 0) {
-      // Toast-only ack: this is the branch the unconditional pre-ack
-      // used to silently swallow. See #265.
-      await ctx.answerCallbackQuery({ text: 'Select at least one key.' }).catch(() => {})
-      return
-    }
-    await grantWizardStep3(ctx, chatId, state)
-    await ackSilently()
-    return
-  }
-
-  // vg:dur:<value> — step 3 duration selection
-  if (data.startsWith('vg:dur:')) {
-    if (state.step !== 'duration') { await ackSilently(); return }
-    const dur = data.slice('vg:dur:'.length)
-    if (dur === 'custom') {
-      // Ask for text reply with n d|h format
-      pendingVaultOps.set(chatId, { ...state, awaitingCustomDuration: true })
-      const msg = ctx.callbackQuery?.message
-      if (msg && 'text' in msg && msg.text) {
-        // Escape source text before re-rendering with HTML parse mode.
-        // `msg.text` returns entities-stripped plain UTF-8; a raw
-        // `<`/`>`/`&` in the wizard's prior-step body (e.g. a future
-        // key or label) would crash the HTML re-parse and the bare
-        // `.catch(() => {})` would swallow the failure silently — same
-        // hazard PR #1158 caught on the operator-event card.
-        await ctx.editMessageText(
-          richMessage(escapeHtmlForTg(msg.text) + '\n\n_Send a duration like \`30d\` or \`12h\`:_'),
-          { reply_markup: buildGrantDurationKeyboard() },
-        ).catch(() => {})
-      }
-      await ackSilently()
-      return
-    }
-    let ttlSeconds: number | null
-    if (dur === 'never') {
-      ttlSeconds = null
-    } else if (dur === '1y') {
-      ttlSeconds = 365 * 86400
-    } else {
-      ttlSeconds = parseGrantDuration(dur)
-      if (ttlSeconds === null) { await ackSilently(); return }
-    }
-    const newState = { ...state, ttlSeconds, awaitingCustomDuration: false }
-    await grantWizardConfirm(ctx, chatId, newState)
-    await ackSilently()
-    return
-  }
-
-  // vg:back:duration — go back to step 2 (keys selection) from step 3
-  if (data === 'vg:back:duration') {
-    if (state.step !== 'duration') { await ackSilently(); return }
-    const msgId = state.wizardMsgId
-    await grantWizardStep2(ctx, chatId, state.agent!, msgId)
-    await ackSilently()
-    return
-  }
-
-  // vg:generate — final step
-  if (data === 'vg:generate') {
-    if (state.step !== 'confirm') { await ackSilently(); return }
-    await executeGrantWizard(ctx, chatId, state)
-    await ackSilently()
-    return
-  }
-
-  // Unrecognised vg: sub-action
-  await ackSilently()
-}
-
-/**
- * Issue #44: write a deferred secret to the vault using the now-cached
- * passphrase. Confirms with a masked ref + slug; matches the "captured
- * N secret" UX of the cached-passphrase happy path so the user
- * experience is identical regardless of which path they came in on.
- *
- * Called from two places:
- *   - The `passphrase-for-deferred` branch of the text-handler
- *     pendingVaultOps intercept, after the passphrase is verified.
- *   - The `vd:unlock` callback handler when a passphrase happens to
- *     already be cached (rare but possible).
- *
- * If write fails, the deferred entry is preserved so the user can retry.
- */
-async function executeDeferredSecretSave(
-  ctx: Context,
-  deferKey: string,
-  passphrase: string,
-  cardMessageId: number | undefined,
-): Promise<void> {
-  const deferred = deferredSecrets.get(deferKey)
-  if (!deferred) {
-    if (cardMessageId != null) {
-      await ctx.api
-        .editMessageText(
-          deferKey.split(':')[0]!,
-          cardMessageId,
-          '⚠️ This card expired before unlock — please re-send the secret.',
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  // De-duplicate suggested_slug against existing vault keys by appending
-  // _2 / _3 / … if needed. Same logic as the cached-passphrase happy
-  // path uses (gateway.ts ~L2402 stash command).
-  const slugBase = deferred.suggested_slug || 'secret'
-  const listed = defaultVaultList(passphrase)
-  const existing = new Set(listed.ok ? listed.keys : [])
-  let slug = slugBase
-  let n = 2
-  while (existing.has(slug)) slug = `${slugBase}_${n++}`
-
-  const write = defaultVaultWrite(slug, deferred.text, passphrase)
-  if (!write.ok) {
-    // Classify the failure via the structured stderr markers emitted by
-    // `switchroom vault` (issue #969 P0a). If it's a recognised marker,
-    // render a clean actionable message instead of dumping the raw
-    // "Vault file not found …" / "VAULT-NEEDS-APPROVAL …" blob the CLI
-    // emits — that was the misleading-error half of #968.
-    //
-    // Keep the deferred entry so the user can retry by tapping again
-    // once the underlying condition is fixed (broker started, host
-    // approval granted, etc.).
-    const parsed = parseVaultCliError(write.output)
-    const rendered = renderVaultCliError(parsed, { verb: "save", key: slug })
-    const body = rendered.suppressRaw
-      ? rendered.html
-      : `⚠️ vault write failed:\n\`\`\`\n${write.output}\n\`\`\``
-    if (cardMessageId != null) {
-      await ctx.api
-        .editMessageText(
-          deferred.chat_id,
-          cardMessageId,
-          richMessage(`${body}\n\nRe-tap to retry.`),
-          {
-            reply_markup: buildDeferredSecretKeyboard(deferKey).inline_keyboard.length > 0
-              ? buildDeferredSecretKeyboard(deferKey)
-              : undefined,
-          },
-        )
-        .catch(() => {})
-    }
-    return
-  }
-
-  deferredSecrets.delete(deferKey)
-  const masked = maskToken(deferred.text)
-  if (cardMessageId != null) {
-    await ctx.api
-      .editMessageText(
-        deferred.chat_id,
-        cardMessageId,
-        richMessage(`✅ stored as \`vault:${slug}\` (masked: \`${masked}\`)\n\nReply \`rename NEW_NAME\` to relabel.`),
-        { reply_markup: { inline_keyboard: [] } },
-      )
-      .catch(() => {})
-  }
-  // Stage for follow-up rename, mirroring the cached-passphrase path.
-  secretStaging.set({
-    chat_id: deferred.chat_id,
-    message_id: deferred.original_message_id,
-    detection: {
-      rule_id: 'deferred',
-      matched_text: deferred.text,
-      start: 0,
-      end: deferred.text.length,
-      confidence: 'high' as const,
-      suppressed: false,
-      suggested_slug: slug,
-    },
-    staged_at: Date.now(),
-  })
-}
-
-async function handleOperatorEventCallback(ctx: Context, data: string): Promise<void> {
-  const senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-
-  // Parse op:<action>:<encoded-agent>
-  const parts = data.slice(3).split(':', 2)  // drop "op:", then split action:agent
-  if (parts.length !== 2) {
-    await ctx.answerCallbackQuery({ text: 'Malformed operator-event callback.' }).catch(() => {})
-    return
-  }
-  const [action, encodedAgent] = parts
-  let agent: string
-  try {
-    agent = decodeURIComponent(encodedAgent)
-  } catch {
-    await ctx.answerCallbackQuery({ text: 'Bad agent name encoding.' }).catch(() => {})
-    return
-  }
-  if (!/^[a-z0-9][a-z0-9_-]{0,50}$/.test(agent)) {
-    await ctx.answerCallbackQuery({ text: 'Invalid agent name.' }).catch(() => {})
-    return
-  }
-
-  // #1150 audit P1: extract the source card text once so every branch
-  // below can append a status line via finalizeCallback. Pre-fix `dismiss`
-  // and `restart` stripped the keyboard but kept the original card body
-  // verbatim — operator scrolling back couldn't see what they'd decided.
-  // `reauth` didn't strip the keyboard at all → re-tappable mid-flow.
-  //
-  // HTML-escape the extracted text before concatenation. Telegram returns
-  // `msg.text` as plain UTF-8 with entities stripped — any raw `<`, `>`,
-  // or `&` characters in the original `detail` (operator-events.ts
-  // `unknown-4xx`/`unknown-5xx` cards routinely carry API error bodies
-  // with `<`/`>` in them) would be re-parsed as HTML tags when the
-  // finalizeCallback edit fires with `parseMode: 'HTML'`. Telegram
-  // rejects the edit, finalizeCallback's catch swallows it, the
-  // keyboard never strips, and the operator re-taps → exact bug this
-  // PR is meant to fix re-introduced. Escape once here so every branch
-  // gets a safe-to-reparse value. We lose the original bold/italic
-  // styling on the source body — acceptable, that styling was already
-  // gone the moment `msg.text` was read instead of `msg.entities`.
-  // (PR #1158 round 2 — review item F.)
-  const sourceMsgText = (() => {
-    const msg = ctx.callbackQuery?.message
-    if (!msg || !('text' in msg) || !msg.text) return ''
-    return escapeHtmlForTg(msg.text)
-  })()
-
-  switch (action) {
-    case 'dismiss': {
-      // #1150 audit P1: was strip-only. Now appends a status line so
-      // scrollback shows the dismissal.
-      const status = `\n\n✗ _Dismissed by operator._`
-      await finalizeCallback(ctx, {
-        ackText: 'Dismissed',
-        newText: sourceMsgText ? `${sourceMsgText}${status}` : status,
-        // No synthInbound — dismiss is operator-only, no model in loop.
-      })
-      return
-    }
-    case 'restart': {
-      const ok = triggerSelfRestart(agent, 'inline-button-restart')
-      if (ok) {
-        // #1150 audit P1: was reply + editMessageReplyMarkup (two
-        // separate edits). Atomic via finalizeCallback now — the
-        // status line is the announcement, no separate reply needed.
-        const status = `\n\n🔄 _**${escapeHtmlForTg(agent)}** restart requested by operator._`
-        await finalizeCallback(ctx, {
-          ackText: `Restarting ${agent}…`,
-          newText: sourceMsgText ? `${sourceMsgText}${status}` : status,
-        })
-      } else {
-        // Failure-path: leave the keyboard tappable so the operator
-        // can retry once they've followed the manual instructions
-        // below. ack toast still fires.
-        await ctx.answerCallbackQuery({ text: `Restart failed for ${agent}` }).catch(() => {})
-        const isDocker = process.env.SWITCHROOM_RUNTIME === 'docker'
-        const detail = isDocker
-          ? `cross-agent restart is not supported under docker. ` +
-            `Restart from the host: \`docker compose -p switchroom restart agent-${agent}\`.`
-          : 'restart trigger failed'
-        await ctx.replyWithRichMessage(richMessage(`**Restart failed for ${agent}:** ${detail}`))
-      }
-      return
-    }
-    case 'reauth': {
-      // #1150 audit P1: pre-fix the operator-event card's [Reauth] button
-      // stayed tappable after the reauth flow started → operator could
-      // re-tap and spawn a second concurrent flow that fights the first
-      // for the login URL state. Strip the keyboard and append a status
-      // line; the new reauth-flow's own messages appear below the
-      // collapsed card.
-      const status = `\n\n🔐 _Reauth started for **${escapeHtmlForTg(agent)}** — follow the login URL below._`
-      await finalizeCallback(ctx, {
-        ackText: `Starting reauth for ${agent}…`,
-        newText: sourceMsgText ? `${sourceMsgText}${status}` : status,
-        synthInbound: async () => {
-          await runSwitchroomAuthCommand(ctx, ['auth', 'reauth', agent], `auth reauth ${agent}`)
-          // PR3 supergroup-mode: key by (chat, thread) so an OAuth code
-          // pasted into a different topic isn't mistakenly intercepted
-          // as this flow's reauth code.
-          const reauthThreadId = ctx.callbackQuery?.message?.message_thread_id
-          pendingReauthFlows.set(
-            chatKey(String(ctx.chat!.id), reauthThreadId ?? null) as string,
-            { agent, startedAt: Date.now() },
-          )
-        },
-      })
-      return
-    }
-    case 'logs': {
-      await ctx.answerCallbackQuery({ text: 'Fetching logs…' }).catch(() => {})
-      // Pick the right log source for the runtime. Under docker, the
-      // gateway is INSIDE the agent container — calling `docker logs`
-      // requires the host's docker socket which is deliberately not
-      // mounted into agent containers. Under systemd, journalctl
-      // works as before. v0.7.2 fixed `case 'restart'` but left this
-      // path systemd-only.
-      const isDocker = process.env.SWITCHROOM_RUNTIME === 'docker'
-      if (isDocker) {
-        await ctx.replyWithRichMessage(richMessage(
-          `_Inline log fetch is not available under docker mode (no docker.sock in agent containers). ` +
-            `Run from the host: \`docker logs --since 30m --tail 30 switchroom-${agent}\`_`,
-        ))
-        return
-      }
-      try {
-        const out = execFileSync(
-          'journalctl',
-          ['--user', '-u', `switchroom-${agent}`, '-n', '30', '--no-pager', '--output=short-monotonic'],
-          { encoding: 'utf-8', timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'] },
-        ) as string
-        const trimmed = out.trim().slice(-3500)
-        await ctx.replyWithRichMessage(richMessage(
-          trimmed
-            ? `\`\`\`\n${trimmed.replace(/```/g, '`​``')}\n\`\`\``
-            : `_No logs for ${agent}._`,
-        ))
-      } catch (err) {
-        await ctx.replyWithRichMessage(richMessage(
-          `**logs failed:** ${escapeHtmlForTg((err as Error).message)}`,
-        ))
-      }
-      return
-    }
-    default: {
-      await ctx.answerCallbackQuery({ text: `Unknown action: ${action}` }).catch(() => {})
-      return
-    }
-  }
-}
-
-// RFC H §7.3: the dashboard callback dispatcher is gone — there are
-// no auth: callback buttons in the new chat surface. We keep a no-op
-// stub so any stale pinned message that fires an `auth:*` tap is
-// silently dismissed instead of crashing the gateway.
-async function handleAuthDashboardCallback(ctx: Context): Promise<void> {
-  const data = ctx.callbackQuery?.data ?? ''
-  const currentAgent = getMyAgentName()
-
-  // auth:use:<label> — fleet-wide swap via broker.setActive (same path
-  // /auth use takes from chat). Admin-gated via the broker's own
-  // per-agent admin flag.
-  if (data.startsWith('auth:use:')) {
-    const label = data.slice('auth:use:'.length)
-    if (!label) {
-      try { await ctx.answerCallbackQuery({ text: 'Missing account label.', show_alert: false }) } catch { /* */ }
-      return
-    }
-    try {
-      const client = await getAuthBrokerClient(currentAgent)
-      if (!client) {
-        try { await ctx.answerCallbackQuery({ text: 'Broker unreachable.', show_alert: true }) } catch { /* */ }
-        return
-      }
-      const result = await client.setActive(label)
-      try {
-        await ctx.answerCallbackQuery({
-          text: `Switched fleet → ${result.active} (${result.fanned.length} agents)`,
-          show_alert: false,
-        })
-      } catch { /* toast may fail on stale tap */ }
-      // Edit the source message to reflect the new active. Leaving
-      // the old keyboard intact would tempt a double-tap; we replace
-      // the text + drop the keyboard so the user has to /auth again
-      // to see fresh state.
-      const msg = ctx.callbackQuery?.message
-      if (msg) {
-        // Wrap in swallowingApiCall per #1075 — stale callback-source
-        // messages (deleted topic, expired) shouldn't crash the swap.
-        await swallowingApiCall(
-          () =>
-            bot.api.editMessageText(
-              msg.chat.id,
-              msg.message_id,
-              richMessage(
-                `**Active account →** \`${result.active}\`\n` +
-                `_Re-mirrored credentials for ${result.fanned.length} agent${result.fanned.length === 1 ? '' : 's'}._\n\n` +
-                `_Tap /auth to see updated quota for the new active account._`,
-              ),
-              {},
-            ),
-          { chat_id: String(msg.chat.id), verb: 'auth:use:edit' },
-        )
-      }
-    } catch (err) {
-      const msg = (err as Error)?.message ?? String(err)
-      try {
-        await ctx.answerCallbackQuery({
-          text: `Switch failed: ${msg.slice(0, 180)}`,
-          show_alert: true,
-        })
-      } catch { /* */ }
-    }
-    return
-  }
-
-  // auth:refresh — re-render the /auth snapshot in-place with a fresh
-  // live probe. Replaces the message body; keyboard stays. The `:demo`
-  // variant re-renders with email masking intact (a ↻ tap on an
-  // `/auth demo` / `/usage demo` card must not unmask mid-recording).
-  if (data === 'auth:refresh' || data === 'auth:refresh:demo') {
-    const refreshDemo = data === 'auth:refresh:demo'
-    // Freshness throttle: each refresh fan-fires N live api.anthropic.com
-    // probes (one per account — forceLive bypasses the broker's 45s
-    // probe-on-open TTL, because an explicit ↻ tap is the user asking
-    // for live-now data). Without this, a user double-tapping the ↻
-    // button burns through their account's RPM budget on duplicate
-    // work. Cap at one per AUTH_REFRESH_THROTTLE_MS per (chat, message)
-    // pair.
-    const refreshMsg = ctx.callbackQuery?.message
-    if (refreshMsg) {
-      const key = `${refreshMsg.chat.id}:${refreshMsg.message_id}`
-      const lastAtMs = lastAuthRefreshAtMs.get(key) ?? 0
-      const sinceLastMs = Date.now() - lastAtMs
-      if (sinceLastMs < AUTH_REFRESH_THROTTLE_MS) {
-        const waitS = Math.ceil((AUTH_REFRESH_THROTTLE_MS - sinceLastMs) / 1000)
-        try {
-          await ctx.answerCallbackQuery({
-            text: `Just refreshed — try again in ${waitS}s`,
-            show_alert: false,
-          })
-        } catch { /* */ }
-        return
-      }
-      lastAuthRefreshAtMs.set(key, Date.now())
-    }
-    try {
-      const client = await getAuthBrokerClient(currentAgent)
-      if (!client) {
-        try { await ctx.answerCallbackQuery({ text: 'Broker unreachable.', show_alert: true }) } catch { /* */ }
-        return
-      }
-      const state = await client.listState()
-      // Broker-routed probe (#1336) — see gateway.ts:8910 for diagnosis.
-      // forceLive=true: an explicit ↻ tap must bypass the broker's
-      // probe-on-open TTL — pre-fix, a tap inside the TTL window served
-      // the cached snapshot while stamping "Live · refreshed 0s ago".
-      const probeResp = state.accounts.length > 0
-        ? await client.probeQuota(state.accounts.map((a) => a.label), undefined, true).catch(() => ({ results: [] }))
-        : { results: [] }
-      // #2495 Change 2 — even under forceLive a failed upstream probe falls
-      // back to the broker cache (served:"cache"); stamp "⚠ cached Nm ago"
-      // instead of a false live stamp, same as the /auth and /usage paths.
-      const { quotas, staleCachedAtMs } = zipProbeResults(
-        state.accounts.map((a) => a.label),
-        probeResp.results,
-      )
-      const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
-      const { renderAuthSnapshotFormat2, buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
-        '../auth-snapshot-format.js'
-      )
-      const snapshots = buildSnapshotsFromState(state, quotas)
-      // Single clock for card body + keyboard so health classification
-      // can't disagree between the two (#2495 folded nit A).
-      const renderNow = new Date()
-      const text = renderAuthSnapshotFormat2(snapshots, {
-        tz,
-        now: renderNow,
-        demo: refreshDemo,
-        // Honesty backstop (same as /usage): a TOTAL probe failure (zero
-        // result rows, nothing served from cache) renders an explicit
-        // "probe failed" marker instead of a false "Live" footer next to
-        // no-data rows.
-        ...(staleCachedAtMs != null
-          ? { staleCachedAtMs }
-          : probeResp.results.length > 0
-            ? { liveProbedAtMs: renderNow.getTime() }
-            : { probeFailed: true }),
-      })
-      const kbRows = buildSnapshotKeyboard(snapshots, { now: renderNow, demo: refreshDemo })
-      const inline_keyboard = kbRows.map((row) =>
-        row.map((b) => {
-          if (b.callbackData) return { text: b.text, callback_data: b.callbackData }
-          if (b.insertText) return { text: b.text, switch_inline_query_current_chat: b.insertText }
-          return { text: b.text, callback_data: 'auth:noop' }
-        }),
-      )
-      const msg = ctx.callbackQuery?.message
-      if (msg) {
-        await swallowingApiCall(
-          () =>
-            bot.api.editMessageText(msg.chat.id, msg.message_id, richMessage(text), {
-              reply_markup: { inline_keyboard },
-            }),
-          { chat_id: String(msg.chat.id), verb: 'auth:refresh:edit' },
-        )
-      }
-      try { await ctx.answerCallbackQuery({ text: 'Refreshed.', show_alert: false }) } catch { /* */ }
-    } catch (err) {
-      const msg = (err as Error)?.message ?? String(err)
-      try {
-        await ctx.answerCallbackQuery({
-          text: `Refresh failed: ${msg.slice(0, 180)}`,
-          show_alert: true,
-        })
-      } catch { /* */ }
-    }
-    return
-  }
-
-  // Unknown auth:* — likely from a too-old message. Dismiss with a
-  // hint pointing at the canonical re-render verb.
-  try {
-    await ctx.answerCallbackQuery({
-      text: 'Unknown auth button. Send /auth for current state.',
-      show_alert: false,
-    })
-  } catch { /* */ }
-}
-
-// /reauth was removed in v0.6.13 — the `/auth` dashboard's
-// `🔄 Reauth default` button fires the same flow (the `case 'reauth':`
-// callback dispatch calls `runSwitchroomAuthCommand` and seeds
-// `pendingReauthFlows`). The OAuth code paste-back is caught by the
-// generic message intercept that watches `pendingReauthFlows` —
-// pasting the code into chat now Just Works without a typed entry
-// point. Removed surfaces in this PR:
-//   - bot.command('reauth', ...)              → use /auth → 🔄 Reauth
-//   - /reauth <code|url>  paste-back          → paste into chat
-//   - /reauth <other-agent> targeting         → use that agent's /auth
-
-bot.command('vault', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  const chatId = String(ctx.chat!.id)
-  const args = (typeof ctx.match === "string" ? ctx.match : "").trim().split(/\s+/).filter(Boolean)
-  const sub = args[0]?.toLowerCase()
-  const key = args[1]
-  if (!sub || sub === 'help') {
-    await switchroomReply(ctx, [
-      '**Vault commands**',
-      '/vault list — list all secret keys',
-      '/vault get <key> — read a secret value',
-      '/vault set <key> — set a secret',
-      '/vault delete <key> — remove a secret',
-      '/vault status — show broker state',
-      '/vault unlock — unlock the broker (prompts for passphrase)',
-      '/vault lock — lock the broker',
-      '/vault grant — mint a capability token (inline wizard)',
-      '/vault grants [agent] — list active capability grants (tap to revoke)',
-      '/vault audit <agent> — unified view of an agent\'s vault access',
-      '',
-      'Your passphrase is cached in memory for 30 min after first use.',
-    ].join('\n'), { html: true })
+bot.command('vault', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  const chatId = String(ctx.chat!.id)
+  const args = (typeof ctx.match === "string" ? ctx.match : "").trim().split(/\s+/).filter(Boolean)
+  const sub = args[0]?.toLowerCase()
+  const key = args[1]
+  if (!sub || sub === 'help') {
+    await switchroomReply(ctx, [
+      '**Vault commands**',
+      '/vault list — list all secret keys',
+      '/vault get <key> — read a secret value',
+      '/vault set <key> — set a secret',
+      '/vault delete <key> — remove a secret',
+      '/vault status — show broker state',
+      '/vault unlock — unlock the broker (prompts for passphrase)',
+      '/vault lock — lock the broker',
+      '/vault grant — mint a capability token (inline wizard)',
+      '/vault grants [agent] — list active capability grants (tap to revoke)',
+      '/vault audit <agent> — unified view of an agent\'s vault access',
+      '',
+      'Your passphrase is cached in memory for 30 min after first use.',
+    ].join('\n'), { html: true })
     return
   }
 
@@ -24887,150 +22657,27 @@ async function renderFleetDoctor(ctx: Context): Promise<void> {
   await switchroomReply(ctx, formatDoctorReport(body), { html: true })
 }
 
-bot.command('doctor', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  try {
-    // Admin agents with hostd reachable choose scope (one tap, no
-    // approval card — doctor is read-only). Everyone else keeps the
-    // original zero-extra-tap in-container behaviour.
-    if (AGENT_ADMIN && hostdWillBeUsed(getMyAgentName())) {
-      await switchroomReply(ctx, '🩺 **Doctor** — which scope?', {
-        html: true,
-        reply_markup: buildDoctorScopeKeyboard(),
-      })
-      return
-    }
-    await renderSelfDoctor(ctx)
-  } catch (err: unknown) {
-    await switchroomReply(ctx, `**doctor failed:**\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
-  }
-})
-
-bot.command('grant', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  const parts = getCommandArgs(ctx).split(/\s+/).filter(Boolean)
-  if (parts.length === 0) { await switchroomReply(ctx, 'Usage: /grant <tool>  or  /grant <agent> <tool>'); return }
-  let agentName: string; let tool: string
-  if (parts.length === 1) { agentName = getMyAgentName(); tool = parts[0] }
-  else { agentName = parts[0]; tool = parts.slice(1).join(' ') }
-  try { assertSafeAgentName(agentName) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
-  await runSwitchroomCommand(ctx, ['agent', 'grant', agentName, tool], `grant ${agentName} ${tool}`)
-})
-
-bot.command('dangerous', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  const parts = getCommandArgs(ctx).split(/\s+/).filter(Boolean)
-  let agentName: string; let off = false
-  if (parts.length === 0) { agentName = getMyAgentName() }
-  else if (parts.length === 1 && parts[0] === 'off') { agentName = getMyAgentName(); off = true }
-  else { agentName = parts[0]; if (parts[1] === 'off') off = true }
-  try { assertSafeAgentName(agentName) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
-  const args = ['agent', 'dangerous', agentName]; if (off) args.push('--off')
-  await runSwitchroomCommand(ctx, args, `dangerous ${agentName}${off ? ' off' : ''}`)
-})
-
-bot.command('permissions', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  const agentName = (typeof ctx.match === "string" ? ctx.match : "").trim() || getMyAgentName()
-  try { assertSafeAgentName(agentName) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
-  await runSwitchroomCommand(ctx, ['agent', 'permissions', agentName], `permissions ${agentName}`)
-})
-
-// Drive-by cleanup (#927): the dead /update handler that lived here
-// was a pre-#919 stub. Grammy registers in order so the comprehensive
-// /update handler at line ~6516 (added in #919, hardened in #924,
-// docker-guarded in #934) fired first and this one never ran.
-// Removed to avoid future confusion.
-
-bot.command('version', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  try {
-    let output: string
-    try { output = switchroomExecCombined(['version'], 10000) }
-    catch (err: unknown) { output = (err as any).stdout ?? (err as any).message ?? 'version failed' }
-    const trimmed = stripAnsi(output).trim()
-    if (!trimmed) { await switchroomReply(ctx, 'version: no output'); return }
-    await switchroomReply(ctx, preBlock(formatSwitchroomOutput(trimmed)), { html: true })
-  } catch (err: unknown) {
-    await switchroomReply(ctx, `**version failed:**\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
-  }
-})
-
-
-// /whoami — the operator's view of THIS agent's sandbox (the same
-// `config whoami` the agent itself can call as an MCP tool, and the host CLI
-// exposes). Read-only, isAuthorizedSender-gated like /version — surfaces
-// tools / MCP / vault key-NAMES (never values) / powers so the operator can
-// see at a glance what this agent is authorized for.
-bot.command('whoami', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  const demo = hasDemoFlag(getCommandArgs(ctx))
-  try {
-    let raw: string
-    try { raw = switchroomExecCombined(['config', 'whoami'], 10000) }
-    catch (err: unknown) { raw = (err as any).stdout ?? (err as any).message ?? 'whoami failed' }
-    const trimmed = stripAnsi(raw).trim()
-    let card: string
-    try { card = formatWhoamiCard(JSON.parse(trimmed.split('\n').pop() ?? trimmed), demo) }
-    catch { card = preBlock(formatSwitchroomOutput(trimmed || 'whoami: no output')) }
-    await switchroomReply(ctx, card, { html: true })
-  } catch (err: unknown) {
-    await switchroomReply(ctx, `**whoami failed:**\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
-  }
-})
-
-/** Compact HTML card from the `config whoami` JSON view. Names/booleans only.
- *  `demo` (the `/whoami demo` suffix) masks the vault key NAMES via maskVaultKey
- *  for screen recordings — agent/MCP/model/skills topology is left untouched
- *  (out of scope). Off by default. */
-function formatWhoamiCard(v: {
-  name?: string; persona?: string | null; model?: string | null; tier?: string;
-  tools?: { allow?: string[]; deny?: string[] }; mcpServers?: string[]; skills?: string[];
-  vault?: { key: string; readable: boolean }[];
-  powers?: { admin?: boolean; root?: boolean; configEdit?: boolean; crossAgentHostVerbs?: boolean };
-  scheduleCount?: number; memoryBackend?: string | null;
-}, demo = false): string {
-  const esc = escapeHtmlForTg
-  const yn = (b?: boolean) => (b ? '✓' : '✗')
-  const lines: string[] = []
-  lines.push(`👤 **${esc(v.name ?? '?')}** · ${esc(v.tier ?? 'standard')}`)
-  if (v.persona) lines.push(esc(v.persona))
-  if (v.model) lines.push(`Model: ${esc(v.model)}`)
-  const allow = v.tools?.allow ?? []
-  lines.push(`Tools: ${allow.length ? esc(allow.slice(0, 8).join(', ')) + (allow.length > 8 ? ` …(+${allow.length - 8})` : '') : '—'}`)
-  if ((v.tools?.deny ?? []).length) lines.push(`Denied: ${esc((v.tools!.deny!).join(', '))}`)
-  if ((v.mcpServers ?? []).length) lines.push(`MCP: ${esc(v.mcpServers!.join(', '))}`)
-  if ((v.skills ?? []).length) lines.push(`Skills: ${esc(v.skills!.join(', '))}`)
-  if ((v.vault ?? []).length) {
-    lines.push(`Vault keys (names only): ${v.vault!.map(k => `${esc(demo ? maskVaultKey(k.key) : k.key)} ${yn(k.readable)}`).join(', ')}`)
-  }
-  const p = v.powers ?? {}
-  lines.push(`Powers: admin ${yn(p.admin)} · root ${yn(p.root)} · config-edit ${yn(p.configEdit)} · cross-agent verbs ${yn(p.crossAgentHostVerbs)}`)
-  lines.push(`Schedule: ${v.scheduleCount ?? 0} cron · Memory: ${esc(v.memoryBackend ?? 'none')}`)
-  return lines.join('\n')
-}
-
-bot.command('commands', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  await switchroomReply(ctx, buildSwitchroomHelpText(getMyAgentName()), { html: true })
+// Ops/info slash commands (/doctor /grant /dangerous /permissions /version
+// /whoami /commands) extracted verbatim to bot-commands-ops-info.ts (#2996
+// Phase 5). Registered here to preserve grammy's in-order registration.
+registerOpsInfoCommands(bot, {
+  AGENT_ADMIN,
+  isAuthorizedSender,
+  getMyAgentName,
+  switchroomReply,
+  buildDoctorScopeKeyboard,
+  renderSelfDoctor,
+  preBlock,
+  formatSwitchroomOutput,
+  getCommandArgs,
+  assertSafeAgentName,
+  runSwitchroomCommand,
+  switchroomExecCombined,
+  stripAnsi,
+  hasDemoFlag,
+  escapeHtmlForTg,
 })
 
-async function registerSwitchroomBotCommands(): Promise<void> {
-  // Slash-menu is deliberately trimmed from the full command catalogue.
-  // See telegram-plugin/welcome-text.ts TELEGRAM_MENU_COMMANDS for the
-  // rationale (mobile UX focus; ops primitives stay typable but out of
-  // the autocomplete clutter). /commands surfaces the full list.
-  await bot.api.setMyCommands(
-    [...TELEGRAM_BASE_COMMANDS, ...TELEGRAM_SWITCHROOM_COMMANDS],
-    { scope: { type: 'all_private_chats' } },
-  )
-  // Group chats don't support /start pairing, so only the switchroom
-  // commands are registered there.
-  await bot.api.setMyCommands(
-    TELEGRAM_SWITCHROOM_COMMANDS,
-    { scope: { type: 'all_group_chats' } },
-  )
-}
 
 // ─── Inline-button handler (permissions) ──────────────────────────────────
 // Handles `perm:(allow|deny|always|asn|asb|back):<id>` — permission request buttons
@@ -27991,7 +25638,7 @@ void (async () => {
         // lifetime.
         scheduleAlwaysAllowPersistDrain()
 
-        void registerSwitchroomBotCommands().catch(() => {})
+        void registerSwitchroomBotCommands(bot).catch(() => {})
 
         // #613 fix: pre-warm the chatAvailableReactions cache for every
         // chat in access.allowFrom. Without this, the FIRST inbound