switchroom 0.17.6 → 0.18.3

package/telegram-plugin/gateway/missed-approvals-card.ts

@@ -0,0 +1,161 @@
+/**
+ * Missed-approvals re-offer digest card (#2862).
+ *
+ * Pure builders — card text, inline keyboard, callback shape, and the
+ * synthetic inbound the gateway injects on Retry — kept out of gateway.ts so
+ * they're pinned by tests independent of the bot plumbing (mirrors
+ * `skill-proposal-card.ts`).
+ *
+ * The digest lists the approvals that TTL-expired while the operator was away
+ * and offers two taps:
+ *   • Ask agent to retry → inject a synthetic inbound asking the live agent to
+ *     re-attempt the actions. This rides the SAME `inject_inbound` /
+ *     synthesized-inbound path cron uses (claude-native): the agent starts a
+ *     fresh turn and naturally re-raises a new approval card. It is a QUESTION
+ *     to the agent — never a re-execution, never a synthesized verdict
+ *     (no-self-escalation intact).
+ *   • Dismiss → clear the list and edit the card closed.
+ *
+ * callback_data shape (fits Telegram's 64-byte limit):
+ *   missre:retry:<digestId>
+ *   missre:dismiss:<digestId>
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+import type { MissedApproval } from './missed-approvals-store.js'
+
+export const MISSED_APPROVAL_CALLBACK_PREFIX = 'missre:'
+/** How many entries to list in the card before collapsing to "…and N more". */
+export const MISSED_APPROVAL_RENDER_CAP = 10
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/** Compact HH:MM (UTC) stamp for a miss. */
+function fmtTime(ms: number): string {
+  const d = new Date(ms)
+  const hh = String(d.getUTCHours()).padStart(2, '0')
+  const mm = String(d.getUTCMinutes()).padStart(2, '0')
+  return `${hh}:${mm}`
+}
+
+/**
+ * Render the digest card text (HTML parse mode). Lists up to
+ * `cap` entries, then a "…and N more" overflow line.
+ */
+export function renderMissedApprovalsDigest(
+  entries: MissedApproval[],
+  opts?: { cap?: number; agentName?: string | null },
+): string {
+  const cap = opts?.cap ?? MISSED_APPROVAL_RENDER_CAP
+  const who = opts?.agentName ? escapeHtml(opts.agentName) : 'the agent'
+  const shown = entries.slice(0, cap)
+  const overflow = entries.length - shown.length
+
+  const lines: string[] = []
+  lines.push('⏳ <b>Missed approvals while you were away</b>')
+  lines.push('')
+  lines.push('These approval requests timed out before you could respond:')
+  for (const e of shown) {
+    lines.push(`• ${escapeHtml(e.action)} <i>(${fmtTime(e.timedOutAt)} UTC)</i>`)
+  }
+  if (overflow > 0) {
+    lines.push(`…and ${overflow} more`)
+  }
+  lines.push('')
+  lines.push(
+    `<i>Tap “Ask agent to retry” to have ${who} re-attempt them — you’ll be ` +
+      'asked to approve again as normal. Dismiss to clear.</i>',
+  )
+  return lines.join('\n')
+}
+
+/** Inline keyboard for the digest card. */
+export function missedApprovalsKeyboard(digestId: string): {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>
+} {
+  return {
+    inline_keyboard: [
+      [
+        {
+          text: '🔁 Ask agent to retry',
+          callback_data: `${MISSED_APPROVAL_CALLBACK_PREFIX}retry:${digestId}`,
+        },
+        {
+          text: '🚫 Dismiss',
+          callback_data: `${MISSED_APPROVAL_CALLBACK_PREFIX}dismiss:${digestId}`,
+        },
+      ],
+    ],
+  }
+}
+
+/** Parse a `missre:` callback into { action, digestId }, or null if not ours. */
+export function parseMissedApprovalCallback(
+  data: string,
+): { action: 'retry' | 'dismiss'; digestId: string } | null {
+  if (!data.startsWith(MISSED_APPROVAL_CALLBACK_PREFIX)) return null
+  const rest = data.slice(MISSED_APPROVAL_CALLBACK_PREFIX.length)
+  const idx = rest.indexOf(':')
+  if (idx < 0) return null
+  const action = rest.slice(0, idx)
+  const digestId = rest.slice(idx + 1)
+  if ((action !== 'retry' && action !== 'dismiss') || digestId.length === 0) return null
+  return { action, digestId }
+}
+
+export interface MissedApprovalInboundContext {
+  agent: string
+  chat_id: string
+  threadId?: number
+}
+
+/**
+ * Build the synthetic inbound injected when the operator taps "Ask agent to
+ * retry". It ASKS the agent to re-attempt the listed actions — it never
+ * re-executes them and never carries a verdict (no-self-escalation). The
+ * agent starts a fresh turn and naturally re-raises approval cards.
+ *
+ * `meta.source = "missed_approval_retry"` so the bridge renders it as
+ * `<channel source="missed_approval_retry">`.
+ */
+export function buildMissedApprovalRetryInbound(opts: {
+  ctx: MissedApprovalInboundContext
+  actions: string[]
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const list =
+    opts.actions.length === 1
+      ? opts.actions[0]
+      : opts.actions.map(a => `\n• ${a}`).join('')
+  const body =
+    opts.actions.length === 1
+      ? `Please re-attempt it now: ${list}.`
+      : `Please re-attempt them now:${list}`
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts,
+    user: 'missed-approvals',
+    userId: 0,
+    ts,
+    text:
+      `🔁 Operator asked you to retry ${opts.actions.length === 1 ? 'an action' : 'some actions'} ` +
+      `that timed out earlier while they were away. ${body} You'll be asked to ` +
+      `approve again as normal — do not assume the earlier timeout was a denial.`,
+    meta: {
+      source: 'missed_approval_retry',
+      agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
+      operator_id: opts.operatorId,
+      action_count: String(opts.actions.length),
+    },
+  }
+}

package/telegram-plugin/gateway/missed-approvals-store.ts

@@ -0,0 +1,167 @@
+/**
+ * Persistence store for approvals that TTL-expired while the operator was
+ * away (#2862, "approval cards don't stick — re-offer digest").
+ *
+ * Problem: when a permission card auto-denies on TTL (the #2411 timeout path)
+ * with the operator absent, the gated work is silently dropped and NOTHING
+ * re-offers it when the operator returns. For cron-fired work (marko's brevo
+ * nurture-drip batches) the batch just doesn't go out and the operator finds
+ * out a day later.
+ *
+ * Fix: at TTL auto-deny the gateway appends the missed request to this store
+ * (persisted so a gateway restart — which happens ~14× on a fleet-roll day —
+ * doesn't lose the digest). On the FIRST operator-activity event afterwards,
+ * the gateway posts ONE compact digest card ("While you were away these
+ * approvals timed out: …  [Ask agent to retry] [Dismiss]") to the origin
+ * surface, then promotes the pending entries into a delivered-digest record
+ * (the posted card is now the durable record in chat). Retry synthesizes an
+ * inbound asking the agent to re-attempt the actions; Dismiss clears the
+ * record and edits the card closed.
+ *
+ * File format: a single JSON object `{ pending, delivered }`, written
+ * synchronously to avoid interleaving on concurrent auto-denies, mode 0o600.
+ * Mirrors the `permission-card-store.ts` pattern. Both lists are hard-capped
+ * so the file stays tiny under a runaway loop.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface MissedApproval {
+  /** The permission request_id that timed out (dedup key). */
+  requestId: string
+  /** Raw claude tool name, e.g. `mcp__brevo__post`. */
+  toolName: string
+  /** Natural-language action (from `naturalAction()`), e.g. "post to Brevo". */
+  action: string
+  /** Origin surface the card was posted to. */
+  chatId: string
+  threadId?: number | null
+  /** When the TTL auto-deny fired (epoch ms). */
+  timedOutAt: number
+}
+
+export interface DeliveredDigest {
+  /** Short id embedded in the card's callback_data (retry/dismiss routing). */
+  digestId: string
+  /** Origin surface the digest card was posted to. */
+  chatId: string
+  threadId?: number | null
+  /** The missed entries this digest covers (for the Retry synthesis). */
+  entries: MissedApproval[]
+  deliveredAt: number
+}
+
+interface FileShape {
+  pending: MissedApproval[]
+  delivered: DeliveredDigest[]
+}
+
+export interface MissedApprovalsStore {
+  /** Record a newly-missed approval. Idempotent on requestId. */
+  add(entry: MissedApproval): void
+  /** Undelivered misses, oldest first. */
+  listPending(): MissedApproval[]
+  pendingCount(): number
+  /**
+   * Move a set of pending entries into a delivered-digest record. The entries
+   * carried on `digest` are removed from `pending` (matched by requestId).
+   */
+  promoteToDigest(digest: DeliveredDigest): void
+  /** Look up a delivered digest by its id (for a retry/dismiss tap). */
+  getDigest(digestId: string): DeliveredDigest | undefined
+  /** Drop a delivered digest (retry consumed it, or dismiss cleared it). */
+  removeDigest(digestId: string): void
+  /** Delete the backing file entirely. */
+  clear(): void
+}
+
+/** Bound the on-disk file even under a runaway auto-deny loop. */
+export const MAX_PENDING = 50
+export const MAX_DELIVERED = 20
+
+export function createMissedApprovalsStore(stateDir: string): MissedApprovalsStore {
+  const filePath = join(stateDir, 'missed-approvals.json')
+
+  function read(): FileShape {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw) as Partial<FileShape>
+      return {
+        pending: Array.isArray(parsed?.pending) ? parsed.pending : [],
+        delivered: Array.isArray(parsed?.delivered) ? parsed.delivered : [],
+      }
+    } catch {
+      return { pending: [], delivered: [] }
+    }
+  }
+
+  function write(f: FileShape): void {
+    try {
+      writeFileSync(filePath, JSON.stringify(f), { encoding: 'utf-8', mode: 0o600 })
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: missed-approvals-store write failed: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  return {
+    add(entry) {
+      const f = read()
+      const idx = f.pending.findIndex(e => e.requestId === entry.requestId)
+      if (idx >= 0) {
+        f.pending[idx] = entry
+      } else {
+        f.pending.push(entry)
+      }
+      // Keep only the most-recent MAX_PENDING (drop oldest by insertion order).
+      if (f.pending.length > MAX_PENDING) {
+        f.pending = f.pending.slice(f.pending.length - MAX_PENDING)
+      }
+      write(f)
+    },
+
+    listPending() {
+      return read().pending
+    },
+
+    pendingCount() {
+      return read().pending.length
+    },
+
+    promoteToDigest(digest) {
+      const f = read()
+      const ids = new Set(digest.entries.map(e => e.requestId))
+      f.pending = f.pending.filter(e => !ids.has(e.requestId))
+      // Replace any existing record with the same id, then append.
+      f.delivered = f.delivered.filter(d => d.digestId !== digest.digestId)
+      f.delivered.push(digest)
+      if (f.delivered.length > MAX_DELIVERED) {
+        f.delivered = f.delivered.slice(f.delivered.length - MAX_DELIVERED)
+      }
+      write(f)
+    },
+
+    getDigest(digestId) {
+      return read().delivered.find(d => d.digestId === digestId)
+    },
+
+    removeDigest(digestId) {
+      const f = read()
+      const filtered = f.delivered.filter(d => d.digestId !== digestId)
+      if (filtered.length !== f.delivered.length) {
+        f.delivered = filtered
+        write(f)
+      }
+    },
+
+    clear() {
+      try {
+        unlinkSync(filePath)
+      } catch {
+        // File may not exist — fine.
+      }
+    },
+  }
+}

package/telegram-plugin/gateway/model-command.ts

@@ -52,11 +52,14 @@ export const MODEL_ALIASES = ['opus', 'sonnet', 'haiku', 'fable', 'default'] as
  * Shape gate for the model argument. This string is typed literally
  * into the agent's tmux pane, so the gate is strict by construction:
  * one token, alphanumeric start, then alphanumerics plus the chars
- * that appear in real model ids (`.` `_` `-` and the `[1m]`-style
- * variant brackets). No whitespace means no second token can ride
+ * that appear in real model ids (`.` `_` `-` `/` and the `[1m]`-style
+ * variant brackets). `/` is allowed for OpenRouter-style
+ * `sr-vendor/model` ids; it is not a shell metachar inside the
+ * double-quoted `claude --model "$_EFFECTIVE_MODEL"` usage, so it can't
+ * break the launch. No whitespace means no second token can ride
  * along; no control characters means no newline/Enter smuggling.
  */
-const MODEL_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._\[\]-]{0,99}$/
+const MODEL_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._/\[\]-]{0,99}$/
 
 export function isValidModelArg(arg: string): boolean {
   return MODEL_ARG_RE.test(arg)
@@ -133,6 +136,18 @@ export interface ModelCommandDeps {
    * mechanism as the `/restart` command (hostd-first, SIGTERM fallback).
    */
   scheduleRestart: (reason: string) => Promise<void>
+  /**
+   * Schedule a session-only switch TO a non-Claude (`sr-*` LiteLLM/OpenRouter)
+   * model. claude's in-REPL `/model` picker rejects unknown `sr-*` ids, so an
+   * inject can't set them. Instead the gateway writes the chosen token to the
+   * `.session-model-override` carrier file and gracefully restarts the agent;
+   * the next boot launches `claude --model <token>` directly (LiteLLM routes
+   * it, no picker validation). Session-only: reverts to the configured default
+   * on the following restart. Wired to the same restart dispatch as
+   * `scheduleRestart`, plus the carrier write. `model` is the full `sr-*` id
+   * (already alias-expanded); `reason` is stamped as the restart reason.
+   */
+  scheduleModelRelaunch: (model: string, reason: string) => Promise<void>
 }
 
 export interface ModelCommandReply {
@@ -152,6 +167,7 @@ function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
     '\`/model\` — show the configured model',
     `\`/model <name>\` — switch the live session (${MODEL_ALIASES.map(a => `\`${a}\``).join(' · ')} or a full model id)`,
     `_OpenRouter shortcuts:_ ${srAliasExamples}`,
+    '_OpenRouter (sr-\\*) switches restart the session (~30s); Claude switches apply instantly._',
     PERSIST_NOTE,
   )
   return { text: lines.join('\n'), html: true }
@@ -214,6 +230,30 @@ export async function handleModelCommand(
     }
   }
 
+  // Claude → sr-*: an in-place inject can't set a non-Anthropic model — claude's
+  // native `/model` picker rejects the unknown `sr-*` id ("Model not found").
+  // Carry the token across a graceful restart and relaunch `claude --model
+  // sr-*` directly (LiteLLM routes it). Session-only: reverts to the configured
+  // default on the next restart. The sr-* → Claude direction is handled above.
+  if (isSrModel(model)) {
+    try {
+      await deps.scheduleModelRelaunch(model, `user: /model ${model} (session-only relaunch)`)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      return {
+        text: `❌ Could not schedule model switch: ${deps.escapeHtml(msg)}`,
+        html: true,
+      }
+    }
+    return {
+      text: [
+        `Switching to \`${deps.escapeHtml(model)}\` — restarting session (~30s).`,
+        '_Session-only — reverts to the configured default on the next restart._',
+      ].join('\n'),
+      html: true,
+    }
+  }
+
   const verbHtml = `\`/model ${deps.escapeHtml(model)}\``
   let result: InjectResult
   try {
@@ -358,16 +398,31 @@ export const EXTRA_CLAUDE_ALIASES: ReadonlyArray<{ alias: string; label: string
  * Friendly display names for sr-* synthetic model names. An sr-* model in
  * LiteLLM has no entry in `model_group_settings.*.forward_client_headers_to_llm_api`
  * so the Anthropic OAuth credential is NEVER forwarded — safe to route to
- * OpenRouter. Names here are display-only; the raw `sr-*` id is what gets
- * injected into the agent's session. See reference/rfcs/litellm-max-subscription-invariants.md § I6.
+ * OpenRouter. Names here are display-only (used by srFriendlyLabel for /status
+ * and switch confirmations); the raw `sr-*` id is what gets injected into the
+ * agent's session. This table is a SUPERSET of the menu-reachable set
+ * (SR_MODEL_ALIASES): it also labels models that are only reachable by typing
+ * the full `/model sr-<name>` (manual passthrough), so those still get a
+ * friendly name without appearing as a keyboard button.
+ * See reference/rfcs/litellm-max-subscription-invariants.md § I6.
  */
 export const SR_MODEL_LABELS: Record<string, string> = {
   'sr-gemini-2.5-pro': 'Gemini 2.5 Pro',
   'sr-gemini-2.5-flash': 'Gemini 2.5 Flash',
   'sr-deepseek-r1': 'DeepSeek R1',
   'sr-deepseek-v3': 'DeepSeek V3',
-  'sr-glm-5': 'GLM-5',
+  // sr-glm-5 now targets glm-5.2 in the live litellm config — label bumped to match.
+  'sr-glm-5': 'GLM-5.2',
   'sr-codex-5.5': 'Codex 5.5',
+  // OpenRouter coverage (pairs with the live litellm sr-* model_name additions).
+  'sr-gpt-oss-20b': 'GPT-OSS 20B',
+  'sr-gpt-oss-120b': 'GPT-OSS 120B',
+  'sr-gpt-5.5': 'GPT-5.5',
+  'sr-gpt-5-codex': 'GPT-5 Codex',
+  'sr-gpt-5.2-codex': 'GPT-5.2 Codex',
+  'sr-gemini-flash-lite': 'Gemini 3.1 Flash Lite',
+  'sr-minimax-m3': 'MiniMax M3',
+  'sr-deepseek-v4-flash': 'DeepSeek V4 Flash',
 }
 
 /**
@@ -448,10 +503,15 @@ function headerRow(label: string): ModelMenuKeyboardButton[] {
  * requires ANTHROPIC_CUSTOM_HEADERS (a litellm key) to be set on the gateway
  * process. switchroom never sets that env on the gateway, so in production
  * discoverSrModels() always returns [] and the external group was silently
- * empty. The six SR_MODEL_ALIASES targets are the sr-* names the litellm
- * config actually exposes, so seeding from them makes the group reliable
- * without the missing env — while still merging any live results on hosts
- * that do configure discovery.
+ * empty. The six SR_MODEL_ALIASES targets are the CURATED main sr-* set, so
+ * seeding from them makes the group reliable without the missing env — while
+ * still merging any live results on hosts that do configure discovery.
+ *
+ * Deliberately a SUBSET: the litellm config exposes more sr-* models than this
+ * (the full OpenRouter catalogue). Those extras are display-labelled in
+ * SR_MODEL_LABELS and remain typeable via `/model <full-sr-name>` (manual
+ * passthrough — the set path is a shape gate, no whitelist), but they are kept
+ * OUT of SR_MODEL_ALIASES on purpose so the keyboard stays small and curated.
  *
  * Subscription-honest: ONLY the curated sr-* aliases surface as buttons. Raw
  * gpt-4o / openrouter/* dupes / voyage-* embeddings never do.

package/telegram-plugin/gateway/permission-rearm.ts

@@ -0,0 +1,115 @@
+/**
+ * Pure decision helpers for permission-card re-arm across gateway restarts
+ * (#2861 / umbrella #2859).
+ *
+ * gateway.ts has top-level side effects and can't be unit-imported, so the
+ * discriminable logic lives here where it can be tested in isolation. The
+ * gateway wires these into `onPermissionRequest` and the boot-sweep.
+ *
+ * The mechanism, end to end:
+ *
+ *  1. The bridge keeps an outstanding-request ledger and re-sends every
+ *     unresolved `permission_request` to the gateway on each IPC (re)connect
+ *     (see `bridge/permission-ledger.ts`). So the gateway MUST treat repeat
+ *     `permission_request`s for the same request_id as idempotent.
+ *
+ *  2. `classifyPermissionRequest` decides what a `permission_request` is:
+ *       - `duplicate` — already live in `pendingPermissions` → ignore (no
+ *         second card). The bridge re-sends on every reconnect.
+ *       - `rearm` — not in memory, but the persisted card store still has
+ *         entries for it → a gateway restart orphaned it. Restore the
+ *         pending entry with the ORIGINAL `startedAt` (the TTL clock keeps
+ *         running from the original ask; an already-expired re-arm falls
+ *         straight into the existing TTL auto-deny sweep, which correctly
+ *         unwedges claude) and re-attach the keyboard on the EXISTING
+ *         message(s) via editMessageText — never a new card.
+ *       - `fresh` — a brand-new ask; post a card as usual.
+ *
+ *  3. The boot-sweep becomes a grace-period strip. At boot, instead of
+ *     stripping persisted cards immediately, wait ~90 s, then strip only the
+ *     cards whose request_id is NOT currently live in `pendingPermissions`.
+ *     A live entry means either a bridge re-send re-armed the card, OR a fresh
+ *     approval was posted during the window — both are legitimately-pending
+ *     asks. Only a genuinely dead session's card (container recreate → new
+ *     bridge, empty ledger, never re-sends → no live entry) gets today's
+ *     "Gateway restarted" strip.
+ *
+ * NEVER auto-allows anything: re-arm restores only the QUESTION, never a
+ * verdict (no-self-escalation invariant). No model callsite is involved —
+ * verdicts still travel only over the existing IPC/MCP channel.
+ */
+
+import type { PersistedPermCard } from './permission-card-store.js'
+
+/** Default grace window before the boot-sweep strips an un-re-claimed card. */
+export const PERMISSION_REARM_GRACE_MS = 90_000
+
+/**
+ * Kill switch. `SWITCHROOM_PERMISSION_REARM=0` reverts to the legacy
+ * immediate-strip (gateway) / drop-when-disconnected (bridge) behavior.
+ */
+export function isPermissionRearmEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return env.SWITCHROOM_PERMISSION_REARM !== '0'
+}
+
+/**
+ * Resolve the boot-sweep grace window (ms). `SWITCHROOM_PERMISSION_REARM_GRACE_MS`
+ * overrides the default (used by tests to collapse the wait). A non-finite or
+ * negative override falls back to the default.
+ */
+export function permissionRearmGraceMs(
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  const raw = env.SWITCHROOM_PERMISSION_REARM_GRACE_MS
+  if (raw == null || raw === '') return PERMISSION_REARM_GRACE_MS
+  const n = Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : PERMISSION_REARM_GRACE_MS
+}
+
+export type PermissionRequestDisposition = 'duplicate' | 'rearm' | 'fresh'
+
+/**
+ * Classify an incoming `permission_request` (pure).
+ *
+ * @param hasPending    is the request_id already live in `pendingPermissions`?
+ * @param persistedCount how many persisted card entries exist for this request_id?
+ */
+export function classifyPermissionRequest(opts: {
+  hasPending: boolean
+  persistedCount: number
+}): PermissionRequestDisposition {
+  if (opts.hasPending) return 'duplicate'
+  if (opts.persistedCount > 0) return 'rearm'
+  return 'fresh'
+}
+
+/**
+ * Which persisted cards should the boot-sweep strip at the grace deadline?
+ * Everything whose request_id is NOT currently live.
+ *
+ * `liveRequestIds` is the set of request_ids present in `pendingPermissions`
+ * at the deadline — which covers BOTH:
+ *   - re-armed cards (a bridge re-send restored the pending entry), and
+ *   - fresh cards born during the grace window (a new approval posted after
+ *     boot sets a pending entry the normal way).
+ * Both are legitimately-pending asks a claude session is still suspended on;
+ * stripping either would re-wedge the turn. Only a genuinely dead session's
+ * card — persisted but with no live pending entry (the bridge never
+ * reconnected to re-arm it) — is stripped. Keying on liveness rather than a
+ * "was re-claimed" flag is what makes fresh-during-grace cards safe.
+ */
+export function computeBootSweepStripTargets(
+  stale: readonly PersistedPermCard[],
+  liveRequestIds: ReadonlySet<string>,
+): PersistedPermCard[] {
+  return stale.filter(card => !liveRequestIds.has(card.requestId))
+}
+
+/** Distinct request_ids in a persisted-card list (for per-request store removal). */
+export function distinctRequestIds(
+  cards: readonly PersistedPermCard[],
+): string[] {
+  return [...new Set(cards.map(c => c.requestId))]
+}

package/telegram-plugin/gateway/scoped-grant-store.ts

@@ -0,0 +1,89 @@
+/**
+ * Persistence for the gateway's 30-min scoped-approval windows
+ * (`scopedGrants: ScopedGrantStore`, see ../scoped-approval.ts).
+ *
+ * Problem: the store is in-memory. Any gateway restart (fleet roll, config
+ * apply, failover probe — marko saw ~14 boots on 2026-07-05) wipes it, so an
+ * action the operator allowed with a 30-min scope minutes ago re-cards
+ * immediately. It reads as "my approval didn't stick."
+ *
+ * Fix: mirror the store to a tiny JSON file in STATE_DIR (same shape as
+ * permission-card-store.ts — synchronous writes, mode 0o600, one small file).
+ * Write-through on every grant and on sweep-expiry removal; reload at boot,
+ * dropping entries already past their ABSOLUTE expiry.
+ *
+ * This only widens WHEN a still-valid window survives a restart — never WHAT
+ * qualifies. Expiry is absolute wall-clock, captured at the original tap, so a
+ * restart can never extend a window. All fail-closed semantics
+ * (destructive-Bash never scoped, expiry lookup fails closed) live in
+ * scoped-approval.ts and are untouched — a reloaded grant runs the identical
+ * `lookupScopedGrant` gate as an in-memory one.
+ *
+ * Kill switch: SWITCHROOM_SCOPED_GRANT_PERSIST=0 → boot with an empty store
+ * and never write (any pre-existing file is ignored).
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  serializeScopedGrants,
+  deserializeScopedGrants,
+  type ScopedGrantStore,
+} from '../scoped-approval.js'
+
+export interface ScopedGrantPersistence {
+  /** True unless the kill switch disabled persistence. */
+  readonly enabled: boolean
+  /** Load surviving grants (absolute expiry > now). Empty when disabled. */
+  load(now: number): ScopedGrantStore
+  /** Write-through the current store. No-op when disabled. */
+  save(store: ScopedGrantStore): void
+}
+
+/** Persistence is on unless SWITCHROOM_SCOPED_GRANT_PERSIST is exactly "0". */
+export function scopedGrantPersistEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  return env.SWITCHROOM_SCOPED_GRANT_PERSIST !== '0'
+}
+
+export function createScopedGrantStore(
+  stateDir: string,
+  env: Record<string, string | undefined> = process.env,
+): ScopedGrantPersistence {
+  const filePath = join(stateDir, 'scoped-grants.json')
+  const enabled = scopedGrantPersistEnabled(env)
+
+  function read(): unknown[] {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      return Array.isArray(parsed) ? parsed : []
+    } catch {
+      return []
+    }
+  }
+
+  return {
+    enabled,
+
+    load(now) {
+      if (!enabled) return new Map()
+      return deserializeScopedGrants(read(), now)
+    },
+
+    save(store) {
+      if (!enabled) return
+      try {
+        writeFileSync(filePath, JSON.stringify(serializeScopedGrants(store)), {
+          encoding: 'utf-8',
+          mode: 0o600,
+        })
+      } catch (err) {
+        process.stderr.write(
+          `telegram gateway: scoped-grant-store write failed: ${(err as Error).message}\n`,
+        )
+      }
+    },
+  }
+}