switchroom 0.8.1 → 0.11.0

package/telegram-plugin/gateway/gateway.ts

@@ -52,6 +52,7 @@ import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
+import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
 import { handlePtyPartialPure, type PtyHandlerState } from '../pty-partial-handler.js'
@@ -82,32 +83,27 @@ import {
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
 import { gatewayStartupRetry } from './startup-network-retry.js'
 import { writeQuarantineMarker } from './quarantine.js'
+// RFC H §7.3: auth-dashboard + auth-slot-parser deleted. Three chat
+// verbs (/auth show | use | rotate) talk to switchroom-auth-broker
+// via the thin client in src/auth/broker/client.ts.
 import {
-  parseAuthSubCommand,
-  checkRemoveSafety,
-  formatSlotList,
-  type SlotListingFromCli,
-} from '../auth-slot-parser.js'
+  parseAuthCommand,
+  handleAuthCommand,
+  isAuthAdmin,
+  pendingAuthRmFlows,
+} from './auth-command.js'
+import type { AuthBrokerClient } from './auth-command.js'
+import type { ListStateData } from './auth-line.js'
+import { getAuthBrokerClient, addAccountViaBroker } from './auth-broker-client.js'
+import { resolveAuthBrokerSocketPath } from '../../src/auth/broker/client.js'
+import { createFleetFallbackGate } from '../fleet-fallback-gate.js'
 import {
-  buildDashboard,
-  buildRemoveConfirmKeyboard,
-  buildAccountConfirmKeyboard,
-  buildAccountPromoteConfirmKeyboard,
-  buildSwitchPrimaryKeyboard,
-  buildAccountSubViewText,
-  buildAccountSubViewKeyboard,
-  buildAccountRemoveConfirmKeyboard,
-  parseCallbackData,
-  encodeCallbackData,
-  isQuotaHot,
-  isAccountQuotaHot,
-  ACCOUNTS_DISPLAY_CAP,
-  type DashboardState,
-  type DashboardSlot,
-  type SlotHealth,
-  type AccountSummary,
-  type AccountHealth,
-} from '../auth-dashboard.js'
+  pendingAuthAddFlows,
+  startAccountAuthSession,
+  submitAccountAuthCode,
+  cancelAccountAuthSession,
+  cleanScratchDir as cleanAuthAddScratchDir,
+} from './auth-add-flow.js'
 import {
   initHistory, recordInbound, recordOutbound, recordEdit,
   deleteFromHistory, query as queryHistory, getLatestInboundMessageId,
@@ -131,6 +127,8 @@ import {
   formatModelUnavailableCard,
   resolveModelUnavailableFromOperatorEvent,
 } from '../model-unavailable.js'
+import { runFleetAutoFallback } from '../auto-fallback-fleet.js'
+import { fetchAccountQuota } from '../quota-check.js'
 import { startRestartWatchdog } from './restart-watchdog.js'
 import { validateStringArray } from './access-validator.js'
 
@@ -167,6 +165,11 @@ import {
   TELEGRAM_SWITCHROOM_COMMANDS,
   type AgentMetadata, type AuthSummary, type StatusProbeRow,
 } from '../welcome-text.js'
+import {
+  type BrokerStateView,
+  type ClaudeJsonView,
+  buildAuthSummaryFromBroker,
+} from './auth-status-adapter.js'
 import {
   isContextExhaustionText,
   shouldArmOrphanedReplyTimeout,
@@ -193,37 +196,52 @@ import {
 import { sweepActiveReactions } from '../active-reactions-sweep.js'
 import { flushOnAgentDisconnect } from './disconnect-flush.js'
 import { PreambleSuppressor } from './preamble-suppressor.js'
+import {
+  fetchFolderPage,
+  FolderListCache,
+} from '../../src/drive/folder-list.js'
+import { loadFromAuthBroker } from '../../src/drive/wrapper-broker.js'
+import {
+  handleFoldersCommand,
+  handleFolderPickerCallback,
+  type FolderPickerHandlerDeps,
+} from './folder-picker-handler.js'
+import {
+  approvalConsume as kernelApprovalConsume,
+  approvalRecord as kernelApprovalRecord,
+  approvalRequest as kernelApprovalRequest,
+} from '../../src/vault/approvals/client.js'
 import {
   fetchQuota,
   formatQuotaBlock,
-  getCachedAccountQuota,
-  prefetchAccountQuotaIfStale,
-  hydrateAccountQuotaCacheFromDisk,
-  clearAccountQuotaCache,
 } from '../quota-check.js'
 import {
-  evaluateFallbackTrigger,
-  performAutoFallback,
-  emptyLockout,
   loadLockout,
-  nextLockout,
-  saveLockout,
   DEFAULT_FALLBACK_COOLDOWN_MS,
-  type LockoutRecord,
   type LockoutPersistOps,
 } from '../auto-fallback.js'
-import { markSlotQuotaExhausted, DEFAULT_SLOT } from '../../src/auth/accounts.js'
-import { fallbackToNextSlot, currentActiveSlot, type AuthCodeOutcome } from '../../src/auth/manager.js'
+import { DEFAULT_SLOT } from '../../src/auth/accounts.js'
+import { currentActiveSlot, type AuthCodeOutcome } from '../../src/auth/manager.js'
 import { injectSlashCommand as injectSlashCommandImpl } from '../../src/agents/inject.js'
 import { handleInjectCommand } from './inject-handler.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
-import { dispatchFallbackNotification } from '../auto-fallback-dispatcher.js'
 import { loadConfig as loadSwitchroomConfig } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
+import {
+  tryHostdDispatch,
+  hostdRequestId,
+  hostdWillBeUsed,
+  pollHostdStatus,
+  warnLegacySpawnIfHostdDisabled,
+  _resetHostdEnabledCache,
+} from './hostd-dispatch.js'
+import type { HostdRequest } from '../../src/host-control/protocol.js'
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
+import { handleRequestDriveApproval } from './drive-write-approval.js'
+import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer } from './pending-inbound-buffer.js'
 import {
   buildVaultGrantApprovedInbound,
@@ -373,9 +391,14 @@ const INBOX_DIR = join(STATE_DIR, 'inbox')
  *     gateway plugin (we're a child of claude inside the same container).
  *     `targetAgent` is informational only here — we can't restart a
  *     different agent's container from inside our own (no docker.sock).
- *   - else (legacy systemd): detached `systemctl --user restart` of the
- *     two units. The detach is required so the systemctl job survives
- *     us being SIGTERM'd by systemd itself.
+ *   - else (v0.6 legacy non-docker path, scheduled for removal in
+ *     Phase 3 of the host-control daemon rollout — see
+ *     `docs/rfcs/host-control-daemon.md`): detached `systemctl --user
+ *     restart` of the two units. This branch is never reached on
+ *     v0.7+ docker installs (the `isDocker` guard above takes the
+ *     docker branch); only callable on legacy systemd hosts that
+ *     ran the gateway as a user unit. Don't add new dependencies
+ *     on this path.
  *
  * `targetAgent` defaults to `SWITCHROOM_AGENT_NAME`; pass a different
  * value only for the inline restart-button callback handler. Under
@@ -1086,6 +1109,14 @@ type CurrentTurn = {
   gatewayReceiveAt: number
   replyCalled: boolean
   capturedText: string[]
+  // #1291: snapshot of capturedText.length at the moment of the most
+  // recent reply / stream_reply tool call. Used by decideTurnFlush to
+  // isolate the post-reply tail (e.g. a soft-commit reply followed by
+  // the real substantive answer in terminal text only) and flush it as
+  // a follow-up message. Pre-#1291 the existence of ANY reply call
+  // suppressed flush entirely — that lost long terminal-only answers
+  // after a "let me check" interim reply.
+  capturedTextLenAtLastReply: number
   orphanedReplyTimeoutId: ReturnType<typeof setTimeout> | null
   registryKey: string | null
   // Last assistant outbound message id for the current turn — populated
@@ -1974,6 +2005,13 @@ const awaitingAuthCodeAt = new Map<string, number>()
 const AUTH_CODE_CONTEXT_TTL_MS = 5 * 60_000 // 5 min — OAuth code lifetime
 const DEFERRED_SECRET_TTL_MS = 24 * 60 * 60_000 // 24 h — ignored one-tap cards
 
+// 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.
+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
 // when the flow completes. Users abandoning a flow (closing Telegram, losing
@@ -2024,9 +2062,29 @@ function isAutoFallbackCooldownActive(_agentName: string, now: number): boolean
 // 60-second sweep drops anything past its documented TTL.
 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)
   }
+  for (const [k, v] of pendingAuthAddFlows) {
+    if (now - v.startedAt > REAUTH_INTERCEPT_TTL_MS) {
+      cancelAccountAuthSession(v)
+      pendingAuthAddFlows.delete(k)
+    }
+  }
+  for (const [k, v] of awaitingAuthCodeAt) {
+    if (now - v > AUTH_CODE_CONTEXT_TTL_MS) awaitingAuthCodeAt.delete(k)
+  }
+  // Auth-refresh throttle entries decay quickly (5s window); sweep
+  // anything older than 60s so abandoned snapshot messages don't pin
+  // their key forever.
+  for (const [k, v] of lastAuthRefreshAtMs) {
+    if (now - v > 60_000) lastAuthRefreshAtMs.delete(k)
+  }
+  // /auth rm two-step confirm window — self-expires at `expiresAt`.
+  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)
   }
@@ -2036,9 +2094,6 @@ const pendingStateReaper = setInterval(() => {
   for (const [k, v] of vaultPassphraseCache) {
     if (now > v.expiresAt) vaultPassphraseCache.delete(k)
   }
-  for (const [k, v] of awaitingAuthCodeAt) {
-    if (now - v > AUTH_CODE_CONTEXT_TTL_MS) awaitingAuthCodeAt.delete(k)
-  }
   for (const [k, v] of deferredSecrets) {
     if (now - v.staged_at > DEFERRED_SECRET_TTL_MS) deferredSecrets.delete(k)
   }
@@ -2230,11 +2285,33 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   let renderedText: string
   let renderedKeyboard: ReturnType<typeof renderOperatorEvent>['keyboard'] | undefined
   if (modelUnavailable) {
+    // Two questions, asked synchronously to avoid the "card promises
+    // an announcement that never arrives" trap:
+    //   1. Is this a kind that AUTO-fallback can address?
+    //   2. Will the dispatcher actually fire (vs. dedup-drop)?
+    // Card text branches on the AND. wouldFireFleetAutoFallback is a
+    // pure read of the dedup state; calling fireFleetAutoFallback only
+    // when both are true keeps the card honest.
+    const isAutoKind =
+      modelUnavailable.kind === 'quota_exhausted' || modelUnavailable.kind === 'overload'
+    const willActuallyFire = isAutoKind && wouldFireFleetAutoFallback()
     process.stderr.write(
-      `telegram gateway: operator-event suppressing-raw-stderr-for-model-unavailable agent=${agent} kind=${kind} detected=${modelUnavailable.kind}\n`,
+      `telegram gateway: operator-event suppressing-raw-stderr-for-model-unavailable agent=${agent} kind=${kind} detected=${modelUnavailable.kind} autoKind=${isAutoKind} willFire=${willActuallyFire}\n`,
     )
-    renderedText = formatModelUnavailableCard(modelUnavailable, agent)
+    renderedText = formatModelUnavailableCard(modelUnavailable, agent, {
+      autoFallbackInFlight: willActuallyFire,
+    })
     renderedKeyboard = undefined
+    // Trigger fleet-wide auto-fallback. Pre-fix this branch only
+    // rendered the card; the fallback machinery was unreachable from
+    // here. We fire-and-forget so card delivery is never blocked on
+    // broker / API latency. The fallback's own announcement is sent
+    // separately with the causal-shape headline ("5-hour limit on
+    // ken" instead of generic "quota exhausted") — see
+    // auth-snapshot-format.ts → renderFallbackAnnouncement.
+    if (willActuallyFire) {
+      void fireFleetAutoFallback(agent)
+    }
   } else {
     try {
       const r = renderOperatorEvent(event)
@@ -2502,6 +2579,7 @@ silencePoke.startTimer({
     const text = silencePoke.formatFrameworkFallbackText(
       ctx.fallbackKind,
       ctx.silenceMs,
+      ctx.inFlightTools,
     )
     try {
       await robustApiCall(
@@ -2809,9 +2887,46 @@ const ipcServer: IpcServer = createIpcServer({
       const key = statusKey(currentTurn.sessionChatId, currentTurn.sessionThreadId)
       if (ev.kind === 'thinking') {
         silencePoke.noteThinking(key, Date.now())
-      } else if (ev.kind === 'tool_use' && (ev.toolName === 'Task' || ev.toolName === 'Agent')) {
-        // Built-in claude sub-agent dispatch — extends soft threshold to 5min.
-        silencePoke.noteSubagentDispatch(key)
+      } else if (ev.kind === 'tool_use') {
+        if (ev.toolName === 'Task' || ev.toolName === 'Agent') {
+          // Built-in claude sub-agent dispatch — extends soft threshold to 5min.
+          silencePoke.noteSubagentDispatch(key)
+        }
+        // #1292: track in-flight tool calls so the 300s framework
+        // fallback message can name the actual observable (e.g.
+        // "running Grep \"foo\" for 4m") instead of the dishonest
+        // generic "still working… no update in 5 min" when the agent
+        // is clearly busy on tool calls. Telegram-surface tools are
+        // excluded — their job IS the outbound message, the silence
+        // clock resets via noteOutbound when they fire. Sub-agent
+        // tool_use events (kind='sub_agent_tool_use') intentionally
+        // NOT tracked: the parent's Task tool_use is already on the
+        // map and represents the user-observable wait.
+        if (
+          ev.toolUseId != null
+          && ev.toolUseId.length > 0
+          && !isTelegramSurfaceTool(ev.toolName)
+        ) {
+          const label = toolLabel(
+            ev.toolName,
+            ev.input,
+            /*preamble*/ undefined,
+            ev.precomputedLabel,
+          )
+          silencePoke.noteToolStart(
+            key,
+            ev.toolUseId,
+            ev.toolName,
+            label.length > 0 ? label : null,
+            Date.now(),
+          )
+        }
+      } else if (ev.kind === 'tool_result') {
+        // #1292: drain the in-flight entry. Idempotent on unknown ids
+        // (covers Telegram-surface tools we skipped at start time).
+        if (ev.toolUseId != null && ev.toolUseId.length > 0) {
+          silencePoke.noteToolEnd(key, ev.toolUseId, Date.now())
+        }
       }
     }
   },
@@ -2948,6 +3063,69 @@ const ipcServer: IpcServer = createIpcServer({
    * Logs every fire so an operator can correlate the agent's
    * transcript turn against the scheduler's audit row by `prompt_key`.
    */
+  async onRequestDriveApproval(client: IpcClient, msg) {
+    // RFC E §4.2 Cut 2 — Drive-write PreToolUse hook is asking the
+    // gateway to post a diff-preview card so the user can decide.
+    await handleRequestDriveApproval(client, msg, {
+      agentName: getMyAgentName(),
+      loadAllowFrom: () => loadAccess().allowFrom,
+      loadTargetChat: () => {
+        const access = loadAccess()
+        const operator = access.allowFrom[0]
+        if (operator === undefined) return null
+        // For DM-paired setups the target chat IS the operator's
+        // user id. For group setups the gateway already has a topic
+        // routing surface (see how /folders posts) — this picks the
+        // DM path which is the common case; group-routing follow-up
+        // can extend this.
+        return { chatId: operator }
+      },
+      registerApproval: async (args) => {
+        const r = await kernelApprovalRequest({
+          agent_unit: args.agent_unit,
+          scope: args.scope,
+          action: args.action,
+          approver_set: args.approver_set,
+          why: args.why,
+          ttl_ms: args.ttl_ms,
+        })
+        if (r === null || r.state === 'rate_limited') return null
+        return {
+          request_id: r.request_id,
+          expires_at_ms: r.expires_at,
+        }
+      },
+      postCard: async (args) => {
+        try {
+          const sent = await robustApiCall(
+            () =>
+              bot.api.sendMessage(args.chatId, args.text, {
+                parse_mode: 'HTML',
+                ...(args.threadId !== undefined
+                  ? { message_thread_id: args.threadId }
+                  : {}),
+                reply_markup: args.replyMarkup as never,
+              }),
+            {
+              chat_id: String(args.chatId),
+              verb: 'drive-approval-card',
+              ...(args.threadId !== undefined ? { threadId: args.threadId } : {}),
+            },
+          )
+          return { messageId: (sent as { message_id: number }).message_id }
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: drive-approval postCard failed: ${(err as Error).message}\n`,
+          )
+          return null
+        }
+      },
+      buildCard: ({ preview, suggestRequestId }) =>
+        buildDiffPreviewCard({ preview, suggestRequestId }),
+      log: (m) => process.stderr.write(`telegram gateway: drive-approval — ${m}\n`),
+    })
+  },
+
   onInjectInbound(_client: IpcClient, msg: InjectInboundMessage) {
     const promptKey = typeof msg.inbound.meta?.prompt_key === 'string'
       ? msg.inbound.meta.prompt_key
@@ -4627,6 +4805,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           gatewayReceiveAt: startedAt,
           replyCalled: false,
           capturedText: [],
+          capturedTextLenAtLastReply: 0,
           orphanedReplyTimeoutId: null,
           registryKey: null,
           lastAssistantMsgId: null,
@@ -4723,6 +4902,12 @@ function handleSessionEvent(ev: SessionEvent): void {
       // placeholder-heartbeat label, which has been retired.
       if (isTelegramReplyTool(name)) {
         turn.replyCalled = true
+        // #1291: pin the captured-text index at the moment of this reply
+        // tool call. Anything pushed into capturedText after this point
+        // is the post-reply tail (e.g. the substantive answer composed
+        // in terminal text after a soft-commit "on it, back in a few").
+        // decideTurnFlush slices from this index to flush the tail.
+        turn.capturedTextLenAtLastReply = turn.capturedText.length
         if (turn.orphanedReplyTimeoutId != null) {
           clearTimeout(turn.orphanedReplyTimeoutId)
           turn.orphanedReplyTimeoutId = null
@@ -4982,8 +5167,20 @@ function handleSessionEvent(ev: SessionEvent): void {
         chatId: turn.sessionChatId,
         replyCalled: turn.replyCalled,
         capturedText: turn.capturedText,
+        capturedTextLenAtLastReply: turn.capturedTextLenAtLastReply,
         flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
       })
+      // #1291: when the model emitted a soft-commit reply followed by a
+      // substantive terminal-only answer, decideTurnFlush returns
+      // kind:'flush' with the post-reply tail. Log WARN so this case is
+      // auditable — the model SHOULD have called reply for the tail, but
+      // didn't, and the framework is covering for it.
+      if (flushDecision.kind === 'flush' && turn.replyCalled) {
+        process.stderr.write(
+          `telegram gateway: WARN post-reply-tail flush (#1291) — model emitted ${flushDecision.text.length} chars after a prior reply call without a follow-up reply tool` +
+          ` chat=${chatId} turnStartedAt=${turn.startedAt}\n`,
+        )
+      }
       if (flushDecision.kind === 'skip' && flushDecision.reason !== 'reply-called') {
         process.stderr.write(
           `telegram gateway: turn-flush skipped — reason=${flushDecision.reason}\n`,
@@ -5133,6 +5330,21 @@ function handleSessionEvent(ev: SessionEvent): void {
         // backup; reset the preamble buffer (its content is already in
         // the captured `capturedText`, which turn-flush is about to send).
         preambleSuppressor.dropNow()
+        // #1289 fix — drain silence-poke + signal-tracker state for this
+        // turn. The three sibling turn_end exit branches (context-exhaust
+        // at ~5098, silent-marker at ~5097-5098, default reply-called tail
+        // at ~5348-5349) all call signalTracker.clear + silencePoke.endTurn.
+        // The flush-backstop branch was retrofitted in #1067 to null
+        // currentTurn early but never had this cleanup added — leaving the
+        // silence-poke state in the Map, so 300s after the original turn
+        // start the framework fallback fires and the user sees
+        // "still working… (no update from agent in 5 min)" on a turn the
+        // gateway already considers over.
+        {
+          const tKey = statusKey(chatId, threadId)
+          signalTracker.clear(tKey)
+          silencePoke.endTurn(tKey)
+        }
 
         void (async () => {
           await new Promise<void>(resolve => setTimeout(resolve, 500))
@@ -5942,6 +6154,60 @@ async function handleInbound(
     return
   }
 
+  // `/auth add` paste-back intercept — sibling to pendingReauthFlows.
+  // Both intercepts are deliberate so the LLM never sees the OAuth
+  // code (it doesn't need to + plaintext OAuth in chat history is bad
+  // hygiene). The add-flow intercept comes first because /auth add
+  // creates fresh credentials at the broker layer, vs /reauth which
+  // mutates an existing agent's slot — different success paths.
+  const pendingAdd = pendingAuthAddFlows.get(chat_id)
+  if (pendingAdd && looksLikeAuthCode(text)) {
+    const elapsed = Date.now() - pendingAdd.startedAt
+    if (elapsed < REAUTH_INTERCEPT_TTL_MS) {
+      pendingAuthAddFlows.delete(chat_id)
+      try {
+        const credentials = await submitAccountAuthCode(pendingAdd, text.trim())
+        try {
+          await addAccountViaBroker(pendingAdd.label, credentials, { replace: false })
+          // success — wipe scratch dir now that the broker owns the creds
+          cleanAuthAddScratchDir(pendingAdd.scratchDir)
+          await switchroomReply(
+            ctx,
+            `✓ Account <code>${escapeHtmlForTg(pendingAdd.label)}</code> added.\n` +
+              `The fleet's active account hasn't changed. Send ` +
+              `<code>/auth use ${escapeHtmlForTg(pendingAdd.label)}</code> to switch to it.`,
+            { html: true },
+          )
+        } catch (brokerErr) {
+          // Broker rejected (e.g. label already exists). Wipe scratch
+          // either way — the credentials are useless without broker
+          // bookkeeping.
+          cleanAuthAddScratchDir(pendingAdd.scratchDir)
+          await switchroomReply(
+            ctx,
+            `<b>/auth add failed at broker:</b> ${escapeHtmlForTg((brokerErr as Error)?.message ?? String(brokerErr))}`,
+            { html: true },
+          )
+        }
+      } catch (err) {
+        // submitAccountAuthCode wiped the scratch dir on its own
+        // failure paths (timeout, child exit, stdin broken).
+        await switchroomReply(
+          ctx,
+          `<b>/auth add code failed:</b> ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`,
+          { html: true },
+        )
+      }
+      // Redact the OAuth code paste from chat history (#488).
+      redactAuthCodeMessage(bot.api as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+      return
+    }
+    // Stale — drop the pending entry but let the message fall through
+    // to other intercepts (defensively wipe scratch).
+    cancelAccountAuthSession(pendingAdd)
+    pendingAuthAddFlows.delete(chat_id)
+  }
+
   // Auth-code intercept
   const pendingReauth = pendingReauthFlows.get(chat_id)
   if (pendingReauth && looksLikeAuthCode(text)) {
@@ -6982,6 +7248,11 @@ export function _resetDockerReachableCache(): void {
   _dockerReachable = undefined
 }
 
+// hostd dispatch lives in `hostd-dispatch.ts` (extracted for testability).
+// Re-export the cache-reset so existing test patterns that reach into
+// gateway.ts for `_resetDockerReachableCache` find a parallel hook.
+export { _resetHostdEnabledCache }
+
 function spawnSwitchroomDetached(
   args: string[],
   onFailure?: (info: { code: number; tail: string }) => void,
@@ -7318,6 +7589,75 @@ async function executeVaultOp(ctx: Context, chatId: string, op: 'list' | 'get' |
   }
 }
 
+/**
+ * Dispatch a short-running verb (agent_start, agent_stop, cross-agent
+ * agent_restart) through hostd when available, else fall back to the
+ * legacy in-container CLI shell-out.
+ *
+ * Why: on docker-mode hosts the agent container has no docker binary,
+ * so the legacy `runSwitchroomCommand` path silently exits 127 for any
+ * verb that touches compose (RFC C §1, #926). Hostd runs on the host
+ * with the docker socket mounted, so the verb actually works.
+ *
+ * Result handling:
+ *   - `not-configured` → fall back to {@link runSwitchroomCommand}.
+ *     (Operator opted out; let the legacy path's existing error
+ *     surfacing handle the exit-127 case.)
+ *   - `completed` → reply with the stdout tail (mirrors the legacy
+ *     path's formatted-output reply).
+ *   - `started`   → reply with a brief "🔄 dispatched" ack. Verbs that
+ *     return `started` (agent_restart) finish asynchronously on the
+ *     daemon; the audit log is the canonical record.
+ *   - `error` / `denied` → reply with the error tail inline. No
+ *     fallback (RFC §7 hard-fail contract — operator opted in).
+ */
+async function dispatchShortVerbViaHostd(
+  ctx: Context,
+  req: HostdRequest,
+  label: string,
+  legacyArgs: string[],
+): Promise<void> {
+  const hostdResp = await tryHostdDispatch(getMyAgentName(), req)
+  if (hostdResp === 'not-configured') {
+    warnLegacySpawnIfHostdDisabled(req.op)
+    await runSwitchroomCommand(ctx, legacyArgs, label)
+    return
+  }
+  if (hostdResp.result === 'completed') {
+    const body = hostdResp.stdout_tail?.trim() || `${label}: done (exit ${hostdResp.exit_code})`
+    const formatted = formatSwitchroomOutput(stripAnsi(body))
+    if (formatted) {
+      await switchroomReply(ctx, preBlock(formatted), { html: true })
+    } else {
+      await switchroomReply(ctx, `${label}: done (no output)`)
+    }
+    return
+  }
+  if (hostdResp.result === 'started') {
+    await switchroomReply(
+      ctx,
+      `🔄 <b>${escapeHtmlForTg(label)}</b> dispatched via hostd ` +
+        `(request_id=<code>${escapeHtmlForTg(hostdResp.request_id)}</code>). ` +
+        `Check audit log for completion.`,
+      { html: true },
+    )
+    return
+  }
+  // error / denied — surface inline. RFC §7 hard-fail: no spawn fallback.
+  const errBody =
+    hostdResp.error ??
+    hostdResp.stderr_tail ??
+    hostdResp.stdout_tail ??
+    '(no error tail returned)'
+  await switchroomReply(
+    ctx,
+    `❌ <b>${escapeHtmlForTg(label)} failed via hostd</b> ` +
+      `(result=${escapeHtmlForTg(hostdResp.result)}):\n` +
+      preBlock(stripAnsi(errBody)),
+    { html: true },
+  )
+}
+
 async function runSwitchroomCommand(ctx: Context, args: string[], label: string): Promise<void> {
   try {
     const output = stripAnsi(switchroomExec(args))
@@ -7364,7 +7704,7 @@ function renderAuthCodeOutcome(outcome: AuthCodeOutcome | null | undefined): str
     case 'pane-not-ready':
       return `Auth pane not ready — tap <b>Retry</b>.`
     case 'timeout':
-      return `Still waiting after 2 min — tap <b>Retry</b> or check <code>switchroom auth status</code>.${tail}`
+      return `Still waiting after 2 min — tap <b>Retry</b> or check <code>switchroom auth list</code>.${tail}`
   }
 }
 
@@ -7550,9 +7890,13 @@ function buildAgentAudit(agentName: string): AgentAudit | undefined {
 }
 
 // Build an AgentMetadata snapshot for the current agent by shelling out
-// to `switchroom agent list --json` and `switchroom auth status --json`.
+// to `switchroom agent list --json` and `switchroom auth show --json`.
 // Best-effort — any missing piece renders as a placeholder in the text
-// templates rather than blocking the reply.
+// templates rather than blocking the reply. RFC H retired the per-agent
+// `auth status --json` shape; auth state is now derived from the
+// broker's fleet-wide `ListStateData` payload via
+// `buildAuthSummaryFromBroker`, with billingType pulled from the
+// agent's `.claude.json` (the broker doesn't track plan tier).
 async function buildAgentMetadata(agentName: string): Promise<AgentMetadata> {
   type AgentListResp = {
     agents: Array<{
@@ -7562,24 +7906,22 @@ async function buildAgentMetadata(agentName: string): Promise<AgentMetadata> {
       model?: string | null;
     }>
   }
-  type AuthStatusResp = {
-    agents: Array<{
-      name: string; authenticated: boolean; auth_source: string | null;
-      subscription_type: string | null; expires_in: string | null;
-    }>
-  }
   const list = switchroomExecJson<AgentListResp>(['agent', 'list'])
-  const auth = switchroomExecJson<AuthStatusResp>(['auth', 'status'])
+  const brokerState = switchroomExecJson<BrokerStateView>(['auth', 'show'])
   const a = list?.agents?.find(x => x.name === agentName) ?? null
-  const au = auth?.agents?.find(x => x.name === agentName) ?? null
-  const authSummary: AuthSummary | null = au
-    ? {
-        authenticated: au.authenticated,
-        subscription_type: au.subscription_type,
-        expires_in: au.expires_in,
-        auth_source: au.auth_source,
-      }
-    : null
+  let claudeJson: ClaudeJsonView | null = null
+  try {
+    const agentDir = resolveAgentDirFromEnv()
+    if (agentDir) {
+      const raw = readFileSync(join(agentDir, '.claude', '.claude.json'), 'utf8')
+      claudeJson = JSON.parse(raw) as ClaudeJsonView
+    }
+  } catch { /* leave null — billingType becomes null in the summary */ }
+  const authSummary: AuthSummary | null = buildAuthSummaryFromBroker(
+    brokerState,
+    agentName,
+    claudeJson,
+  )
   return {
     agentName,
     model: a?.model ?? null,
@@ -7724,14 +8066,24 @@ bot.command('agentstart', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const name = ctx.match?.trim() || getMyAgentName()
   try { assertSafeAgentName(name) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
-  await runSwitchroomCommand(ctx, ['agent', 'start', name], `start ${name}`)
+  await dispatchShortVerbViaHostd(
+    ctx,
+    { v: 1, op: 'agent_start', request_id: hostdRequestId('gw-start'), args: { name } },
+    `start ${name}`,
+    ['agent', 'start', name],
+  )
 })
 
 bot.command('stop', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const name = ctx.match?.trim() || getMyAgentName()
   try { assertSafeAgentName(name) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
-  await runSwitchroomCommand(ctx, ['agent', 'stop', name], `stop ${name}`)
+  await dispatchShortVerbViaHostd(
+    ctx,
+    { v: 1, op: 'agent_stop', request_id: hostdRequestId('gw-stop'), args: { name } },
+    `stop ${name}`,
+    ['agent', 'stop', name],
+  )
 })
 
 bot.command('restart', async ctx => {
@@ -7771,13 +8123,52 @@ bot.command('restart', async ctx => {
     // of whatever reason the downstream CLI would default to.
     stampUserRestartReason('user: /restart from chat')
     await sweepBeforeSelfRestart()
-    spawnSwitchroomDetached(
-      ['agent', 'restart', name, '--force'],
-      notifyDetachedFailure(chatId, threadId ?? null, `restart ${name}`),
+    const hostdResp = await tryHostdDispatch(getMyAgentName(), {
+      v: 1,
+      op: 'agent_restart',
+      request_id: hostdRequestId('gw-restart'),
+      args: { name, force: true, reason: 'user: /restart from chat' },
+    })
+    if (hostdResp === 'not-configured') {
+      warnLegacySpawnIfHostdDisabled('agent_restart')
+      spawnSwitchroomDetached(
+        ['agent', 'restart', name, '--force'],
+        notifyDetachedFailure(chatId, threadId ?? null, `restart ${name}`),
+      )
+      return
+    }
+    if (hostdResp.result === 'started' || hostdResp.result === 'completed') {
+      // Dispatched via hostd. The recreate will kill this gateway
+      // shortly; the new gateway reads the marker and edits the ack.
+      return
+    }
+    // hostd was attempted but errored/denied — clear marker and surface.
+    clearRestartMarker()
+    await switchroomReply(
+      ctx,
+      `❌ <b>restart ${escapeHtmlForTg(name)} failed via hostd</b> ` +
+        `(result=${escapeHtmlForTg(hostdResp.result)}):\n` +
+        preBlock(hostdResp.error ?? '(no error message)'),
+      { html: true },
     )
     return
   }
-  await runSwitchroomCommand(ctx, ['agent', 'restart', name], `restart ${name}`)
+  // Cross-agent /restart <other>. Same hostd-first shape as self-target,
+  // but no restart marker / no self-kill: another agent's container is
+  // about to bounce, not ours. The daemon spawns the work and returns
+  // "started" (per handleAgentRestart at server.ts:466), so the user
+  // sees a brief dispatch ack and the audit log carries the outcome.
+  await dispatchShortVerbViaHostd(
+    ctx,
+    {
+      v: 1,
+      op: 'agent_restart',
+      request_id: hostdRequestId('gw-restart-cross'),
+      args: { name, force: true, reason: `user: /restart ${name} from chat` },
+    },
+    `restart ${name}`,
+    ['agent', 'restart', name],
+  )
 })
 
 // ─── /new and /reset ──────────────────────────────────────────────────────
@@ -7889,9 +8280,30 @@ async function handleNewOrResetCommand(ctx: Context, kind: 'new' | 'reset'): Pro
   // /new" / "user: /reset" rather than the downstream CLI default.
   stampUserRestartReason(`user: /${kind} from chat`)
   await sweepBeforeSelfRestart()
-  spawnSwitchroomDetached(
-    ['agent', 'restart', name, '--force'],
-    notifyDetachedFailure(chatId, threadId ?? null, `${kind} ${name}`),
+  const hostdResp = await tryHostdDispatch(getMyAgentName(), {
+    v: 1,
+    op: 'agent_restart',
+    request_id: hostdRequestId(`gw-${kind}`),
+    args: { name, force: true, reason: `user: /${kind} from chat` },
+  })
+  if (hostdResp === 'not-configured') {
+    warnLegacySpawnIfHostdDisabled('agent_restart')
+    spawnSwitchroomDetached(
+      ['agent', 'restart', name, '--force'],
+      notifyDetachedFailure(chatId, threadId ?? null, `${kind} ${name}`),
+    )
+    return
+  }
+  if (hostdResp.result === 'started' || hostdResp.result === 'completed') {
+    return
+  }
+  clearRestartMarker()
+  await switchroomReply(
+    ctx,
+    `❌ <b>${escapeHtmlForTg(kind)} ${escapeHtmlForTg(name)} failed via hostd</b> ` +
+      `(result=${escapeHtmlForTg(hostdResp.result)}):\n` +
+      preBlock(hostdResp.error ?? '(no error message)'),
+    { html: true },
   )
 }
 
@@ -7947,22 +8359,23 @@ bot.command('update', async ctx => {
   // container, which has the switchroom CLI baked in but no docker
   // binary and no /var/run/docker.sock mount. So `switchroom update`'s
   // pull-images and recreate-containers steps would fail with
-  // "docker: command not found". Without this guard, the operator
-  // sees an opaque "❌ update failed (exit 127)" via
-  // notifyDetachedFailure ~5s after the ack.
+  // "docker: command not found".
   //
-  // Surface a clean explanation instead, pointing them at the host
-  // CLI as the working path. /update (dry-run) does NOT need docker
-  // and is unaffected — only /update apply.
-  if (!isDockerReachable()) {
+  // BYPASSED when hostd is on (#1175 Phase 2 RFC C): hostd runs on the
+  // host with the docker socket mounted, so the in-container docker
+  // dependency goes away. Skip the guard so /update apply can dispatch
+  // through hostd. When hostd is NOT in play, keep the guard so the
+  // operator gets a clean explanation instead of an opaque exit-127.
+  if (!hostdWillBeUsed(getMyAgentName()) && !isDockerReachable()) {
     await switchroomReply(
       ctx,
       `❌ <b>/update apply</b> needs docker access from inside the agent ` +
       `container, but it's not available (no <code>docker</code> binary on ` +
       `PATH, no <code>/var/run/docker.sock</code> mount).\n\n` +
-      `On docker installs, run <code>switchroom update</code> from the ` +
-      `host shell instead.\n\n` +
-      `<i>Tracked as #926 — host-side update daemon would close this gap.</i>`,
+      `On docker installs, either run <code>switchroom update</code> from ` +
+      `the host shell, or enable <code>host_control.enabled</code> in ` +
+      `<code>switchroom.yaml</code> and <code>switchroom hostd install</code> ` +
+      `so this verb dispatches through the host-side daemon.`,
       { html: true },
     )
     return
@@ -8036,9 +8449,94 @@ bot.command('update', async ctx => {
   // pinned-progress-card surface is the headline feature per CLAUDE.md;
   // leaving one pinned across the recreate would surprise the operator.
   await sweepBeforeSelfRestart()
-  spawnSwitchroomDetached(
-    ['update', ...passthrough],
-    notifyDetachedFailure(chatId, threadId ?? null, 'update'),
+  const skipImages = passthrough.includes('--skip-images')
+  const rebuild = passthrough.includes('--rebuild')
+  const updateRequestId = hostdRequestId('gw-update')
+  const hostdResp = await tryHostdDispatch(getMyAgentName(), {
+    v: 1,
+    op: 'update_apply',
+    request_id: updateRequestId,
+    args: {
+      ...(skipImages ? { skip_images: true } : {}),
+      ...(rebuild ? { rebuild: true } : {}),
+    },
+  })
+  if (hostdResp === 'not-configured') {
+    warnLegacySpawnIfHostdDisabled('update_apply')
+    spawnSwitchroomDetached(
+      ['update', ...passthrough],
+      notifyDetachedFailure(chatId, threadId ?? null, 'update'),
+    )
+    return
+  }
+  if (hostdResp.result === 'completed') {
+    return
+  }
+  if (hostdResp.result === 'started') {
+    // RFC C §5.3: long-running mutation. Poll get_status until terminal
+    // or until the recreate kills this gateway (whichever happens first).
+    // The success signal is the post-restart greeting card edited into
+    // ackId via the restart marker. The poll is here so that
+    // *fail-before-recreate* (image pull error, scaffold regen crash)
+    // doesn't leave the operator staring at the orphan "🚀 update started"
+    // ack indefinitely. Live repro: PR #1305.
+    void (async () => {
+      // 60s budget: RFC C §5.3 specs `apply` at 30s and `update_apply`
+      // at 60s. Image pulls + scaffold regeneration dominate the wall
+      // clock for update_apply, hence the larger budget. The poll
+      // resolves earlier on any terminal state from the daemon.
+      const terminal = await pollHostdStatus(getMyAgentName(), updateRequestId, {
+        timeoutMs: 60_000,
+      })
+      if (terminal === 'not-configured') return
+      // completed → recreate is about to run / has run; let the post-
+      // restart greeting card handle the success message.
+      if (terminal.result === 'completed') return
+      // Anything else means the daemon's mutation failed before it could
+      // kill us. Edit the ack to surface the tail and clear the marker
+      // so the next gateway boot doesn't render a false success card.
+      clearRestartMarker()
+      const errBody =
+        terminal.error ??
+        terminal.stderr_tail ??
+        terminal.stdout_tail ??
+        '(no error tail returned)'
+      const editedText =
+        `🚀 <b>update started</b> — <b>FAILED</b> via hostd ` +
+        `(result=${escapeHtmlForTg(terminal.result)}):\n` +
+        preBlock(errBody)
+      if (ackId != null) {
+        try {
+          await robustApiCall(
+            () =>
+              lockedBot.api.editMessageText(chatId, ackId!, editedText, {
+                parse_mode: 'HTML',
+                link_preview_options: { is_disabled: true },
+              }),
+            { verb: 'update.poll.editAck' },
+          )
+        } catch {
+          // edit-failed (message deleted, parse error) — fall back to
+          // a fresh reply so the failure isn't silent.
+          try {
+            await switchroomReply(ctx, editedText, { html: true })
+          } catch {}
+        }
+      } else {
+        try {
+          await switchroomReply(ctx, editedText, { html: true })
+        } catch {}
+      }
+    })()
+    return
+  }
+  clearRestartMarker()
+  await switchroomReply(
+    ctx,
+    `❌ <b>/update apply failed via hostd</b> ` +
+      `(result=${escapeHtmlForTg(hostdResp.result)}):\n` +
+      preBlock(hostdResp.error ?? '(no error message)'),
+    { html: true },
   )
 })
 
@@ -8066,6 +8564,81 @@ bot.command('upgrade', async ctx => {
   )
 })
 
+// /audit hostd — tail/filter the hostd audit log. Mirrors `/vault audit`
+// in spirit (operator observability over a privileged subsystem from any
+// admin DM). Admin-gated via ADMIN_COMMAND_NAMES. Reads the audit JSONL
+// at ~/.switchroom/host-control-audit.log directly — no hostd RPC needed
+// because the file is shared via the host bind mount on docker installs.
+bot.command('audit', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  const arg = (ctx.match ?? '').trim()
+  if (arg === '' || arg === 'help' || arg === '--help') {
+    await switchroomReply(
+      ctx,
+      'Usage: <code>/audit hostd [--tail N] [--agent &lt;name&gt;] [--op &lt;verb&gt;] [--error]</code>',
+      { html: true },
+    )
+    return
+  }
+  const tokens = arg.split(/\s+/)
+  const sub = tokens[0]
+  if (sub !== 'hostd') {
+    await switchroomReply(
+      ctx,
+      `Unknown audit target <code>${escapeHtmlForTg(sub ?? '')}</code>. ` +
+      `Supported: <code>hostd</code>.`,
+      { html: true },
+    )
+    return
+  }
+  // Build the CLI argv for switchroom hostd audit. Validate each
+  // operator-supplied value to keep argv injection out of the picture.
+  const ALLOWED_OPS = new Set([
+    'agent_start', 'agent_stop', 'agent_restart', 'apply',
+    'update_check', 'update_apply', 'update_status', 'upgrade_status',
+    'get_status', 'doctor', 'fleet_state',
+  ])
+  const argv: string[] = ['hostd', 'audit']
+  for (let i = 1; i < tokens.length; i++) {
+    const t = tokens[i]!
+    if (t === '--error') { argv.push('--error'); continue }
+    if (t === '--tail' || t === '--agent' || t === '--op') {
+      const v = tokens[++i]
+      if (v == null) {
+        await switchroomReply(ctx, `Flag <code>${t}</code> requires a value.`, { html: true })
+        return
+      }
+      if (t === '--tail' && !/^[0-9]{1,4}$/.test(v)) {
+        await switchroomReply(ctx, `<code>--tail</code> must be an integer (1-9999).`, { html: true })
+        return
+      }
+      if (t === '--agent' && !/^[a-z][a-z0-9-]{0,62}$/i.test(v)) {
+        await switchroomReply(ctx, `<code>--agent</code> name has an invalid shape.`, { html: true })
+        return
+      }
+      if (t === '--op' && !ALLOWED_OPS.has(v)) {
+        await switchroomReply(
+          ctx,
+          `Unknown hostd verb <code>${escapeHtmlForTg(v)}</code>. ` +
+          `Known: ${[...ALLOWED_OPS].sort().map(o => `<code>${o}</code>`).join(', ')}.`,
+          { html: true },
+        )
+        return
+      }
+      argv.push(t, v)
+      continue
+    }
+    await switchroomReply(
+      ctx,
+      `Unknown flag <code>${escapeHtmlForTg(t)}</code>. ` +
+      `Allowed: <code>--tail</code>, <code>--agent</code>, <code>--op</code>, <code>--error</code>.`,
+      { html: true },
+    )
+    return
+  }
+  await runSwitchroomCommand(ctx, argv, `hostd audit${argv.length > 2 ? ' …' : ''}`)
+})
+
 // ─── /approve, /deny, /pending ────────────────────────────────────────────
 // Slash-command alternatives to the inline-button approval flow (useful for
 // desktop-only sessions and power-users). Share pendingPermissions state
@@ -8129,6 +8702,59 @@ async function handlePermissionSlash(ctx: Context, behavior: 'allow' | 'deny'):
 bot.command('approve', async ctx => handlePermissionSlash(ctx, 'allow'))
 bot.command('deny', async ctx => handlePermissionSlash(ctx, 'deny'))
 
+// ─── Drive folder picker (RFC E §4.1) ───────────────────────────────────
+// /folders — post a Telegram picker card listing this agent's top-level
+// Drive folders. Tap [Allow] on a folder to grant the agent
+// allow_always at doc:gdrive:folder/<id>/**; tap [Browse] to drill in.
+//
+// Authorisation: same dmCommandGate as the other operator slash
+// commands — only allowFrom users can post-trigger.
+
+const folderPickerCache = new FolderListCache()
+
+function buildFolderPickerDeps(): FolderPickerHandlerDeps {
+  const agentName = getMyAgentName()
+  return {
+    agentName,
+    cache: folderPickerCache,
+    fetchPage: async ({ parent_id, page_token }) => {
+      const handle = await loadFromAuthBroker()
+      if (handle === null) {
+        throw new Error(
+          `auth-broker unreachable for agent ${agentName} — is the broker container running?`,
+        )
+      }
+      return fetchFolderPage({
+        access_token: handle.access_token,
+        ...(parent_id !== undefined ? { parent_id } : {}),
+        ...(page_token !== undefined ? { page_token } : {}),
+      })
+    },
+    approvalRequest: async (args) => {
+      const r = await kernelApprovalRequest({
+        agent_unit: args.agent_unit,
+        scope: args.scope,
+        action: args.action,
+        approver_set: args.approver_set,
+        ...(args.why !== null && args.why !== undefined ? { why: args.why } : {}),
+        ...(args.ttl_ms !== null && args.ttl_ms !== undefined ? { ttl_ms: args.ttl_ms } : {}),
+      })
+      if (r === null || r.state === 'rate_limited') return null
+      return { request_id: r.request_id }
+    },
+    approvalConsume: async (id) => {
+      const r = await kernelApprovalConsume(id)
+      return r !== null && r.consumed
+    },
+    approvalRecord: async (args) => kernelApprovalRecord(args),
+  }
+}
+
+bot.command('folders', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  await handleFoldersCommand(ctx, buildFolderPickerDeps())
+})
+
 // /pending — list current pending permission prompts with their ids, so the
 // user can target a specific one via /approve <id> or /deny <id>.
 // Restricted to access.allowFrom DMs to match /approve and /deny — it
@@ -8160,16 +8786,12 @@ bot.command('interrupt', async ctx => {
   await runSwitchroomCommand(ctx, ['agent', 'interrupt', name], `interrupt ${name}`)
 })
 
-// Shared auto-fallback state. `lockout` is a per-process in-memory
-// guard against rapid re-fire between the scheduled poll and any
-// manual trigger (see telegram-plugin/auto-fallback.ts).
-//
-// Pre-#417 fix this was always emptyLockout() at process start, so a
-// gateway restart inside the cooldown window reset the timer and a
-// quota-flap on the recovering slot could re-trigger fallback the
-// moment the gateway came back. We now seed from disk on first use
-// and persist on every transition. Errors are swallowed: losing the
-// lockout file just degrades to in-memory-only behaviour.
+// Persist-ops bundle for the legacy auto-fallback lockout file. The
+// only remaining reader is `isAutoFallbackCooldownActive` (line ~2030)
+// — used by the pending-restart drain cap to defer a forced restart
+// stacking on top of an in-flight slot rotation. The legacy poller
+// that USED to write this file was retired alongside this refactor;
+// existing on-disk lockouts age out via DEFAULT_FALLBACK_COOLDOWN_MS.
 const lockoutOps: LockoutPersistOps = {
   readFileSync: (p, enc) => readFileSync(p, enc),
   writeFileSync: (p, data, opts) => writeFileSync(p, data, opts),
@@ -8177,24 +8799,6 @@ const lockoutOps: LockoutPersistOps = {
   mkdirSync: (p, opts) => mkdirSync(p, opts),
   joinPath: (...parts) => join(...parts),
 }
-let autoFallbackLockout: LockoutRecord = emptyLockout()
-let autoFallbackLockoutSeeded = false
-function seedAutoFallbackLockoutIfNeeded(agentDir: string): void {
-  if (autoFallbackLockoutSeeded) return
-  autoFallbackLockoutSeeded = true
-  try {
-    autoFallbackLockout = loadLockout(agentDir, lockoutOps)
-  } catch (err) {
-    process.stderr.write(`telegram gateway: auto-fallback lockout seed failed (using empty): ${(err as Error).message}\n`)
-  }
-}
-function persistLockout(agentDir: string): void {
-  try {
-    saveLockout(agentDir, autoFallbackLockout, lockoutOps)
-  } catch (err) {
-    process.stderr.write(`telegram gateway: auto-fallback lockout persist failed: ${(err as Error).message}\n`)
-  }
-}
 
 // Pinned slot-banner state (#421). One banner per gateway process,
 // in the owner chat (access.allowFrom[0]). Per-topic forum support
@@ -8225,91 +8829,123 @@ async function refreshPinnedBanner(reason: string): Promise<void> {
   }
 }
 
-type AutoFallbackCheckResult =
-  | { kind: 'no-action'; reason: string; decision: 'noop' | 'fallback-skipped' }
-  | { kind: 'executed'; previousSlot: string; newSlot: string }
-  | { kind: 'exhausted-all'; activeSlot: string }
-  | { kind: 'error'; message: string }
+/**
+ * Re-entry guard + dedup window for `fireFleetAutoFallback`. The state
+ * was lifted into `fleet-fallback-gate.ts` so it can be tested in
+ * isolation (gateway.ts module state was unreachable from vitest). The
+ * gate ALSO enforces the broker-reachability honesty contract: when the
+ * broker is down, `wouldFire()` returns false so the model-unavailable
+ * card stays honest instead of advertising a swap that would bail with
+ * `reason=no-broker-client`.
+ */
+const FLEET_FALLBACK_DEDUP_MS = 30_000
+
+/** Synchronous reachability check for the auth-broker UDS. Used by the
+ *  fleet-fallback gate to keep the model-unavailable card honest: if the
+ *  broker socket isn't bound, the dispatcher would bail with
+ *  `reason=no-broker-client`, so `wouldFire()` should return false and
+ *  the card should fall back to the manual `/auth use <label>` hint. */
+function isAuthBrokerSocketReachable(): boolean {
+  try {
+    return existsSync(resolveAuthBrokerSocketPath())
+  } catch {
+    return false
+  }
+}
+
+const fleetFallbackGate = createFleetFallbackGate({
+  dedupMs: FLEET_FALLBACK_DEDUP_MS,
+  brokerReachable: isAuthBrokerSocketReachable,
+})
+
+function wouldFireFleetAutoFallback(): boolean {
+  return fleetFallbackGate.wouldFire()
+}
+
+/**
+ * Fleet-wide auto-fallback dispatcher (RFC H follow-up).
+ *
+ * Wired from the model-unavailable card render path so a quota-out
+ * event on ANY agent immediately triggers a fleet-wide swap (via
+ * broker.setActive — same path /auth use takes), not the per-agent
+ * legacy `runAutoFallbackCheck`. Pre-fix, the card path never called
+ * any fallback machinery; the scheduled poller (60-min interval, only
+ * fires on utilization headers) was the only trigger and missed
+ * hard-rejection events.
+ *
+ * Concurrency: collapses concurrent triggers via the in-flight
+ * promise above. Subsequent calls within `FLEET_FALLBACK_DEDUP_MS` of
+ * a recent fire are dropped silently — the broadcast announcement is
+ * the user-visible signal that the swap happened, no need to repeat.
+ *
+ * Fire-and-forget: never throws into the caller's flow. Posts the
+ * causal-shape announcement to every chat in `loadAccess().allowFrom`
+ * so the user sees the outcome inline with the original "Model
+ * unavailable" card.
+ */
+async function fireFleetAutoFallback(triggerAgent: string): Promise<void> {
+  return fleetFallbackGate.fire(
+    () => doFireFleetAutoFallback(triggerAgent),
+    (err) => {
+      process.stderr.write(
+        `telegram gateway: [fleet-fallback] error agent=${triggerAgent}: ${(err as Error)?.message ?? err}\n`,
+      )
+    },
+  )
+}
 
-async function runAutoFallbackCheck(opts: { trigger: 'scheduled' | 'manual' }): Promise<AutoFallbackCheckResult> {
-  // All log lines in this path use the `[autofallback]` tag so a single
-  // grep against journalctl reconstructs the full decision history of
-  // a slot rotation: `journalctl -u switchroom-<agent>-gateway -g autofallback`.
+/** Returns true iff the dispatcher actually performed a swap (and the
+ *  user-visible announcement was broadcast). False on no-op /
+ *  error / idempotent-skip — caller uses this to decide whether to
+ *  arm the post-fire suppression window. */
+async function doFireFleetAutoFallback(triggerAgent: string): Promise<boolean> {
   try {
-    const agentDir = resolveAgentDirFromEnv()
-    if (!agentDir) {
-      return { kind: 'no-action', reason: 'no agent dir', decision: 'noop' }
-    }
-    const agentName = getMyAgentName()
-    seedAutoFallbackLockoutIfNeeded(agentDir)
-    const active = currentActiveSlot(agentDir)
-    const quota = await fetchQuota({ claudeConfigDir: join(agentDir, '.claude') })
-    const decision = evaluateFallbackTrigger({
-      quota,
-      activeSlot: active,
-      now: Date.now(),
-      lockout: autoFallbackLockout,
-    })
-    if (decision.action !== 'fallback') {
+    const client = await getAuthBrokerClient(triggerAgent)
+    if (!client) {
       process.stderr.write(
-        `telegram gateway: [autofallback] noop trigger=${opts.trigger} agent=${agentName} active=${active ?? 'none'} reason=${decision.reason}\n`,
+        `telegram gateway: [fleet-fallback] skipped agent=${triggerAgent} reason=no-broker-client\n`,
       )
-      return { kind: 'no-action', reason: decision.reason, decision: 'noop' }
+      return false
     }
-    process.stderr.write(
-      `telegram gateway: [autofallback] decision=fallback trigger=${opts.trigger} agent=${agentName} active=${active ?? 'none'} reason=${decision.triggerReason} util=${decision.utilizationPct?.toFixed(1) ?? 'n/a'}%\n`,
+    const state = await client.listState()
+    // Probe live quota for every account in parallel. force:true
+    // bypasses the 5-min in-process cache — we want the freshest data
+    // for the swap decision, not a cached stale read.
+    const quotas = await Promise.all(
+      state.accounts.map((a) => fetchAccountQuota(a.label, { force: true })),
     )
-    const plan = performAutoFallback({
-      agentDir,
-      agentName,
-      decision,
-      deps: { currentActiveSlot, markSlotQuotaExhausted, fallbackToNextSlot },
+    const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
+    const outcome = await runFleetAutoFallback({
+      state,
+      quotas,
+      setActive: (label) => client.setActive(label),
+      triggerAgent,
+      tz,
     })
-    const ownerChatId = loadAccess().allowFrom[0]
-    await dispatchFallbackNotification({
-      bot,
-      ownerChatId,
-      plan,
-      onError: (err) => {
-        process.stderr.write(`telegram gateway: [autofallback] notify failed trigger=${opts.trigger} agent=${agentName}: ${err}\n`)
-      },
-    })
-    if (plan.kind === 'executed') {
-      try { assertSafeAgentName(plan.agentName) }
-      catch {
-        process.stderr.write(`telegram gateway: [autofallback] invalid-agent-name agent=${plan.agentName}\n`)
-        return { kind: 'error', message: `invalid agent name: ${plan.agentName}` }
-      }
-      try {
-        // Preemptive failover (utilization-over-threshold / explicit) waits
-        // for the active turn to drain. Reactive failover (429-response)
-        // hard-restarts because the request that triggered it has already
-        // failed — there's no in-flight turn worth preserving. See #420.
-        const restartArgs = ['agent', 'restart', plan.agentName]
-        if (plan.triggerReason !== '429-response') {
-          restartArgs.push('--graceful-restart')
-        }
-        process.stderr.write(
-          `telegram gateway: [autofallback] executed agent=${plan.agentName} prev=${plan.previousSlot} next=${plan.newSlot} restart=${plan.triggerReason === '429-response' ? 'hard' : 'graceful'}\n`,
-        )
-        switchroomExec(restartArgs)
-      } catch (err) {
-        process.stderr.write(`telegram gateway: [autofallback] restart failed agent=${plan.agentName}: ${err}\n`)
-      }
-      autoFallbackLockout = nextLockout(plan.previousSlot, Date.now())
-      persistLockout(agentDir)
-      void refreshPinnedBanner('auto-fallback')
-      return { kind: 'executed', previousSlot: plan.previousSlot, newSlot: plan.newSlot }
-    }
     process.stderr.write(
-      `telegram gateway: [autofallback] exhausted-all agent=${agentName} active=${plan.activeSlot}\n`,
+      `telegram gateway: [fleet-fallback] outcome=${outcome.kind} agent=${triggerAgent}` +
+        (outcome.kind === 'switched' ? ` old=${outcome.oldLabel} new=${outcome.newLabel}` : '') +
+        '\n',
     )
-    autoFallbackLockout = nextLockout(plan.activeSlot, Date.now())
-    persistLockout(agentDir)
-    return { kind: 'exhausted-all', activeSlot: plan.activeSlot }
+    // Post the announcement to every authorized chat. Mirrors the
+    // operator-event broadcast pattern (line ~2290) — DM-only opts
+    // (no message_thread_id) so THREAD_NOT_FOUND can't fire here;
+    // wrap in swallowingApiCall anyway per the codebase rule.
+    const access = loadAccess()
+    if (access.allowFrom.length === 0) return outcome.kind === 'switched'
+    const opts = { parse_mode: 'HTML' as const }
+    for (const chat_id of access.allowFrom) {
+      void swallowingApiCall(
+        () => bot.api.sendMessage(chat_id, outcome.announcement, opts),
+        { chat_id, verb: 'fleet-fallback:notify' },
+      )
+    }
+    return outcome.kind === 'switched'
   } catch (err) {
-    process.stderr.write(`telegram gateway: [autofallback] ${opts.trigger} poll error: ${err}\n`)
-    return { kind: 'error', message: String((err as Error).message ?? err) }
+    process.stderr.write(
+      `telegram gateway: [fleet-fallback] error agent=${triggerAgent}: ${(err as Error)?.message ?? err}\n`,
+    )
+    return false
   }
 }
 
@@ -8346,14 +8982,19 @@ async function runCreditWatch(): Promise<void> {
   // assumption mirrors auto-fallback's notification routing.
   const access = loadAccess()
   for (const chat_id of access.allowFrom) {
-    try {
-      await bot.api.sendMessage(chat_id, decision.message, {
-        parse_mode: 'HTML',
-        link_preview_options: { is_disabled: true },
-      })
-    } catch (err) {
-      process.stderr.write(`telegram gateway: credit-watch notify chat=${chat_id} failed: ${err}\n`)
-    }
+    // Credit-watch notify — best-effort. Wrap via swallowingApiCall so
+    // flood-wait / deleted-chat / not-found surface as a stderr log
+    // rather than a thrown exception that aborts the loop and leaves
+    // half the allowFrom chats unnotified. Matches the wrapping
+    // contract enforced by scripts/check-bot-api-wrapping.sh (#1075).
+    await swallowingApiCall(
+      () =>
+        bot.api.sendMessage(chat_id, decision.message, {
+          parse_mode: 'HTML',
+          link_preview_options: { is_disabled: true },
+        }),
+      { chat_id, verb: 'credit-watch.notify' },
+    )
   }
   // Persist state regardless of whether send succeeded — losing a
   // notify is bad, but re-spamming on every poll tick is worse.
@@ -8364,438 +9005,152 @@ async function runCreditWatch(): Promise<void> {
   }
 }
 
-// /authfallback was removed in v0.6.12 — it duplicated the work of
-// the dashboard's Switch primary picker (operator-facing surface) and
-// the auto-fallback poller (transparent on-quota-wall case).
-// Operators who want to manually shuffle the active credential now
-// use the picker. The `runAutoFallbackCheck` function and the
-// `case 'fallback':` callback dispatch stay in the codebase: any
-// pinned messages from earlier versions still work, and the
-// auto-fallback poller still calls runAutoFallbackCheck directly.
-
-bot.command('auth', async ctx => {
+bot.command("auth", async ctx => {
   if (!isAuthorizedSender(ctx)) return
-  const parts = getCommandArgs(ctx).split(/\s+/).filter(Boolean)
+  const text = ctx.message?.text ?? ""
+  const parsed = parseAuthCommand(text)
+  if (!parsed) return
   const currentAgent = getMyAgentName()
-  const intent = parseAuthSubCommand(parts, currentAgent)
-
-  if (intent.kind === 'error' || intent.kind === 'usage') {
-    await switchroomReply(ctx, intent.message)
-    return
-  }
-
-  if (intent.kind === 'login' || intent.kind === 'reauth' || intent.kind === 'link') {
-    await runSwitchroomAuthCommand(ctx, intent.cliArgs, intent.label)
-    if (intent.registerReauth) pendingReauthFlows.set(String(ctx.chat!.id), { agent: intent.agent, startedAt: Date.now() })
-    return
-  }
-  if (intent.kind === 'code') {
-    // Use structured JSON path so we can render typed outcome messages.
-    const { result, errorText } = execAuthCode(intent.agent, intent.code)
-    if (errorText) {
-      await switchroomReply(ctx, `<b>${escapeHtmlForTg(intent.label)} failed:</b>\n${preBlock(formatSwitchroomOutput(errorText))}`, { html: true })
-    } else if (result) {
-      const outcomeMsg = renderAuthCodeOutcome(result.outcome)
-      if (outcomeMsg) {
-        await switchroomReply(ctx, outcomeMsg, { html: true })
-      } else {
-        const output = result.instructions.join('\n')
-        const formatted = formatAuthOutputForTelegram(output)
-        await switchroomReply(ctx, formatted.text, { html: true })
-      }
-    }
-    pendingReauthFlows.delete(String(ctx.chat!.id))
-    // Redact the OAuth code from chat history (#488).
-    redactAuthCodeMessage(bot.api as never, String(ctx.chat!.id), ctx.message?.message_id ?? null, line => process.stderr.write(line))
-    return
-  }
-  if (intent.kind === 'cancel') {
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    pendingReauthFlows.delete(String(ctx.chat!.id))
-    return
-  }
-
-  // --- Slot management verbs ---
-
-  if (intent.kind === 'add') {
-    await runSwitchroomAuthCommand(ctx, intent.cliArgs, intent.label)
-    pendingReauthFlows.set(String(ctx.chat!.id), { agent: intent.agent, startedAt: Date.now() })
-    void refreshPinnedBanner('auth-add')
-    return
-  }
-
-  if (intent.kind === 'use') {
-    // Soft-confirm: a slot swap restarts the agent process, killing any
-    // in-flight turn. If a turn is currently running, refuse without
-    // --force so a fat-finger tap doesn't quietly destroy the user's
-    // work-in-progress. Idle-state swaps proceed with no friction. (#421B)
-    if (!intent.force && activeTurnStartedAt.size > 0) {
+  // Post-unification admin gating: admin authority is sourced from each
+  // agent's own `admin: true` flag (the same flag that gates /agents,
+  // /restart, /update etc. per PR #1258). The gateway looks itself up
+  // and passes a boolean through — handler-side code does not consult
+  // any list. The broker enforces server-side from the same source.
+  let isAdmin = false
+  try {
+    const cfg = loadSwitchroomConfig()
+    const me = (cfg as unknown as { agents?: Record<string, { admin?: boolean }> })?.agents?.[currentAgent]
+    isAdmin = me?.admin === true
+  } catch { /* best-effort — non-admin is the safe default */ }
+
+  // `/auth add` and `/auth cancel` are gateway-routed (drive a
+  // scratch-dir-backed `claude setup-token` lifecycle the broker
+  // client can't model). Everything else delegates to
+  // handleAuthCommand which only needs the narrow broker surface.
+  const chatId = String(ctx.chat?.id ?? '')
+  if (parsed.kind === 'add' || parsed.kind === 'cancel') {
+    if (!isAuthAdmin({ isAdmin })) {
       await switchroomReply(
         ctx,
-        `⚠️ A turn is in flight. Swapping to <code>${escapeHtmlForTg(intent.slot)}</code> will abort it.\n` +
-          `Resend as <code>/auth use ${escapeHtmlForTg(intent.agent)} ${escapeHtmlForTg(intent.slot)} --force</code> to proceed.`,
+        `<b>Not authorized.</b> <code>/auth ${parsed.kind}</code> is admin-only.\n` +
+          `Set <code>admin: true</code> on this agent in switchroom.yaml to unlock ` +
+          `(the same flag that gates <code>/agents</code>, <code>/restart</code>, ` +
+          `<code>/update</code> etc.).`,
         { html: true },
       )
       return
     }
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    // Restart the agent so the new OAuth token is picked up.
-    try { assertSafeAgentName(intent.agent) } catch { return }
-    await runSwitchroomCommand(ctx, ['agent', 'restart', intent.agent], `restart ${intent.agent}`)
-    void refreshPinnedBanner('auth-use')
-    return
-  }
-
-  if (intent.kind === 'list') {
-    await runSwitchroomCommandFormatted(ctx, intent.cliArgs, intent.label, () => {
-      const data = switchroomExecJson<SlotListingFromCli>(intent.cliArgs)
-      if (!data) return null
-      return formatSlotList({ ...data, agent: data.agent ?? intent.agent })
-    })
-    return
-  }
-
-  if (intent.kind === 'rm') {
-    // Safety check against current slot listing unless --force.
-    if (!intent.force) {
-      const listing = switchroomExecJson<SlotListingFromCli>(['auth', 'list', intent.agent, '--json'])
-      if (listing) {
-        const err = checkRemoveSafety({ ...listing, agent: listing.agent ?? intent.agent }, intent.slot, intent.force)
-        if (err) { await switchroomReply(ctx, err); return }
+    if (parsed.kind === 'cancel') {
+      const existing = pendingAuthAddFlows.get(chatId)
+      if (!existing) {
+        await switchroomReply(ctx, "<i>No pending <code>/auth add</code> flow in this chat.</i>", { html: true })
+        return
       }
+      cancelAccountAuthSession(existing)
+      pendingAuthAddFlows.delete(chatId)
+      await switchroomReply(ctx, "Cancelled.", { html: true })
+      return
     }
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    return
-  }
-
-  // --- New account-shaped verbs (see reference/share-auth-across-the-fleet.md) ---
-
-  if (intent.kind === 'account-add') {
-    // /auth account add <label> [--from-agent <name>]
-    // Lifts an already-authenticated agent's credentials into a global
-    // account so other agents can share the same Anthropic subscription
-    // without each running its own OAuth flow.
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    return
-  }
-
-  if (intent.kind === 'account-list') {
-    // /auth account list — table of accounts + which agents use each.
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    return
-  }
-
-  if (intent.kind === 'account-rm') {
-    // /auth account rm <label> — refused if any agent is still enabled.
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    return
-  }
-
-  if (intent.kind === 'account-rename') {
-    // /auth account rename <old> <new> — atomic dir rename + YAML
-    // rewrite of every agents.<name>.auth.accounts list. No agent
-    // restart required: per-agent credentials.json content is
-    // unchanged (only the source-of-truth label moved).
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    return
-  }
-
-  if (intent.kind === 'enable') {
-    // /auth enable <label> [agents...|all] — wires the account to those agents
-    // (defaults to the current agent), then restarts each so claude picks
-    // up the freshly fanned-out credentials. The CLI accepts the `all`
-    // keyword verbatim and expands it itself; we expand here too so the
-    // restart loop knows the real agent names.
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    if (intent.restartAgentsAfter) {
-      const restartTargets = await resolveAgentsForRestart(intent.agents)
-      for (const a of restartTargets) {
-        try { assertSafeAgentName(a) } catch { continue }
-        await runSwitchroomCommand(ctx, ['agent', 'restart', a], `restart ${a}`)
-      }
+    // parsed.kind === 'add'
+    if (pendingAuthAddFlows.has(chatId)) {
+      await switchroomReply(
+        ctx,
+        "<i>An <code>/auth add</code> flow is already in progress for this chat. " +
+          "Finish the paste, or send <code>/auth cancel</code> to abort.</i>",
+        { html: true },
+      )
+      return
     }
-    void refreshPinnedBanner('auth-enable')
-    return
-  }
-
-  if (intent.kind === 'disable') {
-    // /auth disable <label> [agents...|all] — unwires the account from those
-    // agents. Doesn't auto-restart: the operator may want to drain the
-    // current credential first. The CLI hint already says "restart now".
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    return
-  }
-
-  if (intent.kind === 'share') {
-    // /auth share <label> [--from-agent <name>] — one-shot account-add +
-    // enable on every claude-enabled agent. The CLI does the merged YAML
-    // write; we restart every agent it touched so credentials load.
-    await runSwitchroomCommand(ctx, intent.cliArgs, intent.label)
-    const restartTargets = await resolveAgentsForRestart(['all'])
-    for (const a of restartTargets) {
-      try { assertSafeAgentName(a) } catch { continue }
-      await runSwitchroomCommand(ctx, ['agent', 'restart', a], `restart ${a}`)
+    try {
+      const { loginUrl, scratchDir, child } = await startAccountAuthSession(parsed.label)
+      pendingAuthAddFlows.set(chatId, {
+        label: parsed.label,
+        scratchDir,
+        child,
+        startedAt: Date.now(),
+      })
+      await switchroomReply(
+        ctx,
+        `<b>Adding account</b> <code>${escapeHtmlForTg(parsed.label)}</code>\n\n` +
+          `1. Open this URL on your phone:\n${loginUrl}\n\n` +
+          `2. Log into Anthropic, copy the code Claude shows.\n` +
+          `3. Paste it back here.\n\n` +
+          `Send <code>/auth cancel</code> to abort.`,
+        { html: true },
+      )
+    } catch (err) {
+      await switchroomReply(
+        ctx,
+        `<b>/auth add failed:</b> ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`,
+        { html: true },
+      )
     }
-    void refreshPinnedBanner('auth-share')
     return
   }
 
-  // intent.kind === 'status' — render the inline-keyboard dashboard.
-  // For the dashboard we're the bot-bound agent: we don't list every
-  // agent in the switchroom config; we show THIS bot's agent with its
-  // slots and actions. The 'status' branch of AuthIntent has no
-  // `agent` field; use currentAgent as the dashboard target.
-  await sendAuthDashboard(ctx, currentAgent)
-})
-
-/**
- * Gather DashboardState for an agent and send the dashboard as a fresh
- * message (on `/auth` command) or editMessageText (on callback refresh).
- *
- * Implementation note: we could poll fetchQuota here to populate the
- * fiveHour/sevenDay utilization per slot. Skipping for the initial
- * landing — quota-check is expensive (one Anthropic API call per poll)
- * and the background auto-fallback already surfaces quota-exhausted
- * state. Dashboard renders the CLI-side health badges and omits
- * utilization numbers when they're absent; a future PR can wire
- * quota-check in.
- */
-async function sendAuthDashboard(
-  ctx: Context,
-  agent: string,
-  opts: { edit?: boolean } = {},
-): Promise<void> {
-  const state = fetchDashboardState(agent)
-  if (!state) {
-    await switchroomReply(
-      ctx,
-      `<b>/auth</b> — no data (agent "${escapeHtmlForTg(agent)}" missing from switchroom.yaml or CLI unreachable)`,
-      { html: true },
-    )
+  const client = await getAuthBrokerClient(currentAgent)
+  if (!client) {
+    await switchroomReply(ctx, "<b>/auth unavailable:</b> auth-broker client is not loaded (post-RFC-H rewire in progress?).", { html: true })
     return
   }
-  const { text, keyboard } = buildDashboard(state)
-  if (opts.edit && ctx.callbackQuery) {
-    try {
-      await ctx.editMessageText(text, { parse_mode: 'HTML', reply_markup: keyboard, link_preview_options: { is_disabled: true } })
-      return
-    } catch {
-      // Message may have been deleted or identical content
-      // (editMessageText throws MESSAGE_NOT_MODIFIED) — fall through
-      // to sending a new one.
-    }
-  }
-  await switchroomReply(ctx, text, { html: true, reply_markup: keyboard })
-}
-
-/**
- * Drop the cached per-account quota and immediately schedule a
- * background re-probe for every known account. Used after auth-mutating
- * dashboard taps (enable/disable/promote/share/account-rm-confirm) so
- * the next `/auth` render shows fresh quota rather than a 30s-stale
- * snapshot from before the change.
- *
- * Fire-and-forget: probes complete in ~hundreds of ms; the user's
- * follow-up dashboard render reads whatever's cached at that moment,
- * usually the freshly-warmed value. Errors (network, rate limit) are
- * absorbed by `prefetchAccountQuotaIfStale`.
- */
-function clearAndRewarmAccountQuotas(): void {
-  clearAccountQuotaCache()
-  try {
-    const accounts = switchroomExecJson<Array<{ label: string }>>([
-      'auth', 'account', 'list', '--json',
-    ])
-    if (Array.isArray(accounts)) {
-      for (const a of accounts) {
-        if (typeof a?.label === 'string') prefetchAccountQuotaIfStale(a.label)
+  const reply = await handleAuthCommand(parsed, {
+    agentName: currentAgent,
+    isAdmin,
+    client,
+    chatId,
+    // Format 2 enricher — probe live quota for every account in
+    // parallel so the snapshot reflects current Anthropic-side
+    // utilization, not the broker's potentially-days-stale
+    // disk-cached `quota.json`. force:true bypasses the 5-min
+    // in-process cache for this call. ~500-800ms per account
+    // serial; in parallel ~800ms total for typical 3-account
+    // fleets — acceptable for an interactive command.
+    liveQuotas: async (accounts) =>
+      Promise.all(
+        accounts.map((a) => fetchAccountQuota(a.label, { force: true })),
+      ),
+    tz: process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ,
+  })
+  // Translate the handler's optional keyboard shape into grammy's
+  // `reply_markup`. Buttons with `callbackData` become callback_data;
+  // buttons with `insertText` become switch_inline_query_current_chat
+  // (taps paste the slash-command into the user's input). Keep a
+  // safe default for buttons missing both (shouldn't happen).
+  if (reply.keyboard && reply.keyboard.length > 0) {
+    // Build via grammy's InlineKeyboard so the type is correct
+    // for switchroomReply's reply_markup field — no `as never`
+    // cast needed.
+    const kb = new InlineKeyboard()
+    for (let i = 0; i < reply.keyboard.length; i++) {
+      const row = reply.keyboard[i]!
+      for (const b of row) {
+        if (b.callbackData) kb.text(b.text, b.callbackData)
+        else if (b.insertText) kb.switchInlineCurrent(b.text, b.insertText)
+        else kb.text(b.text, 'auth:noop')
       }
+      // grammy's row terminator — except after the last row.
+      if (i < reply.keyboard.length - 1) kb.row()
     }
-  } catch {
-    /* clear-only fallback — next dashboard render's lazy prefetch will warm */
-  }
-}
-
-function fetchDashboardState(agent: string): DashboardState | null {
-  // Slots come from switchroom auth list --json.
-  let slots: DashboardSlot[] = []
-  try {
-    const listing = switchroomExecJson<SlotListingFromCli>(['auth', 'list', agent, '--json'])
-    if (listing && Array.isArray(listing.slots)) {
-      slots = listing.slots.map((s) => ({
-        slot: s.slot,
-        active: s.active,
-        health: (s.health as SlotHealth) ?? 'missing',
-        quotaExhaustedUntil: s.quota_exhausted_until ?? null,
-        fiveHourPct: null,
-        sevenDayPct: null,
-      }))
-    }
-  } catch {
-    return null
-  }
-
-  // Plan + bank + rateLimitTier come from switchroom auth status for
-  // THIS agent. rateLimitTier is the signal users need to verify the
-  // correct Anthropic account got authorized during reauth (e.g.
-  // max_5x vs max_20x). See 2026-04-22 account-mismatch discussion.
-  let plan: string | null = null
-  let rateLimitTier: string | null = null
-  const bankId = agent
-  try {
-    type AuthStatusResp = { agents: Array<{ name: string; subscription_type: string | null; rate_limit_tier?: string | null }> }
-    const statusData = switchroomExecJson<AuthStatusResp>(['auth', 'status'])
-    const thisAgent = statusData?.agents?.find((a) => a.name === agent)
-    if (thisAgent?.subscription_type) plan = thisAgent.subscription_type
-    if (thisAgent?.rate_limit_tier) rateLimitTier = thisAgent.rate_limit_tier
-  } catch {
-    /* best-effort */
-  }
-
-  // Check for a pending auth session on disk. When present, surface it
-  // on the dashboard so the user can tap [♻️ Restart flow] without
-  // waiting for the automatic stale-session detection to fire (which
-  // only fires on actual PKCE challenge drift).
-  const pendingSessionSlot = readPendingSessionSlot(agent)
-
-  // Account-level state for the dashboard's accounts section. The CLI
-  // emits a sorted, JSON array via `auth account list --json` (added
-  // in v0.6.x). We map it to the dashboard's `AccountSummary` shape,
-  // computing `enabledHere` from the per-account `agents` list.
-  //
-  // Wrapped in try/catch so an older CLI without --json (or any other
-  // failure) leaves `accounts` undefined — the renderer hides the
-  // section gracefully.
-  type AccountListItem = {
-    label: string
-    health: AccountHealth
-    subscriptionType?: string
-    expiresAt?: number
-    quotaExhaustedUntil?: number
-    email?: string
-    agents: string[]
-    /** v0.6.9+: agents for which this label is at index 0 of
-     *  auth.accounts: (i.e. the post-fanout active for that agent).
-     *  Optional — older CLIs without the field cause the dashboard to
-     *  fall back to the v3a unmarked render. */
-    primaryForAgents?: string[]
-  }
-  let accounts: AccountSummary[] | undefined
-  let accountsTruncated = false
-  try {
-    const raw = switchroomExecJson<AccountListItem[]>([
-      'auth', 'account', 'list', '--json',
-    ])
-    if (Array.isArray(raw)) {
-      accounts = raw.map((a) => {
-        // Layer per-account quota onto the summary from the in-process
-        // cache (warmed by `prefetchAccountQuotaIfStale` below). Sync
-        // read keeps `fetchDashboardState` itself sync; the cache TTL
-        // (30s) keeps the API-call rate bounded.
-        const cached = getCachedAccountQuota(a.label)
-        const summary: AccountSummary = {
-          label: a.label,
-          health: a.health,
-          enabledHere: Array.isArray(a.agents) && a.agents.includes(agent),
-          ...(Array.isArray(a.primaryForAgents)
-            ? { activeForThisAgent: a.primaryForAgents.includes(agent) }
-            : {}),
-          ...(a.subscriptionType ? { subscriptionType: a.subscriptionType } : {}),
-          ...(a.expiresAt != null ? { expiresAt: a.expiresAt } : {}),
-          ...(a.quotaExhaustedUntil != null
-            ? { quotaExhaustedUntil: a.quotaExhaustedUntil }
-            : {}),
-          ...(cached?.ok
-            ? {
-                fiveHourPct: cached.data.fiveHourUtilizationPct,
-                sevenDayPct: cached.data.sevenDayUtilizationPct,
-                ...(cached.data.fiveHourResetAt
-                  ? { fiveHourResetAt: cached.data.fiveHourResetAt.getTime() }
-                  : {}),
-                ...(cached.data.sevenDayResetAt
-                  ? { sevenDayResetAt: cached.data.sevenDayResetAt.getTime() }
-                  : {}),
-              }
-            : {}),
-        }
-        // Fire a background probe if the cache is cold/stale. The
-        // current render uses whatever's already cached; the *next*
-        // tap of /auth (after the probe completes) sees the fresh
-        // numbers. Swallowed errors keep the dashboard responsive even
-        // when Anthropic is slow or returns a transient 5xx.
-        prefetchAccountQuotaIfStale(a.label)
-        return summary
-      })
-      accountsTruncated = accounts.length > ACCOUNTS_DISPLAY_CAP
-    }
-  } catch {
-    /* leave accounts undefined */
-  }
-
-  // `canBootstrapShare` decides whether to surface the "🌐 Share to
-  // fleet" button when zero accounts exist. We only show it when this
-  // agent has slot creds we could promote — otherwise the share verb
-  // would fail at the credentials lookup.
-  const canBootstrapShare = slots.some(
-    (s) => s.health === 'healthy' || s.health === 'active',
-  )
-
-  // `quotaHot` now considers BOTH per-slot percentages (legacy slot
-  // model) and per-account percentages (new account model). Either
-  // path lighting up flips the [Fall back now] affordance, so the
-  // operator sees the warning whether they're on the legacy or new
-  // framework.
-  const slotQuotaHot = isQuotaHot(slots)
-  const accountQuotaHot = isAccountQuotaHot(accounts)
-
-  return {
-    agent,
-    bankId,
-    plan,
-    rateLimitTier,
-    slots,
-    quotaHot: slotQuotaHot || accountQuotaHot,
-    generatedAt: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
-    pendingSessionSlot,
-    accounts,
-    accountsTruncated,
-    canBootstrapShare,
+    await switchroomReply(ctx, reply.text, {
+      html: reply.html,
+      reply_markup: kb,
+    })
+  } else {
+    await switchroomReply(ctx, reply.text, { html: reply.html })
   }
-}
+})
 
-/**
- * Build the per-account list rendered on the boot/health card (issue
- * #708). Reuses `fetchDashboardState` so the data source matches
- * `/auth` exactly — same cache, same shape. Returns null on any
- * failure so the boot card silently omits the section.
- */
-function loadAccountsForBootCard(agent: string): ReadonlyArray<AccountSummary> | null {
+// Boot-card auth-row loader (issue #708, RFC H rewire). Queries the
+// broker for `list-state` and hands the raw shape to the boot card,
+// which delegates rendering to `renderAuthLine`. Returns null on any
+// failure so the boot card silently omits the section.
+async function loadAccountsForBootCard(agent: string): Promise<ListStateData | null> {
   try {
-    // Re-hydrate the in-process cache from on-disk snapshots
-    // captured by previous gateway lifetimes. Without this, a fresh
-    // boot would render the accounts section with empty quota rows
-    // until the background prefetch ticks. Best-effort.
-    try {
-      const labels = switchroomExecJson<Array<{ label?: string }>>([
-        'auth', 'account', 'list', '--json',
-      ])
-      if (Array.isArray(labels)) {
-        hydrateAccountQuotaCacheFromDisk(
-          labels.map((l) => l?.label).filter((s): s is string => typeof s === 'string'),
-        )
-      }
-    } catch {
-      /* hydrate is best-effort; fall through to live state */
-    }
-
-    const state = fetchDashboardState(agent)
-    if (!state || !state.accounts) return null
-    // Show only accounts enabled on this agent — fallback rows on the
-    // dashboard are useful, but on the boot card "accounts I'm using"
-    // is the right scope.
-    const enabled = state.accounts.filter((a) => a.enabledHere)
-    return enabled.length > 0 ? enabled : null
-  } catch {
+    const client = await getAuthBrokerClient(agent)
+    if (!client) return null
+    return await client.listState()
+  } catch (err) {
+    process.stderr.write(`telegram gateway: boot-card auth probe failed: ${(err as Error)?.message ?? String(err)}\n`)
     return null
   }
 }
@@ -10405,310 +10760,154 @@ async function handleOperatorEventCallback(ctx: Context, data: string): Promise<
   }
 }
 
+// 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 senderId = String(ctx.from?.id ?? '')
-  const access = loadAccess()
-  if (!access.allowFrom.includes(senderId)) {
-    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
-    return
-  }
-  const action = parseCallbackData(data)
+  const currentAgent = getMyAgentName()
 
-  switch (action.kind) {
-    case 'refresh': {
-      await ctx.answerCallbackQuery({ text: 'Refreshed' }).catch(() => {})
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'reauth': {
-      await ctx.answerCallbackQuery({ text: 'Starting reauth…' }).catch(() => {})
-      await runSwitchroomAuthCommand(
-        ctx,
-        action.slot ? ['auth', 'reauth', action.agent, '--slot', action.slot] : ['auth', 'reauth', action.agent],
-        `auth reauth ${action.agent}`,
-      )
-      pendingReauthFlows.set(String(ctx.chat!.id), { agent: action.agent, startedAt: Date.now() })
-      return
-    }
-    case 'add': {
-      await ctx.answerCallbackQuery({ text: 'Adding slot…' }).catch(() => {})
-      await runSwitchroomAuthCommand(ctx, ['auth', 'add', action.agent], `auth add ${action.agent}`)
-      pendingReauthFlows.set(String(ctx.chat!.id), { agent: action.agent, startedAt: Date.now() })
-      return
-    }
-    case 'use': {
-      await ctx.answerCallbackQuery({ text: `Switching to ${action.slot}…` }).catch(() => {})
-      await runSwitchroomCommand(ctx, ['auth', 'use', action.agent, action.slot], `auth use ${action.agent} ${action.slot}`)
-      try { assertSafeAgentName(action.agent) } catch { return }
-      await runSwitchroomCommand(ctx, ['agent', 'restart', action.agent], `restart ${action.agent}`)
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'rm': {
-      // Two-step confirm — swap the dashboard keyboard for a
-      // confirmation keyboard before doing anything destructive.
-      await ctx.answerCallbackQuery({ text: `Confirm remove ${action.slot}?` }).catch(() => {})
-      try {
-        await ctx.editMessageReplyMarkup({ reply_markup: buildRemoveConfirmKeyboard(action.agent, action.slot) })
-      } catch { /* ignore */ }
-      return
-    }
-    case 'confirm-rm': {
-      await ctx.answerCallbackQuery({ text: `Removing ${action.slot}…` }).catch(() => {})
-      const listing = switchroomExecJson<SlotListingFromCli>(['auth', 'list', action.agent, '--json'])
-      if (listing) {
-        const err = checkRemoveSafety({ ...listing, agent: listing.agent ?? action.agent }, action.slot, false)
-        if (err) {
-          await switchroomReply(ctx, err)
-          await sendAuthDashboard(ctx, action.agent, { edit: true })
-          return
-        }
-      }
-      await runSwitchroomCommand(ctx, ['auth', 'rm', action.agent, action.slot], `auth rm ${action.agent} ${action.slot}`)
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'fallback': {
-      await ctx.answerCallbackQuery({ text: 'Triggering fallback…' }).catch(() => {})
-      const result = await runAutoFallbackCheck({ trigger: 'manual' })
-      if (result.kind === 'executed') {
-        await switchroomReply(ctx, `✅ Switched <code>${escapeHtmlForTg(result.previousSlot)}</code> → <code>${escapeHtmlForTg(result.newSlot)}</code>.`, { html: true })
-      } else if (result.kind === 'exhausted-all') {
-        await switchroomReply(ctx, `🚨 All slots quota-exhausted. Tap ➕ Add slot.`, { html: true })
-      } else if (result.kind === 'error') {
-        await switchroomReply(ctx, `❌ Fallback error: ${escapeHtmlForTg(result.message)}`, { html: true })
-      } else {
-        await switchroomReply(ctx, `No action: ${escapeHtmlForTg(result.reason)}`, { html: true })
-      }
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'restart-flow': {
-      // Kill any pending session + restart the same flow (reauth or
-      // add-slot) fresh. Exists for the case where the user wants to
-      // start over BEFORE the automatic stale-session detection fires
-      // (e.g. closed the browser tab, 2FA failed, waited too long).
-      await ctx.answerCallbackQuery({ text: `Restarting ${action.slot} flow…` }).catch(() => {})
-      // Step 1: cancel any pending session for this agent.
-      try {
-        await runSwitchroomCommand(ctx, ['auth', 'cancel', action.agent], `auth cancel ${action.agent}`)
-      } catch { /* cancel is best-effort */ }
-      // Step 2: re-initiate. Slot == 'default' → reauth; else → add-slot.
-      // Both paths print the fresh URL + button + ForceReply prompt via
-      // runSwitchroomAuthCommand.
-      if (action.slot === 'default') {
-        await runSwitchroomAuthCommand(ctx, ['auth', 'reauth', action.agent], `auth reauth ${action.agent}`)
-      } else {
-        await runSwitchroomAuthCommand(ctx, ['auth', 'add', action.agent, '--slot', action.slot], `auth add ${action.agent} --slot ${action.slot}`)
-      }
-      pendingReauthFlows.set(String(ctx.chat!.id), { agent: action.agent, startedAt: Date.now() })
+  // 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
     }
-    case 'usage': {
-      await ctx.answerCallbackQuery({ text: 'Fetching quota…' }).catch(() => {})
-      const agentDir = resolveAgentDirFromEnv()
-      if (!agentDir) {
-        await switchroomReply(ctx, 'Quota lookup unavailable: no agent directory.')
+    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 {
-        const quota = await fetchQuota({ claudeConfigDir: join(agentDir, '.claude') })
-        if (!quota.ok) {
-          await switchroomReply(ctx, `<b>Quota:</b> ${escapeHtmlForTg(quota.reason)}`, { html: true })
-        } else {
-          await switchroomReply(ctx, formatQuotaBlock(quota.data), { html: true })
-        }
-      } catch (err) {
-        await switchroomReply(ctx, `Quota fetch failed: ${escapeHtmlForTg(String(err))}`, { html: true })
-      }
-      return
-    }
-    // Account-level toggles (#share-auth-across-the-fleet). Two-stage
-    // confirm pattern mirrors `rm`/`confirm-rm` so a stray tap doesn't
-    // re-shuffle credentials. The CLI verb is the one source of truth
-    // for the YAML mutation + fanout; we only translate the tap into
-    // a `runSwitchroomCommand` call and refresh the dashboard.
-    case 'account-enable': {
-      await ctx.answerCallbackQuery({ text: `Confirm enable ${action.label}?` }).catch(() => {})
-      try {
-        await ctx.editMessageReplyMarkup({
-          reply_markup: buildAccountConfirmKeyboard(action.agent, action.label, 'enable'),
+        await ctx.answerCallbackQuery({
+          text: `Switched fleet → ${result.active} (${result.fanned.length} agents)`,
+          show_alert: false,
         })
-      } catch { /* ignore */ }
-      return
-    }
-    case 'account-disable': {
-      await ctx.answerCallbackQuery({ text: `Confirm disable ${action.label}?` }).catch(() => {})
-      try {
-        await ctx.editMessageReplyMarkup({
-          reply_markup: buildAccountConfirmKeyboard(action.agent, action.label, 'disable'),
-        })
-      } catch { /* ignore */ }
-      return
-    }
-    case 'confirm-account-enable': {
-      await ctx.answerCallbackQuery({ text: `Enabling ${action.label}…` }).catch(() => {})
-      try { assertSafeAgentName(action.agent) } catch { return }
-      // CLI does the YAML mutation + per-agent credential fanout. The
-      // restart afterwards is what actually loads the new credentials
-      // into the running claude process.
-      await runSwitchroomCommand(
-        ctx,
-        ['auth', 'enable', action.label, action.agent],
-        `auth enable ${action.label} ${action.agent}`,
-      )
-      await runSwitchroomCommand(ctx, ['agent', 'restart', action.agent], `restart ${action.agent}`)
-      // Account roster changed — drop cached quota so the next
-      // dashboard render kicks a fresh probe instead of showing
-      // stale numbers (or a zero row for a label that just got added).
-      clearAndRewarmAccountQuotas()
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'confirm-account-disable': {
-      await ctx.answerCallbackQuery({ text: `Disabling ${action.label}…` }).catch(() => {})
-      try { assertSafeAgentName(action.agent) } catch { return }
-      await runSwitchroomCommand(
-        ctx,
-        ['auth', 'disable', action.label, action.agent],
-        `auth disable ${action.label} ${action.agent}`,
-      )
-      // Force restart so claude drops the stale credentials immediately.
-      // The CLI's `disable` doesn't auto-restart (it expects the operator
-      // to drain manually); the dashboard tap is implicit "I'm done with
-      // this account on this agent now," so we restart on their behalf.
-      await runSwitchroomCommand(ctx, ['agent', 'restart', action.agent], `restart ${action.agent}`)
-      clearAndRewarmAccountQuotas()
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'account-promote': {
-      // Two-stage confirm — same UX as enable/disable, just a different
-      // verb on the confirm row's callback. The CLI verb does the
-      // YAML reorder + fanout. Reachable via the legacy v3b per-row
-      // `⤴ Promote` button (callback verb `apr`) — kept for any
-      // already-pinned messages that still have it.
-      await ctx.answerCallbackQuery({ text: `Confirm promote ${action.label}?` }).catch(() => {})
+      } 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,
+              `<b>Active account →</b> <code>${escapeHtmlForTg(result.active)}</code>\n` +
+                `<i>Re-mirrored credentials for ${result.fanned.length} agent${result.fanned.length === 1 ? '' : 's'}.</i>\n\n` +
+                `<i>Tap /auth to see updated quota for the new active account.</i>`,
+              { parse_mode: 'HTML' },
+            ),
+          { chat_id: String(msg.chat.id), verb: 'auth:use:edit' },
+        )
+      }
+    } catch (err) {
+      const msg = (err as Error)?.message ?? String(err)
       try {
-        await ctx.editMessageReplyMarkup({
-          reply_markup: buildAccountPromoteConfirmKeyboard(action.agent, action.label),
+        await ctx.answerCallbackQuery({
+          text: `Switch failed: ${msg.slice(0, 180)}`,
+          show_alert: true,
         })
-      } catch { /* ignore */ }
-      return
+      } catch { /* */ }
     }
-    case 'switch-primary-view': {
-      // v3c picker: open a sub-keyboard that lists every non-active
-      // account as a one-tap promote target. Direct
-      // `confirm-account-promote` callbacks (no second confirm) — the
-      // picker IS the confirmation surface.
-      await ctx.answerCallbackQuery().catch(() => {})
-      const state = fetchDashboardState(action.agent)
-      const candidates = (state?.accounts ?? [])
-        .filter((a) => a.activeForThisAgent !== true)
-        .map((a) => ({ label: a.label, health: a.health }))
-      if (candidates.length === 0) {
-        // No fallbacks to switch to — return to the main board with a
-        // toast explaining why.
-        await ctx.answerCallbackQuery({ text: 'No fallback accounts to switch to.' }).catch(() => {})
-        await sendAuthDashboard(ctx, action.agent, { edit: true })
+    return
+  }
+
+  // auth:refresh — re-render the /auth snapshot in-place with a fresh
+  // live probe. Replaces the message body; keyboard stays.
+  if (data === 'auth:refresh') {
+    // Freshness throttle: each refresh fan-fires N live api.anthropic.com
+    // probes (one per account, force=true bypasses the 5-min cache).
+    // 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
       }
-      try {
-        await ctx.editMessageReplyMarkup({
-          reply_markup: buildSwitchPrimaryKeyboard(action.agent, candidates),
-        })
-      } catch { /* ignore MESSAGE_NOT_MODIFIED */ }
-      return
+      lastAuthRefreshAtMs.set(key, Date.now())
     }
-    case 'confirm-account-promote': {
-      await ctx.answerCallbackQuery({ text: `Promoting ${action.label}…` }).catch(() => {})
-      try { assertSafeAgentName(action.agent) } catch { return }
-      await runSwitchroomCommand(
-        ctx,
-        ['auth', 'promote', action.label, action.agent],
-        `auth promote ${action.label} ${action.agent}`,
+    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()
+      const quotas = await Promise.all(
+        state.accounts.map((a) => fetchAccountQuota(a.label, { force: true })),
       )
-      // Promotion changes the active credential — must restart so
-      // claude reloads the new primary's tokens.
-      await runSwitchroomCommand(ctx, ['agent', 'restart', action.agent], `restart ${action.agent}`)
-      clearAndRewarmAccountQuotas()
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'share-fleet': {
-      // Bootstrap one-tap: zero accounts exist, this agent has healthy
-      // slot creds. Synthesise label="default" so the user gets a
-      // sensible starting state in one tap; rename via CLI later.
-      await ctx.answerCallbackQuery({ text: 'Sharing to fleet…' }).catch(() => {})
-      try { assertSafeAgentName(action.agent) } catch { return }
-      await runSwitchroomCommand(
-        ctx,
-        ['auth', 'share', 'default', '--from-agent', action.agent],
-        `auth share default --from-agent ${action.agent}`,
+      const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
+      const { renderAuthSnapshotFormat2, buildSnapshotsFromState, buildSnapshotKeyboard } = await import(
+        '../auth-snapshot-format.js'
       )
-      await runSwitchroomCommand(ctx, ['agent', 'restart', action.agent], `restart ${action.agent}`)
-      clearAndRewarmAccountQuotas()
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    // v3a: per-account drill-down sub-view handlers.
-    case 'account-view': {
-      // Drill into the per-account sub-view. Fetch current account state
-      // so the sub-view reflects live health, then edit-in-place.
-      await ctx.answerCallbackQuery().catch(() => {})
-      const state = fetchDashboardState(action.agent)
-      const acc = state?.accounts?.find((a) => a.label === action.label)
-      if (!acc || !state) {
-        await ctx.answerCallbackQuery({ text: `Account "${action.label}" not found.` }).catch(() => {})
-        await sendAuthDashboard(ctx, action.agent, { edit: true })
-        return
+      const snapshots = buildSnapshotsFromState(state, quotas)
+      const text = renderAuthSnapshotFormat2(snapshots, {
+        tz,
+        now: new Date(),
+        liveProbedAtMs: Date.now(),
+      })
+      const kbRows = buildSnapshotKeyboard(snapshots)
+      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, text, {
+              parse_mode: 'HTML',
+              reply_markup: { inline_keyboard },
+            }),
+          { chat_id: String(msg.chat.id), verb: 'auth:refresh:edit' },
+        )
       }
-      const text = buildAccountSubViewText(action.agent, acc)
-      const keyboard = buildAccountSubViewKeyboard(action.agent, action.label)
-      try {
-        await ctx.editMessageText(text, { parse_mode: 'HTML', reply_markup: keyboard, link_preview_options: { is_disabled: true } })
-      } catch { /* ignore MESSAGE_NOT_MODIFIED */ }
-      return
-    }
-    case 'account-reauth': {
-      // Reauth by account is not wired to a CLI verb in v3a.
-      // Surface a toast so the button is visible-but-inert; the full
-      // flow lands in v3b when `auth account reauth <label>` exists.
-      await ctx.answerCallbackQuery({ text: 'Reauth not yet wired — coming in v3b' }).catch(() => {})
-      return
-    }
-    case 'account-rm': {
-      // Two-step confirm — swap sub-view keyboard for remove confirm.
-      await ctx.answerCallbackQuery({ text: `Remove ${action.label}?` }).catch(() => {})
+      try { await ctx.answerCallbackQuery({ text: 'Refreshed.', show_alert: false }) } catch { /* */ }
+    } catch (err) {
+      const msg = (err as Error)?.message ?? String(err)
       try {
-        await ctx.editMessageReplyMarkup({
-          reply_markup: buildAccountRemoveConfirmKeyboard(action.agent, action.label),
+        await ctx.answerCallbackQuery({
+          text: `Refresh failed: ${msg.slice(0, 180)}`,
+          show_alert: true,
         })
-      } catch { /* ignore */ }
-      return
-    }
-    case 'account-rm-confirm': {
-      await ctx.answerCallbackQuery({ text: `Removing ${action.label}…` }).catch(() => {})
-      try { assertSafeAgentName(action.agent) } catch { return }
-      await runSwitchroomCommand(
-        ctx,
-        ['auth', 'account', 'rm', action.label],
-        `auth account rm ${action.label}`,
-      )
-      // Removed account label is gone — drop its cache entry (and any
-      // siblings, since `enabledHere` shifts when an agent's account
-      // list changes).
-      clearAndRewarmAccountQuotas()
-      await sendAuthDashboard(ctx, action.agent, { edit: true })
-      return
-    }
-    case 'noop':
-    default: {
-      await ctx.answerCallbackQuery().catch(() => {})
-      return
+      } 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
@@ -11119,6 +11318,44 @@ bot.command('issues', async ctx => {
 
 bot.command('usage', async ctx => {
   if (!isAuthorizedSender(ctx)) return
+  // Format 2 path: enumerate every account in the broker's known set,
+  // probe live quota in parallel, render the health-grouped snapshot.
+  // Falls back to the legacy single-agent shape when the broker is
+  // unreachable, since /usage was historically callable against any
+  // agent regardless of fleet state.
+  const currentAgent = getMyAgentName()
+  try {
+    const client = await getAuthBrokerClient(currentAgent)
+    if (client) {
+      const state = await client.listState()
+      if (state.accounts.length > 0) {
+        const quotas = await Promise.all(
+          state.accounts.map((a) => fetchAccountQuota(a.label, { force: true })),
+        )
+        const { renderAuthSnapshotFormat2, buildSnapshotsFromState } = await import(
+          '../auth-snapshot-format.js'
+        )
+        const tz = process.env.SWITCHROOM_TIMEZONE ?? process.env.TZ ?? 'UTC'
+        const snapshots = buildSnapshotsFromState(state, quotas)
+        const text = renderAuthSnapshotFormat2(snapshots, {
+          tz,
+          now: new Date(),
+          liveProbedAtMs: Date.now(),
+        })
+        await switchroomReply(ctx, text, { html: true })
+        return
+      }
+    }
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: /usage Format 2 path failed agent=${currentAgent}: ${(err as Error)?.message ?? err}\n`,
+    )
+    // fall through to legacy single-agent path
+  }
+
+  // Legacy single-agent path — kept as a graceful fallback when the
+  // broker is unreachable (post-RFC-H rewire boot timing, broken
+  // socket bind, etc.). Same shape /usage shipped with originally.
   const agentDir = resolveAgentDirFromEnv()
   if (!agentDir) {
     await switchroomReply(ctx, '<b>/usage:</b> cannot resolve agent dir.', { html: true })
@@ -11243,6 +11480,29 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // RFC E §4.1: drvpick:<verb>:<agent>[:<...>] — folder-picker card taps.
+  // open / enter / back / refresh re-render the card in place;
+  // grant writes an allow_always kernel decision at
+  // doc:gdrive:folder/<id>/** and edits the card to a confirmation.
+  //
+  // Auth gate: the picker grant is an OPERATOR action (mirrors the
+  // `op:`/`vd:`/`vg:` family, not the `apv:` agent-approval shape).
+  // Mirror those patterns — refuse callbacks from anyone outside
+  // `access.allowFrom`. Without this, a group member who isn't in
+  // the operator allowlist could still tap [✅ Allow "<folder>"] on
+  // a card that landed in the group and write an `allow_always`
+  // decision attributed to themselves.
+  if (data.startsWith('drvpick:')) {
+    const access = loadAccess()
+    const senderId = String(ctx.from?.id ?? '')
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' })
+      return
+    }
+    await handleFolderPickerCallback(ctx, data, buildFolderPickerDeps())
+    return
+  }
+
   // op:<action>:<encoded-agent> callbacks from operator-events.ts
   // renderOperatorEvent(). Agent name is URL-encoded at emit (issue #24).
   // Actions: dismiss, restart, reauth, swap-slot, add-slot, logs.
@@ -12993,35 +13253,10 @@ void (async () => {
           )
         }
 
-        // v0.6.10 boot-warm: kick off a background per-account quota
-        // probe for every account in the new auth framework. Without
-        // this, the FIRST `/auth` after a restart shows no mini-bars
-        // because the in-process cache is cold — the dashboard's lazy
-        // prefetch fires the probe but the operator's already-rendered
-        // message has empty quota rows. Pre-warming fills the cache
-        // before the user can tap.
-        //
-        // Fire-and-forget per label. Failures (rate limit, network,
-        // expired token) leave the cache unset so the dashboard's lazy
-        // path retries on the next render — same safety-net contract
-        // as available_reactions above.
-        try {
-          const accountsAtBoot = switchroomExecJson<Array<{ label: string }>>([
-            'auth', 'account', 'list', '--json',
-          ])
-          if (Array.isArray(accountsAtBoot) && accountsAtBoot.length > 0) {
-            for (const a of accountsAtBoot) {
-              if (typeof a?.label === 'string') prefetchAccountQuotaIfStale(a.label)
-            }
-            process.stderr.write(
-              `telegram gateway: boot-warmed quota cache for ${accountsAtBoot.length} account(s)\n`,
-            )
-          }
-        } catch (err) {
-          process.stderr.write(
-            `telegram gateway: boot-warm of account quota cache failed (continuing): ${(err as Error).message}\n`,
-          )
-        }
+        // RFC H removes the per-account-quota-cache boot-warm: the
+        // auth-broker owns quota state now; the gateway reads it via
+        // `list-state` on demand and renders directly. No in-process
+        // cache to warm.
 
         // #412 boot-cleanup: clear any pre-existing turn-active marker.
         // By definition no turn can be in flight when the gateway just
@@ -13208,23 +13443,6 @@ void (async () => {
           }
         } catch {}
 
-        // Auto-fallback on quota exhaustion. Periodically polls
-        // the active slot's rate-limit headers; when utilization >= 99.5%
-        // or a 429 is observed, marks the slot exhausted, swaps to the
-        // next healthy slot via src/auth, restarts the agent, and posts
-        // a notification to the owner chat. See telegram-plugin/auto-fallback.ts
-        // for the pure decision logic + notification builder.
-        //
-        // Default poll cadence: every 60 minutes. Set
-        // SWITCHROOM_AUTO_FALLBACK_POLL_MS=0 to disable the background
-        // poller. Pre-v0.6.12 a manual `/authfallback` typed command
-        // also ran the same check; that command was removed in favour
-        // of the `/auth` dashboard's Switch primary picker.
-        const AUTO_FALLBACK_POLL_MS = Number(process.env.SWITCHROOM_AUTO_FALLBACK_POLL_MS ?? 60 * 60_000)
-        if (AUTO_FALLBACK_POLL_MS > 0) {
-          setInterval(() => { void runAutoFallbackCheck({ trigger: 'scheduled' }) }, AUTO_FALLBACK_POLL_MS).unref()
-        }
-
         // Credit-exhaustion watcher (#348). Reads `<agentDir>/.claude/.claude.json`
         // for `cachedExtraUsageDisabledReason`. Fires a Telegram notification
         // on transition into / out of fatal billing states (out_of_credits,