switchroom 0.18.7 → 0.18.9

package/telegram-plugin/flood-circuit-breaker.ts

@@ -0,0 +1,123 @@
+/**
+ * Telegram per-bot flood-wait circuit breaker (issue #2923).
+ *
+ * When a burst of outbound sends trips Telegram's per-bot-token flood limit,
+ * the API returns `429 { retry_after: N }` — a SERVER-SIDE ban on the bot
+ * token that no client-side lever clears early (observed retry_after ~4116s,
+ * ~68 min). The failure is misleading: the container is `Up`, the gateway is
+ * polling, inbound works — but every outbound send is rejected. Worse, each
+ * `docker restart` posts a fresh boot/config card = another send INTO the
+ * open window, which can reset/extend the flood counter. A local, recoverable
+ * disk-full problem thereby amplifies into a remote, unrecoverable ban.
+ *
+ * This breaker persists the flood-wait window to disk so that:
+ *   - `retryApiCall`'s `onFloodWait` hook records it the moment a 429 is seen;
+ *   - a restart-time NON-ESSENTIAL send (boot card, config summary) consults
+ *     `isFloodWaitActive` and SKIPS while the ban is open, so a restart during
+ *     a flood-wait doesn't feed the counter and prolong the ban.
+ *
+ * The state file is tiny JSON under the agent's telegram state dir. All the
+ * logic is pure + injectable so it unit tests without a real clock or bot.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export interface FloodWaitState {
+  /** Epoch ms at which the flood-wait window expires. */
+  untilTs: number
+  /** The retry_after (seconds) Telegram reported, for diagnostics. */
+  retryAfterSec: number
+  /** Epoch ms the window was (re)recorded. */
+  recordedTs: number
+}
+
+/** Default marker filename inside the telegram state dir. */
+export const FLOOD_STATE_FILE = 'flood-wait.json'
+
+/**
+ * Resolve the flood-wait marker path from a telegram state dir. Kept as a
+ * helper so callers share one location.
+ */
+export function floodStatePath(stateDir: string): string {
+  return join(stateDir, FLOOD_STATE_FILE)
+}
+
+/**
+ * Compute the flood-wait state for an observed `retry_after`. Extends (never
+ * shrinks) an existing window: if a fresh 429 reports a shorter remaining ban
+ * than we already recorded, we keep the longer expiry — the server is the
+ * authority and being conservative avoids sending back into an open window.
+ */
+export function computeFloodWait(
+  prior: FloodWaitState | null,
+  retryAfterSec: number,
+  now: number,
+): FloodWaitState {
+  const candidate = now + Math.max(0, retryAfterSec) * 1000
+  const untilTs = prior && prior.untilTs > candidate ? prior.untilTs : candidate
+  return { untilTs, retryAfterSec, recordedTs: now }
+}
+
+/** Remaining ban time in ms (0 when no active window). */
+export function floodWaitRemainingMs(state: FloodWaitState | null, now: number): number {
+  if (!state) return 0
+  return Math.max(0, state.untilTs - now)
+}
+
+/** True while the flood-wait ban is still open. */
+export function isFloodWaitActive(state: FloodWaitState | null, now: number): boolean {
+  return floodWaitRemainingMs(state, now) > 0
+}
+
+/** Read persisted flood state; null on absence / parse failure. */
+export function readFloodState(path: string): FloodWaitState | null {
+  try {
+    if (!existsSync(path)) return null
+    const raw = JSON.parse(readFileSync(path, 'utf-8')) as Partial<FloodWaitState>
+    if (typeof raw.untilTs !== 'number') return null
+    return {
+      untilTs: raw.untilTs,
+      retryAfterSec: typeof raw.retryAfterSec === 'number' ? raw.retryAfterSec : 0,
+      recordedTs: typeof raw.recordedTs === 'number' ? raw.recordedTs : 0,
+    }
+  } catch {
+    return null
+  }
+}
+
+/** Persist flood state (best-effort — a write failure must not crash the send path). */
+export function writeFloodState(path: string, state: FloodWaitState): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(state), { mode: 0o600 })
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Build the `onFloodWait` callback for `createRetryApiCall`, wired to persist
+ * (and extend) the window at `path`. Reads current state, merges the new
+ * retry_after, writes it back.
+ */
+export function makeFloodWaitRecorder(
+  path: string,
+  now: () => number = Date.now,
+): (retryAfterSec: number) => void {
+  return (retryAfterSec: number) => {
+    const t = now()
+    const next = computeFloodWait(readFloodState(path), retryAfterSec, t)
+    writeFloodState(path, next)
+  }
+}
+
+/**
+ * Decide whether a NON-ESSENTIAL restart-time send (boot card, config
+ * summary) should be suppressed because a flood-wait is active. Returns the
+ * remaining ms when suppressed (>0), or 0 to proceed. Reads state fresh so a
+ * concurrently-updated window is honoured.
+ */
+export function suppressNonEssentialSendMs(path: string, now: number): number {
+  return floodWaitRemainingMs(readFloodState(path), now)
+}

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

@@ -43,6 +43,11 @@
  * failure than one frozen orphan. A benign-400 (message already
  * deleted/vanished, or "not modified") is NOT counted as a finalize — nothing
  * was delivered — see the `vanished` tally in `runActivityCardBootReaper`.
+ *
+ * The UNPIN half is different (#3001): unpinning is idempotent, so it gets
+ * AT-LEAST-ONCE (capped) semantics — a failed unpin re-persists the record
+ * with `finalizeAttempted: true` + an `unpinAttempts` counter so the next boot
+ * retries ONLY the unpin (never the edit), up to BOOT_UNPIN_MAX_ATTEMPTS.
  */
 
 export interface ActivityCardStoreFsSeam {
@@ -73,8 +78,21 @@ export interface ActivityCardRecord {
    *  forever). Optional so a v1-shape record (pre-unpin-tracking) still
    *  loads and degrades to "don't attempt an unpin", never a crash. */
   pinned?: boolean
+  /** Set when the boot reaper retains a record ONLY to retry its failed
+   *  unpin (#3001). The finalizing edit stays AT-MOST-ONCE: a retained
+   *  record's edit was already attempted, so the next boot skips the edit
+   *  and only retries the (idempotent) unpin. */
+  finalizeAttempted?: boolean
+  /** Boot-reaper unpin retry counter (#3001); the record is forfeited at
+   *  BOOT_UNPIN_MAX_ATTEMPTS. Absent = 0. */
+  unpinAttempts?: number
 }
 
+/** Cap on cross-boot unpin retries — same rationale as the status-pin
+ *  store's BOOT_UNPIN_MAX_ATTEMPTS (bound a permanently-undeliverable
+ *  unpin; unpins themselves are idempotent so retrying is safe). */
+export const BOOT_UNPIN_MAX_ATTEMPTS = 5
+
 interface SnapshotEnvelope {
   v: 1
   cards: ActivityCardRecord[]
@@ -91,7 +109,9 @@ function isCardRow(x: unknown): x is ActivityCardRecord {
     (o.threadId === null || typeof o.threadId === 'number') &&
     typeof o.activityMessageId === 'number' &&
     typeof o.startedAt === 'number' &&
-    (o.pinned === undefined || typeof o.pinned === 'boolean')
+    (o.pinned === undefined || typeof o.pinned === 'boolean') &&
+    (o.finalizeAttempted === undefined || typeof o.finalizeAttempted === 'boolean') &&
+    (o.unpinAttempts === undefined || typeof o.unpinAttempts === 'number')
   )
 }
 
@@ -245,32 +265,57 @@ export async function runActivityCardBootReaper(args: {
     // turn that upserted a fresh card under the same turnKey mid-reap keeps
     // its own (different-id) record.
     clearActivityCardRecord(args.path, args.fs, record.turnKey, record.activityMessageId, log)
-    try {
-      // Count a finalize ONLY when the edit actually landed. robustApiCall
-      // resolves to undefined on a benign-400 (the card was already deleted or
-      // the chat is gone) — that delivered nothing, so it is a `vanished`
-      // orphan, not a `finalized` one. Counting it as finalized (the pre-fix
-      // behaviour) over-reported the guarantee in the boot log.
-      const res = await args.finalizeCard(record)
-      if (res != null) finalized++
-      else vanished++
-    } catch (err) {
-      log(
-        `activity-card-store: boot reaper finalize failed ` +
-          `(chat=${record.chatId} msg=${record.activityMessageId}): ` +
-          `${(err as Error).message}\n`,
-      )
+    // The finalizing EDIT stays at-most-once: skip it for a record retained by
+    // a prior boot purely to retry its failed unpin (finalizeAttempted).
+    if (!record.finalizeAttempted) {
+      try {
+        // Count a finalize ONLY when the edit actually landed. robustApiCall
+        // resolves to undefined on a benign-400 (the card was already deleted or
+        // the chat is gone) — that delivered nothing, so it is a `vanished`
+        // orphan, not a `finalized` one. Counting it as finalized (the pre-fix
+        // behaviour) over-reported the guarantee in the boot log.
+        const res = await args.finalizeCard(record)
+        if (res != null) finalized++
+        else vanished++
+      } catch (err) {
+        log(
+          `activity-card-store: boot reaper finalize failed ` +
+            `(chat=${record.chatId} msg=${record.activityMessageId}): ` +
+            `${(err as Error).message}\n`,
+        )
+      }
     }
     if (record.pinned) {
       try {
         await args.unpinCard(record)
         unpinned++
       } catch (err) {
+        // Retry-safe unpin (#3001): unlike the edit (at-most-once by design),
+        // an unpin is idempotent — so a failed one is RE-PERSISTED with an
+        // attempt counter and retried on the next boot, up to the cap, instead
+        // of being forfeited. `finalizeAttempted` guarantees the retained
+        // record can never re-run its edit.
+        const attempts = (record.unpinAttempts ?? 0) + 1
         log(
           `activity-card-store: boot reaper unpin failed ` +
-            `(chat=${record.chatId} msg=${record.activityMessageId}): ` +
-            `${(err as Error).message}\n`,
+            `(chat=${record.chatId} msg=${record.activityMessageId} ` +
+            `attempt=${attempts}): ${(err as Error).message}\n`,
         )
+        if (attempts < BOOT_UNPIN_MAX_ATTEMPTS) {
+          writeActivityCardRecord(
+            args.path,
+            args.fs,
+            { ...record, finalizeAttempted: true, unpinAttempts: attempts },
+            log,
+          )
+        } else {
+          log(
+            `activity-card-store: boot reaper FORFEITING card unpin after ` +
+              `${attempts} failed attempts ` +
+              `(chat=${record.chatId} msg=${record.activityMessageId}) — ` +
+              `will not retry again\n`,
+          )
+        }
       }
     }
   }

package/telegram-plugin/gateway/approval-card-stores.ts

@@ -0,0 +1,99 @@
+/**
+ * In-memory storage for the four AGENT-INITIATED approval-card families
+ * (vault_request_access / vault_request_save / request_secret /
+ * mental_model_propose), extracted from gateway.ts (Phase 3 step 1 of the
+ * gateway decomposition — see #2996). STORAGE ONLY: the per-card expiry LOGIC
+ * (card edits, timeout synthetics, missed-approval re-offers) still lives in
+ * gateway.ts and is injected here as `expire`. This module owns the Map
+ * lifecycle and CO-LOCATES the TTL sweep next to the storage it sweeps, so the
+ * gateway's authoritative `pendingStateReaper` calls a single `store.sweep(now)`
+ * delegation instead of open-coding a `sweepExpiredEntries(...)` per family.
+ *
+ * Why a Map-compatible surface (get/set/delete/has/iteration) rather than a
+ * bespoke API: every existing gateway call site — the callback-query handlers,
+ * the executor add-sites, and `restorePendingApprovalCards` — used the raw Map
+ * directly. Preserving the exact Map method surface keeps those call sites
+ * BYTE-IDENTICAL (the variable name and every `.get`/`.set`/`.delete`/`for..of`
+ * are unchanged), which is the invariant this phase must not break: the store
+ * moves WHERE the Map is constructed and WHERE its sweep lives, nothing about
+ * how the gateway reads or writes it. Restore semantics are therefore untouched.
+ *
+ * Race contract preserved (pinned by approval-card-stores.test.ts):
+ *   - A verdict (operator tap → `.delete(stageId)`) arriving DURING an expiry
+ *     sweep is single-shot-safe: the pure `expirePendingCard` core removes the
+ *     entry before any fallible side effect, so the same card can never both
+ *     expire and resolve. The store's `sweep` is a thin pass-through to that
+ *     core via `sweepExpiredEntries`, so the ordering guarantee is unchanged.
+ *   - A verdict arriving DURING restore is a plain `.set`/`.delete` on the same
+ *     Map instance the restore populates — no separate storage to desync.
+ *   - The shared reaper cadence is unchanged: `sweep(now)` performs exactly the
+ *     work the old `sweepPendingX(now)` free functions did, in the same order.
+ *
+ * `expire` and `log` are supplied as THUNKS so a store constructed early in
+ * gateway module-eval can reference the hoisted `expire*Card` functions and the
+ * `const cardExpiryLog` arrow (which is in the temporal dead zone at
+ * construction time); both are resolved lazily at sweep time.
+ */
+
+import { sweepExpiredEntries } from './pending-card-expiry.js'
+
+export interface SweepableCardStore<T> {
+  get(stageId: string): T | undefined
+  set(stageId: string, value: T): void
+  delete(stageId: string): boolean
+  has(stageId: string): boolean
+  clear(): void
+  readonly size: number
+  keys(): IterableIterator<string>
+  values(): IterableIterator<T>
+  entries(): IterableIterator<[string, T]>
+  forEach(cb: (value: T, key: string, map: Map<string, T>) => void): void
+  [Symbol.iterator](): IterableIterator<[string, T]>
+  /**
+   * Expire every entry past its TTL. Delegates to the same pure
+   * `sweepExpiredEntries` core the gateway used inline, so per-entry
+   * fault-isolation and single-shot ordering are byte-identical.
+   */
+  sweep(now: number): void
+}
+
+export interface SweepableCardStoreDeps<T> {
+  /** Predicate: is this entry past its TTL at `now`? Closes over the family TTL. */
+  isExpired: (value: T, now: number) => boolean
+  /**
+   * Per-entry expiry action (card strip + timeout synthetic + missed-approval
+   * re-offer). A THUNK so it can reference gateway functions that are hoisted /
+   * defined after this store is constructed. Called once per expired entry.
+   */
+  expire: () => (stageId: string, value: T, now: number) => void
+  /** Error sink thunk (resolves the gateway's `cardExpiryLog` lazily). */
+  log: () => (msg: string) => void
+}
+
+/**
+ * Create a Map-backed, self-sweeping store for one approval-card family.
+ * The backing Map is the sole storage; the returned object forwards the Map
+ * surface the gateway uses plus a co-located `sweep`.
+ */
+export function createSweepableCardStore<T>(
+  deps: SweepableCardStoreDeps<T>,
+): SweepableCardStore<T> {
+  const map = new Map<string, T>()
+  return {
+    get: (stageId) => map.get(stageId),
+    set: (stageId, value) => void map.set(stageId, value),
+    delete: (stageId) => map.delete(stageId),
+    has: (stageId) => map.has(stageId),
+    clear: () => map.clear(),
+    get size() {
+      return map.size
+    },
+    keys: () => map.keys(),
+    values: () => map.values(),
+    entries: () => map.entries(),
+    forEach: (cb) => map.forEach(cb),
+    [Symbol.iterator]: () => map[Symbol.iterator](),
+    sweep: (now) =>
+      sweepExpiredEntries(map, deps.isExpired, deps.expire(), now, deps.log()),
+  }
+}

package/telegram-plugin/gateway/boot-card.ts

@@ -69,6 +69,7 @@ import {
 } from './config-snapshot.js'
 import { join } from 'path'
 import { bootCardChatKey, loadBootCardMsgId, saveBootCardMsgId } from './boot-card-msgid.js'
+import { suppressNonEssentialSendMs } from '../flood-circuit-breaker.js'
 import { loadConfig as _loadSwitchroomConfig } from '../../src/config/loader.js'
 import { resolveAgentConfig as _resolveAgentConfig } from '../../src/config/merge.js'
 
@@ -605,6 +606,16 @@ export interface RunProbesOpts {
    * behaviour.
    */
   bootCardStatePath?: string
+  /**
+   * #2923 flood-wait circuit breaker. Path to the persisted flood-wait
+   * marker. When a Telegram per-bot flood ban is active, posting a boot card
+   * on restart is a NON-ESSENTIAL send straight into the open window that can
+   * reset/extend the ban — so if this path shows an active flood-wait, the
+   * boot card is SUPPRESSED (logged, not sent). Omit to always post.
+   */
+  floodStatePath?: string
+  /** Injectable clock for the flood-wait check (tests). Defaults to Date.now. */
+  nowMs?: () => number
 }
 
 /** Run all six probes concurrently with their own per-probe timeouts.
@@ -652,6 +663,22 @@ export async function startBootCard(
   const setTimeoutFn = opts.setTimeoutImpl ?? setTimeout
   const settleMs = opts.settleWindowMs ?? SETTLE_WINDOW_MS
 
+  // #2923 circuit breaker: if a per-bot Telegram flood ban is active, do NOT
+  // post the boot card. It's a non-essential restart-time send straight into
+  // the open flood window — the exact thing that resets/extends the ban and
+  // keeps the agent mute for longer. Skip loudly (log) and return a no-op.
+  if (opts.floodStatePath != null) {
+    const now = (opts.nowMs ?? Date.now)()
+    const remainingMs = suppressNonEssentialSendMs(opts.floodStatePath, now)
+    if (remainingMs > 0) {
+      logger(
+        `telegram gateway: boot-card: SUPPRESSED — Telegram flood-wait active for ~${Math.round(remainingMs / 1000)}s; ` +
+          `not posting a restart card into the open ban window (issue #2923)\n`,
+      )
+      return { messageId: -1, complete: () => {} }
+    }
+  }
+
   // Render and post the bare ack line immediately. The user gets
   // confirmation that the agent is back without waiting on probes.
   const ackText = renderBootCard({

package/telegram-plugin/gateway/bot-commands-ops-info.ts

@@ -0,0 +1,194 @@
+import type { Bot, Context, InlineKeyboard } from 'grammy'
+import { hostdWillBeUsed } from './hostd-dispatch.js'
+import { maskVaultKey } from '../demo-mask.js'
+import { switchroomHelpText as buildSwitchroomHelpText } from '../welcome-text.js'
+
+/**
+ * Read-only ops/info slash commands extracted verbatim from gateway.ts
+ * (#2996 Phase 5 leaf move): `/doctor`, `/grant`, `/dangerous`,
+ * `/permissions`, `/version`, `/whoami`, `/commands`.
+ *
+ * These are pure info/ops surfaces (no send-path or turn-lifecycle
+ * coupling). Every gateway-local helper they close over is passed in via
+ * `deps` (repo factory-deps precedent) so the module never back-references
+ * the gateway singleton or reads `currentTurn`. `bot` is injected so
+ * grammy registration order is preserved at the original call site.
+ */
+export interface OpsInfoCommandDeps {
+  AGENT_ADMIN: boolean
+  isAuthorizedSender: (ctx: Context) => boolean
+  getMyAgentName: () => string
+  switchroomReply: (
+    ctx: Context,
+    text: string,
+    options?: {
+      html?: boolean
+      reply_markup?: InlineKeyboard
+      classification?: 'query' | 'mutation' | 'heavy'
+    },
+  ) => Promise<void>
+  buildDoctorScopeKeyboard: () => InlineKeyboard
+  renderSelfDoctor: (ctx: Context) => Promise<void>
+  preBlock: (text: string) => string
+  formatSwitchroomOutput: (output: string, maxLen?: number) => string
+  getCommandArgs: (ctx: Context) => string
+  assertSafeAgentName: (name: string) => void
+  runSwitchroomCommand: (
+    ctx: Context,
+    args: string[],
+    label: string,
+    classification?: 'query' | 'mutation' | 'heavy',
+  ) => Promise<void>
+  switchroomExecCombined: (args: string[], timeoutMs?: number) => string
+  stripAnsi: (text: string) => string
+  hasDemoFlag: (args: string) => boolean
+  escapeHtmlForTg: (text: string) => string
+}
+
+export function registerOpsInfoCommands(bot: Bot, deps: OpsInfoCommandDeps): void {
+  const {
+    AGENT_ADMIN,
+    isAuthorizedSender,
+    getMyAgentName,
+    switchroomReply,
+    buildDoctorScopeKeyboard,
+    renderSelfDoctor,
+    preBlock,
+    formatSwitchroomOutput,
+    getCommandArgs,
+    assertSafeAgentName,
+    runSwitchroomCommand,
+    switchroomExecCombined,
+    stripAnsi,
+    hasDemoFlag,
+    escapeHtmlForTg,
+  } = deps
+
+  /** 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('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 })
+    }
+  })
+
+  bot.command('commands', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    await switchroomReply(ctx, buildSwitchroomHelpText(getMyAgentName()), { html: true })
+  })
+}