switchroom 0.16.29 → 0.16.46

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -142,7 +142,8 @@ export type GatewayToClient =
   | ScheduleRestartResult
   | DriveApprovalPostedEvent
   | Ms365ApprovalPostedEvent
-  | ConfigApprovalResolvedEvent;
+  | ConfigApprovalResolvedEvent
+  | RolloutStatusPostedEvent;
 
 // === Bridge (Client) -> Gateway messages ===
 
@@ -493,6 +494,67 @@ export interface PostSkillProposalMessage {
   draft: Record<string, string>;
 }
 
+/**
+ * #2726 Part 1 — hostd asks the caller agent's gateway to POST one ordinary
+ * operator-DM message narrating a rollout's terminal outcome. This is a NORMAL
+ * message, NOT a pinned card and NOT a bespoke widget — the framework speaking
+ * a plain progress line in the chat, which keeps it clear of
+ * `chat-is-the-single-source-of-truth` (in-chat narration, not a parallel
+ * pinned mirror).
+ *
+ * The gateway posts `text` to the operator chat (`allowFrom[0]`) and — for the
+ * Part 2 narration surface — replies with a `rollout_status_posted` event
+ * carrying the message_id so hostd can EDIT it as later phases arrive. Part 1
+ * uses only the terminal post and ignores the reply (fire-and-forget).
+ *
+ * Trust model: same as request_config_approval — the gateway socket lives in
+ * the agent container; hostd reaches it via the per-agent state-dir bind mount.
+ * `agentName` is validated server-side; the chat target is the gateway's OWN
+ * operator, never a caller-supplied chat.
+ */
+export interface RolloutStatusPostMessage {
+  type: "rollout_status_post";
+  /** hostd request_id of the roll (binds the surface to a real request). */
+  requestId: string;
+  /** The admin agent whose gateway relays the message (the rollout caller). */
+  agentName: string;
+  /** Fully-rendered message body. */
+  text: string;
+}
+
+/**
+ * #2726 Part 2 — hostd asks the gateway to EDIT the rollout status message it
+ * previously posted (identified by `messageId`, returned in the
+ * `rollout_status_posted` reply). Best-effort, fire-and-forget: an edit failure
+ * (incl. Telegram 429) is handled gateway-side and never surfaced back toward
+ * the roll.
+ */
+export interface RolloutStatusEditMessage {
+  type: "rollout_status_edit";
+  requestId: string;
+  agentName: string;
+  /** message_id of the status message to edit (from rollout_status_posted). */
+  messageId: number;
+  /** New fully-rendered body. */
+  text: string;
+}
+
+/**
+ * #2726 — gateway → hostd reply after a `rollout_status_post` was posted, so
+ * hostd learns the message_id to EDIT for subsequent phases. `ok:false` when
+ * the post failed (hostd then simply won't edit — the durable log + terminal
+ * push remain the record).
+ */
+export interface RolloutStatusPostedEvent {
+  type: "rollout_status_posted";
+  requestId: string;
+  ok: boolean;
+  /** Telegram message_id of the posted status message (present when ok). */
+  messageId?: number;
+  /** Diagnostic detail on failure. */
+  reason?: string;
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -510,4 +572,6 @@ export type ClientToGateway =
   | RequestConfigFinalizeMessage
   | QuotaWallDetectedMessage
   | SendOutboundMessage
-  | PostSkillProposalMessage;
+  | PostSkillProposalMessage
+  | RolloutStatusPostMessage
+  | RolloutStatusEditMessage;

package/telegram-plugin/gateway/ipc-server.ts

@@ -1,4 +1,4 @@
-import { renameSync, unlinkSync } from "fs";
+import { renameSync, unlinkSync, chmodSync } from "fs";
 import type {
   ClientToGateway,
   GatewayToClient,
@@ -15,6 +15,8 @@ import type {
   RequestConfigFinalizeMessage,
   RequestDriveApprovalMessage,
   RequestMs365ApprovalMessage,
+  RolloutStatusPostMessage,
+  RolloutStatusEditMessage,
   ScheduleRestartMessage,
   SessionEventForward,
   ToolCallMessage,
@@ -113,6 +115,25 @@ export interface IpcServerOptions {
     client: IpcClient,
     msg: RequestConfigFinalizeMessage,
   ) => Promise<void>;
+  /**
+   * #2726 Part 1 — hostd asks the gateway to POST one ordinary operator-DM
+   * message narrating a rollout's terminal outcome (Part 1) or its first phase
+   * (Part 2). Handler posts to the agent's own operator chat and — for Part 2 —
+   * replies with a `rollout_status_posted` event carrying the message_id.
+   * Optional: gateways without the hostd integration ignore it.
+   */
+  onRolloutStatusPost?: (
+    client: IpcClient,
+    msg: RolloutStatusPostMessage,
+  ) => Promise<void>;
+  /**
+   * #2726 Part 2 — hostd asks the gateway to EDIT a previously-posted rollout
+   * status message as later phases arrive. Best-effort, no reply. Optional.
+   */
+  onRolloutStatusEdit?: (
+    client: IpcClient,
+    msg: RolloutStatusEditMessage,
+  ) => void;
   log?: (msg: string) => void;
   /**
    * How long (in ms) to wait without a heartbeat before force-closing the
@@ -381,6 +402,33 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
           || (m.ttlMs as number) < 0)) return false;
       return true;
     }
+    case "rollout_status_post": {
+      // #2726 Part 1 — hostd-initiated terminal ping / status post. Wire shape
+      // only; the gateway handler fences the chat to the agent's own operator.
+      if (typeof m.requestId !== "string"
+        || (m.requestId as string).length === 0
+        || (m.requestId as string).length > 64) return false;
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.text !== "string"
+        || (m.text as string).length === 0
+        || (m.text as string).length > RICH_MESSAGE_MAX_CHARS) return false;
+      return true;
+    }
+    case "rollout_status_edit": {
+      // #2726 Part 2 — hostd-initiated status-message edit.
+      if (typeof m.requestId !== "string"
+        || (m.requestId as string).length === 0
+        || (m.requestId as string).length > 64) return false;
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.messageId !== "number"
+        || !Number.isInteger(m.messageId as number)) return false;
+      if (typeof m.text !== "string"
+        || (m.text as string).length === 0
+        || (m.text as string).length > RICH_MESSAGE_MAX_CHARS) return false;
+      return true;
+    }
     default:
       return false;
   }
@@ -406,6 +454,8 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onRequestMs365Approval,
     onRequestConfigApproval,
     onRequestConfigFinalize,
+    onRolloutStatusPost,
+    onRolloutStatusEdit,
     log = () => {},
     heartbeatTimeoutMs = 30_000,
   } = options;
@@ -637,6 +687,42 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
         }
         // No reply expected.
         break;
+      case "rollout_status_post":
+        if (onRolloutStatusPost) {
+          onRolloutStatusPost(client, msg as RolloutStatusPostMessage).catch(
+            (err) => {
+              log(
+                `rollout_status_post handler threw (client=${client.id}): ${(err as Error).message}`,
+              );
+              // Best-effort failure reply so hostd's Part 2 renderer knows the
+              // post failed (it just won't edit). Part 1 ignores the reply.
+              try {
+                client.send({
+                  type: "rollout_status_posted",
+                  requestId: (msg as RolloutStatusPostMessage).requestId,
+                  ok: false,
+                  reason: `gateway handler error: ${(err as Error).message}`,
+                });
+              } catch {
+                /* best effort */
+              }
+            },
+          );
+        }
+        // No reply required when unwired — hostd falls back to the durable log.
+        break;
+      case "rollout_status_edit":
+        if (onRolloutStatusEdit) {
+          try {
+            onRolloutStatusEdit(client, msg as RolloutStatusEditMessage);
+          } catch (err) {
+            log(
+              `rollout_status_edit handler threw (client=${client.id}): ${(err as Error).message}`,
+            );
+          }
+        }
+        // Fire-and-forget; no reply.
+        break;
       case "update_placeholder":
         // Legacy recall.py IPC — placeholder UX was removed in #553 PR 5.
         // Soft-accepted so recall.py keeps working without modifying
@@ -786,6 +872,10 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     },
   });
 
+  // Allow the web container (uid=1000, operator) to inject prompts via
+  // injectInbound without needing root — the socket is inside the per-agent
+  // state directory which is already operator-accessible.
+  try { chmodSync(socketPath, 0o666); } catch { /* best-effort */ }
   log(`listening on ${socketPath}`);
 
   // ─── Heartbeat watchdog (issue #71) ─────────────────────────────────────

package/telegram-plugin/gateway/linear-activity.ts

@@ -15,6 +15,7 @@
  * agent to `vault_request_access` for that key rather than failing opaquely.
  */
 
+import { escapeMarkdown } from '../format.js'
 import {
   getViaBrokerStructured,
   putViaBroker,
@@ -30,10 +31,6 @@ export type LinearAuthDeadReason = 'no_bundle' | 'revoked'
 /** Minimal GFM-markdown escape (#2669). Kept local so the message builder is
  *  self-contained + unit-testable without reaching into a gateway-only
  *  escaper (the bug that shipped the first cut of this alert). */
-function escapeMarkdownMin(s: string): string {
-  return s.replace(/([\\`*_~=\[\]|])/g, '\\$1')
-}
-
 /**
  * Build the operator-facing Telegram alert (GFM markdown) for an un-healable
  * Linear auth failure. Pure + self-escaping so it can be unit-tested directly.
@@ -42,7 +39,7 @@ function escapeMarkdownMin(s: string): string {
 export function buildLinearAuthDeadMessage(agent: string, reason: LinearAuthDeadReason): string {
   // Inside `code` spans the agent slug is literal (no escaping); in prose it
   // is markdown-escaped.
-  const aEsc = escapeMarkdownMin(agent)
+  const aEsc = escapeMarkdown(agent)
   const why =
     reason === 'no_bundle'
       ? `no refresh credentials are stored (\`linear/${agent}/oauth\` is missing), so its daily-expiring token can't renew`

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

@@ -308,6 +308,32 @@ export const MODEL_CALLBACK_REFRESH = 'mdl:r'
 export const MODEL_CALLBACK_SR = 'mdl:sr:'
 /** Callback for section-header rows — shows an informational toast, no action. */
 export const MODEL_CALLBACK_HEADER = 'mdl:h'
+/**
+ * Callback prefix for Claude aliases that the CLI picker doesn't render but
+ * the CLI resolves natively (e.g. `fable`). Carries the alias verbatim; its
+ * handler INJECTS `/model <alias>` — the same mechanism MODEL_CALLBACK_SR
+ * uses — because the cursor-nav select path can only pick rows claude's own
+ * picker actually renders.
+ */
+export const MODEL_CALLBACK_ALIAS = 'mdl:alias:'
+/** Callback: open the nested "External models" keyboard page. */
+export const MODEL_CALLBACK_PAGE_EXTERNAL = 'mdl:page:ext'
+/** Callback: return from the External page to the main keyboard page. */
+export const MODEL_CALLBACK_PAGE_MAIN = 'mdl:page:main'
+
+/** Which keyboard page the model menu is currently rendering. */
+export type ModelMenuPage = 'main' | 'external'
+
+/**
+ * Static Claude aliases appended to the scraped Claude group. The claude CLI's
+ * own `/model` picker (deps.discover) does NOT list `fable`, but the CLI
+ * resolves the alias natively, so we render it as an extra button that selects
+ * by injecting `/model fable` (MODEL_CALLBACK_ALIAS). Extend this list to
+ * surface further CLI-resolvable aliases the picker omits.
+ */
+export const EXTRA_CLAUDE_ALIASES: ReadonlyArray<{ alias: string; label: string }> = [
+  { alias: 'fable', label: 'Fable' },
+]
 
 /**
  * Friendly display names for sr-* synthetic model names. An sr-* model in
@@ -394,14 +420,42 @@ function headerRow(label: string): ModelMenuKeyboardButton[] {
   return [{ text: label, callback_data: MODEL_CALLBACK_HEADER }]
 }
 
-function menuKeyboard(
+/**
+ * The external (🌐 non-Anthropic) model list, sourced from the static
+ * SR_MODEL_ALIASES values UNION-ed with any live discoverSrModels() results,
+ * deduped and sorted.
+ *
+ * Why the static union: discoverSrModels() reads LiteLLM's /model/info, which
+ * 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.
+ *
+ * Subscription-honest: ONLY the curated sr-* aliases surface as buttons. Raw
+ * gpt-4o / openrouter/* dupes / voyage-* embeddings never do.
+ */
+export function externalModelNames(discovered: string[]): string[] {
+  const set = new Set<string>(Object.values(SR_MODEL_ALIASES))
+  for (const n of discovered) {
+    if (isSrModel(n)) set.add(n)
+  }
+  return [...set].sort()
+}
+
+/**
+ * Main keyboard page: scraped Claude buttons + static Fable alias, then (only
+ * when the external list is non-empty) a single "🌐 External models ▸" row that
+ * opens the nested page, then Refresh.
+ */
+function mainPageKeyboard(
   claudeOptions: ModelPickerOption[],
-  srOptions: ModelPickerOption[],
+  hasExternal: boolean,
 ): ModelMenuKeyboardButton[][] {
-  const hasBothGroups = claudeOptions.length > 0 && srOptions.length > 0
   const rows: ModelMenuKeyboardButton[][] = []
 
-  if (hasBothGroups) rows.push(headerRow('── Claude (Max / Pro subscription) ──'))
   for (const o of claudeOptions) {
     rows.push([{
       text: o.current ? `✅ ${o.label}` : o.label,
@@ -409,23 +463,44 @@ function menuKeyboard(
     }])
   }
 
-  // sr-* models are non-Anthropic (routed via LiteLLM → OpenRouter).
-  // Selection uses text-inject rather than cursor-nav — more reliable
-  // when the picker has many models (GATEWAY_MODEL_DISCOVERY=1).
-  if (srOptions.length > 0) {
-    rows.push(headerRow('── OpenRouter / external ──'))
-    for (const o of srOptions) {
-      rows.push([{
-        text: `🌐 ${srFriendlyLabel(o.label)}`,
-        callback_data: `${MODEL_CALLBACK_SR}${o.label}`,
-      }])
-    }
+  // Static Claude aliases the CLI picker omits (e.g. Fable). Deduped: if the
+  // scraped Claude options already include a matching row, don't render the
+  // static one too.
+  for (const { alias, label } of EXTRA_CLAUDE_ALIASES) {
+    const already = claudeOptions.some(
+      (o) => o.label.toLowerCase() === label.toLowerCase() ||
+        o.label.toLowerCase() === alias.toLowerCase(),
+    )
+    if (already) continue
+    rows.push([{ text: label, callback_data: `${MODEL_CALLBACK_ALIAS}${alias}` }])
+  }
+
+  if (hasExternal) {
+    rows.push([{ text: '🌐 External models ▸', callback_data: MODEL_CALLBACK_PAGE_EXTERNAL }])
   }
 
   rows.push([{ text: '🔄 Refresh', callback_data: MODEL_CALLBACK_REFRESH }])
   return rows
 }
 
+/**
+ * External keyboard page: a labelled header, one 🌐 button per external model
+ * (reusing the existing MODEL_CALLBACK_SR select handler), then Back + Refresh.
+ */
+function externalPageKeyboard(externalNames: string[]): ModelMenuKeyboardButton[][] {
+  const rows: ModelMenuKeyboardButton[][] = []
+  rows.push(headerRow('── External (billed separately) ──'))
+  for (const name of externalNames) {
+    rows.push([{
+      text: `🌐 ${srFriendlyLabel(name)}`,
+      callback_data: `${MODEL_CALLBACK_SR}${name}`,
+    }])
+  }
+  rows.push([{ text: '◂ Back', callback_data: MODEL_CALLBACK_PAGE_MAIN }])
+  rows.push([{ text: '🔄 Refresh', callback_data: MODEL_CALLBACK_REFRESH }])
+  return rows
+}
+
 /**
  * Build the `/model` dashboard: live model + quota brief + tap menu.
  * Returns a keyboard-less fallback (v1-shaped static text) when the
@@ -433,6 +508,7 @@ function menuKeyboard(
  */
 export async function buildModelMenu(
   deps: ModelMenuDeps & ModelCommandDeps,
+  page: ModelMenuPage = 'main',
 ): Promise<ModelMenuReply> {
   if (deps.isBusy()) return busyReply(deps)
 
@@ -460,7 +536,26 @@ export async function buildModelMenu(
   // sr-* models come from LiteLLM (/model/info via discoverSrModels), not the
   // claude picker — the CLI only knows Anthropic models.
   const { claude: claudeOptions } = classifyDiscoveredOptions(discovered.options)
-  const srOptions: ModelPickerOption[] = srNames.map((name, i) => ({ index: i, label: name, detail: '', current: false }))
+  const externalNames = externalModelNames(srNames)
+
+  // External page: a focused list of the 🌐 (billed-separately) models with a
+  // Back button. It never switches the model itself — the page callbacks just
+  // re-render with the other page's keyboard.
+  if (page === 'external') {
+    const lines: string[] = [`**Model — ${deps.escapeHtml(deps.getAgentName())}** · 🌐 External`]
+    lines.push(
+      '',
+      'These models are **billed separately** via OpenRouter — they do NOT use your Claude Max/Pro subscription. Tap one to switch the **live session**:',
+      PERSIST_NOTE,
+    )
+    return { text: lines.join('\n'), html: true, keyboard: externalPageKeyboard(externalNames) }
+  }
+
+  // claude's ✔ marks the DEFAULT FOR NEW SESSIONS, which is a different axis
+  // from the model the agent is running right now (set via --model at launch
+  // or a prior session switch). Labelling the ✔ row "Now:" was misleading —
+  // it could read "Opus 4.8" while the live session is on Fable. Call it what
+  // it is, and tell the operator a switch applies to the live session.
   const current = claudeOptions.find((o) => o.current)
   const lines: string[] = [`**Model — ${deps.escapeHtml(deps.getAgentName())}**`]
   if (discovered.dismissFailed) {
@@ -474,12 +569,16 @@ export async function buildModelMenu(
   }
   if (quota) lines.push(`Quota: ${deps.escapeHtml(quota)}`)
   lines.push('', 'Tap a model to switch the **live session**:')
-  if (srOptions.length > 0) {
-    lines.push('Claude models use your Max/Pro subscription. 🌐 models are billed separately via OpenRouter.')
+  if (externalNames.length > 0) {
+    lines.push('Claude models use your Max/Pro subscription. Tap 🌐 External models for models billed separately via OpenRouter.')
   }
   lines.push(PERSIST_NOTE)
 
-  return { text: lines.join('\n'), html: true, keyboard: menuKeyboard(claudeOptions, srOptions) }
+  return {
+    text: lines.join('\n'),
+    html: true,
+    keyboard: mainPageKeyboard(claudeOptions, externalNames.length > 0),
+  }
 }
 
 export interface ModelCallbackOutcome {
@@ -519,6 +618,61 @@ export async function handleModelMenuCallback(
     return { answer: 'Refreshed', reply: await buildModelMenu(deps) }
   }
 
+  // Page navigation — these DO NOT switch the model. They just re-render the
+  // menu with the other page's keyboard + body text (mirrors the REFRESH shape).
+  if (data === MODEL_CALLBACK_PAGE_EXTERNAL) {
+    return { answer: 'External models', reply: await buildModelMenu(deps, 'external') }
+  }
+  if (data === MODEL_CALLBACK_PAGE_MAIN) {
+    return { answer: 'Back', reply: await buildModelMenu(deps, 'main') }
+  }
+
+  // Claude-alias tap (e.g. Fable): the CLI resolves the alias but its picker
+  // doesn't render it, so select by injecting `/model <alias>` — same path as
+  // the sr-* handler below, no cursor-nav.
+  if (data.startsWith(MODEL_CALLBACK_ALIAS)) {
+    const alias = data.slice(MODEL_CALLBACK_ALIAS.length)
+    if (!isValidModelArg(alias)) {
+      return { answer: 'Invalid model name', reply: await buildModelMenu(deps) }
+    }
+    if (deps.isBusy()) {
+      return {
+        answer: '⏳ Agent is mid-turn — tap again when it’s idle',
+        reply: busyReply(deps),
+        toastOnly: true,
+      }
+    }
+    let aliasResult: InjectResult
+    try {
+      aliasResult = await deps.inject(deps.getAgentName(), `/model ${alias}`)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      return {
+        answer: 'Switch failed',
+        reply: await menuWithBanner(deps, `❌ Switch to **${deps.escapeHtml(alias)}** failed: ${deps.escapeHtml(msg)}`),
+      }
+    }
+    if (aliasResult.outcome === 'ok') {
+      const confirmation =
+        aliasResult.output
+          .split('\n')
+          .map((l) => l.trim())
+          .find((l) => /set model|switched/i.test(l)) ?? `Switched to ${alias} (session)`
+      return {
+        answer: confirmation,
+        reply: await menuWithBannerStatic(deps, `✅ ${deps.escapeHtml(confirmation)}`),
+        selectedModel: sessionModelFromConfirmation(confirmation) ?? alias,
+      }
+    }
+    return {
+      answer: 'Switch failed',
+      reply: await menuWithBanner(
+        deps,
+        `❌ Switch to **${deps.escapeHtml(alias)}** failed — agent may be mid-turn`,
+      ),
+    }
+  }
+
   if (data === MODEL_CALLBACK_HEADER) {
     // Section-header row — the gateway handles this with a direct answerCallbackQuery
     // before calling this function, so this branch is dead in practice. Guard

package/telegram-plugin/gateway/obligation-turn-end.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure decision for what a turn_end does to the ending turn's delivery
+ * obligation (#2624).
+ *
+ * Two branches, both must be pinned by tests:
+ *
+ *   - **Normal reply** — the turn either delivered a genuine final answer
+ *     (`finalAnswerDelivered`) OR the model explicitly called reply
+ *     (`replyCalled`, true even for a short LiteLLM sr-* `reply("OK",
+ *     {disable_notification:true})` that `isFinalAnswerReply` demoted to
+ *     non-final). Either way the obligation is satisfied → close it at
+ *     turn_end.
+ *
+ *   - **Ack-then-ghost / no-reply** — the turn ended with no reply at all
+ *     (no ack, no answer). The obligation must NOT close at turn_end; it
+ *     stays open and the idle sweep later ends it via the silence_fallback
+ *     path. At turn_end we only stamp the grace clock (`note-ended`).
+ *
+ * Returns the action the caller applies to the ledger. Pure — no ledger
+ * mutation, no module state.
+ */
+export function decideObligationTurnEnd(
+  finalAnswerDelivered: boolean,
+  replyCalled: boolean,
+): 'close' | 'note-ended' {
+  return finalAnswerDelivered || replyCalled ? 'close' : 'note-ended'
+}

package/telegram-plugin/gateway/permission-card-store.ts

@@ -0,0 +1,104 @@
+/**
+ * Persistence store for in-flight permission card references.
+ *
+ * Problem: `pendingPermissions` is in-memory. When the gateway restarts
+ * (gateway crash OR container restart), all entries are lost. Old permission
+ * cards in Telegram keep their [Allow][Deny] inline keyboard buttons.
+ * When the operator taps one, they get STALE_TAP_NOTICE ("already resolved
+ * (timed out)"), which is misleading — the request wasn't resolved, it was
+ * lost. Operators interpret this as "my approval didn't work."
+ *
+ * Fix: persist the (chatId, messageId) references for every posted card to a
+ * JSON file in STATE_DIR. On each resolution (allow/deny/TTL-expire), remove
+ * the entry. On gateway boot, load any surviving entries (they were never
+ * resolved — the gateway crashed) and strip their inline keyboards + add a
+ * "gateway restarted" footer so the operator sees a clear explanation instead
+ * of a tappable-but-dead button.
+ *
+ * File format: JSON array of PersistedPermCard objects. Kept small (one file,
+ * written synchronously to avoid interleaving on concurrent card posts).
+ * Production rate: a few cards per permission request; file stays tiny.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface PersistedPermCard {
+  requestId: string
+  chatId: string
+  messageId: number
+  startedAt: number
+  toolName: string
+  cardText: string
+}
+
+export interface PermissionCardStore {
+  /** Record a newly-posted card. Idempotent on requestId+messageId. */
+  add(entry: PersistedPermCard): void
+  /** Remove all entries for this request (resolved — allow, deny, TTL). */
+  remove(requestId: string): void
+  /** Return all persisted entries (for boot-time stale-strip sweep). */
+  loadAll(): PersistedPermCard[]
+  /** Delete the backing file entirely (after boot sweep completes). */
+  clear(): void
+}
+
+export function createPermissionCardStore(stateDir: string): PermissionCardStore {
+  const filePath = join(stateDir, 'pending-perm-cards.json')
+
+  function read(): PersistedPermCard[] {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      return Array.isArray(parsed) ? (parsed as PersistedPermCard[]) : []
+    } catch {
+      return []
+    }
+  }
+
+  function write(entries: PersistedPermCard[]): void {
+    try {
+      writeFileSync(filePath, JSON.stringify(entries), { encoding: 'utf-8', mode: 0o600 })
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: permission-card-store write failed: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  return {
+    add(entry) {
+      const entries = read()
+      // Replace existing entry for same (requestId, messageId) if present
+      const idx = entries.findIndex(
+        e => e.requestId === entry.requestId && e.messageId === entry.messageId,
+      )
+      if (idx >= 0) {
+        entries[idx] = entry
+      } else {
+        entries.push(entry)
+      }
+      write(entries)
+    },
+
+    remove(requestId) {
+      const entries = read()
+      const filtered = entries.filter(e => e.requestId !== requestId)
+      if (filtered.length !== entries.length) {
+        write(filtered)
+      }
+    },
+
+    loadAll() {
+      return read()
+    },
+
+    clear() {
+      try {
+        unlinkSync(filePath)
+      } catch {
+        // File may not exist — that's fine
+      }
+    },
+  }
+}

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

@@ -71,17 +71,36 @@ export function isRecentTimeoutDuplicate(
 
 // ─── Bug 2 — per-tool TTL + timed-out card hygiene + stale-tap honesty ──────
 
-/** Default operator approval-card lifetime. */
-export const PERMISSION_TTL_MS = 10 * 60_000
+/** Fallback operator approval-card lifetime when nothing is configured. */
+export const PERMISSION_TTL_DEFAULT_MS = 60 * 60_000
+
+/**
+ * Resolve the operator approval-card lifetime (ms) from the environment.
+ * Threaded from config as `channels.telegram.approval_timeout_minutes` →
+ * `SWITCHROOM_TG_APPROVAL_TIMEOUT_MS` (see scaffold.ts `channelsToEnv`). A
+ * blank/garbage value falls back to the 60-min default; `0` (or negative) is
+ * clamped to the default so a card can never be born already-expired.
+ */
+export function approvalTtlMs(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.SWITCHROOM_TG_APPROVAL_TIMEOUT_MS
+  if (raw === undefined || raw.trim() === '') return PERMISSION_TTL_DEFAULT_MS
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n <= 0) return PERMISSION_TTL_DEFAULT_MS
+  return Math.floor(n)
+}
+
+/** Default operator approval-card lifetime (config-driven, 60 min default). */
+export const PERMISSION_TTL_MS = approvalTtlMs()
 
 /**
  * hostd gated fleet-mutation verbs (rollout / update_apply / agent_* /
  * config_propose_edit) surface an OPERATOR approval card and demand a
- * human-scale decision window — 10 min is too tight when the operator is
- * mid-task. The `mcp__hostd__*` family gets 30 min; everything else keeps
- * the 10-min default.
+ * human-scale decision window. The `mcp__hostd__*` family gets at least
+ * 30 min; if the configured approval window is longer, it wins.
  */
-export const HOSTD_PERMISSION_TTL_MS = 30 * 60_000
+export const HOSTD_PERMISSION_TTL_MS = Math.max(30 * 60_000, PERMISSION_TTL_MS)
 
 /** Per-tool approval-card TTL. */
 export function ttlForTool(toolName: string | undefined): number {