switchroom 0.10.0 → 0.11.1

package/telegram-plugin/fleet-fallback-gate.ts

@@ -0,0 +1,105 @@
+/**
+ * Re-entry guard + dedup window for fleet-wide auto-fallback.
+ *
+ * Lifted out of gateway.ts so the dedup state is constructable per-test
+ * (gateway.ts module state was hard to reach from vitest — every test
+ * shared the same in-flight Promise + last-fired timestamp).
+ *
+ * Contract (the "honesty contract" from PR #1317 review):
+ *
+ *   `wouldFire()` is the SYNCHRONOUS read the model-unavailable card
+ *   uses to decide whether to advertise "Auto-failover in progress".
+ *   It MUST agree with the dispatcher's actual behavior — otherwise
+ *   the card lies (claims a swap is coming when the dispatcher will
+ *   dedup-drop or bail).
+ *
+ *   Three reasons `wouldFire()` returns false:
+ *     1. A swap is already in flight (collapse concurrent fires).
+ *     2. The post-trigger dedup window is still active (the user
+ *        already saw a swap announcement; another one would oscillate).
+ *     3. The broker is unreachable — the dispatcher would just bail
+ *        with `reason=no-broker-client`, leaving the card to lie.
+ *        Optional: only checked when `brokerReachable` is supplied.
+ *
+ *   `markFired()` is called ONLY on actual swaps (kind: 'switched').
+ *   No-ops (no broker, no eligible target, idempotent skip) DO NOT
+ *   arm the suppression window — otherwise a transient hiccup blocks
+ *   the next 30s of legitimate fires.
+ */
+
+export interface FleetFallbackGateOptions {
+  /** Suppression window in ms after a successful swap. */
+  dedupMs: number;
+  /** Time source (overridable in tests). */
+  nowFn?: () => number;
+  /**
+   * Synchronous probe of broker reachability. Optional. Returning false
+   * makes `wouldFire()` return false so the card stays honest about a
+   * fire that would otherwise bail in the dispatcher.
+   *
+   * Synchronous on purpose: `wouldFire()` runs on the card-render path
+   * and must not block. A connection-cached flag (e.g. a UDS reachability
+   * check populated by a background heartbeat) fits this shape.
+   */
+  brokerReachable?: () => boolean;
+}
+
+export interface FleetFallbackGate {
+  /** True iff a fresh fire would actually invoke the dispatcher. */
+  wouldFire(): boolean;
+  /** Run a fire-and-forget action under the gate. Collapses concurrent
+   *  callers to the same in-flight Promise. The action's resolved value
+   *  controls whether the dedup window arms (true = arm, false = skip).
+   *  Caller-thrown errors are swallowed (logged via `onError`). */
+  fire(action: () => Promise<boolean>, onError?: (err: unknown) => void): Promise<void>;
+  /** Test seam — reset to fresh state. Production code should not call this. */
+  reset(): void;
+  /** Test/debug — current internal state. */
+  inspect(): { inFlight: boolean; lastFiredAtMs: number };
+}
+
+export function createFleetFallbackGate(opts: FleetFallbackGateOptions): FleetFallbackGate {
+  const nowFn = opts.nowFn ?? (() => Date.now());
+  let inFlight: Promise<void> | null = null;
+  // -Infinity = never fired. Concrete number = wall-clock ms of the
+  // last actual swap. Sentinel matters in tests (fake clocks at t=0
+  // would otherwise look like "just fired" and falsely arm dedup).
+  let lastFiredAtMs = Number.NEGATIVE_INFINITY;
+
+  function wouldFire(): boolean {
+    if (inFlight) return false;
+    if (nowFn() - lastFiredAtMs < opts.dedupMs) return false;
+    if (opts.brokerReachable && !opts.brokerReachable()) return false;
+    return true;
+  }
+
+  function fire(action: () => Promise<boolean>, onError?: (err: unknown) => void): Promise<void> {
+    if (inFlight) return inFlight;
+    if (nowFn() - lastFiredAtMs < opts.dedupMs) return Promise.resolve();
+    if (opts.brokerReachable && !opts.brokerReachable()) return Promise.resolve();
+
+    inFlight = (async () => {
+      try {
+        const didSwap = await action();
+        if (didSwap) lastFiredAtMs = nowFn();
+      } catch (err) {
+        if (onError) onError(err);
+      } finally {
+        inFlight = null;
+      }
+    })();
+    return inFlight;
+  }
+
+  return {
+    wouldFire,
+    fire,
+    reset() {
+      inFlight = null;
+      lastFiredAtMs = Number.NEGATIVE_INFINITY;
+    },
+    inspect() {
+      return { inFlight: inFlight !== null, lastFiredAtMs };
+    },
+  };
+}

package/telegram-plugin/gateway/approval-callback.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for `buildGrantedKeyboard` — the post-tap inline-keyboard
+ * surfaced on a granted approval card (RFC E §4.3 — granted-card
+ * confirmations gain the [ 📖 Open in Drive ] deep-link button).
+ *
+ * Scope-driven and pure, so the test runs without mocking grammy's
+ * Context or the approval kernel. The full handler in
+ * `approval-callback.ts` glues this onto the consumed-scope payload
+ * the kernel returns; the routing decision lives entirely in this
+ * builder.
+ */
+
+import { describe, expect, it } from "vitest";
+import { InlineKeyboard } from "grammy";
+import { buildGrantedKeyboard } from "./approval-callback.js";
+
+/**
+ * Helper — pull the `[{text, url}]` rows out of a grammy InlineKeyboard
+ * so we can assert without poking into its internal shape too hard.
+ */
+function rows(kb: InlineKeyboard): Array<Array<{ text: string; url?: string }>> {
+  return kb.inline_keyboard.map((row) =>
+    row.map((btn) => ({
+      text: btn.text,
+      ...("url" in btn ? { url: btn.url } : {}),
+    })),
+  );
+}
+
+describe("buildGrantedKeyboard — Drive scopes", () => {
+  it("emits Open-in-Drive for a single-doc grant", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:D1");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/file/d/D1/view",
+        },
+      ],
+    ]);
+  });
+
+  it("emits Open-in-Drive for a folder grant (canonical folder URL)", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:folder/F1/**");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/drive/folders/F1",
+        },
+      ],
+    ]);
+  });
+
+  it("emits Open-in-Drive for write-namespace grants on a single doc", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:write:D1");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/file/d/D1/view",
+        },
+      ],
+    ]);
+  });
+
+  it("emits Open-in-Drive for suggest-namespace folder grants", () => {
+    const kb = buildGrantedKeyboard("doc:gdrive:suggest:folder/F1/**");
+    expect(kb).toBeDefined();
+    expect(rows(kb!)).toEqual([
+      [
+        {
+          text: "📖 Open in Drive",
+          url: "https://drive.google.com/drive/folders/F1",
+        },
+      ],
+    ]);
+  });
+});
+
+describe("buildGrantedKeyboard — no button cases", () => {
+  it("returns undefined for the whole-Drive grant (no specific artifact)", () => {
+    expect(buildGrantedKeyboard("doc:gdrive:**")).toBeUndefined();
+    expect(buildGrantedKeyboard("doc:gdrive:suggest:**")).toBeUndefined();
+    expect(buildGrantedKeyboard("doc:gdrive:write:**")).toBeUndefined();
+  });
+
+  it("returns undefined for non-Drive scopes (secrets, system, vault)", () => {
+    expect(buildGrantedKeyboard("secret:OPENAI_API_KEY")).toBeUndefined();
+    expect(buildGrantedKeyboard("system:reconnect:gdrive")).toBeUndefined();
+    expect(buildGrantedKeyboard("vault:read:gdrive:klanker:refresh_token")).toBeUndefined();
+  });
+
+  it("returns undefined for unparseable Drive scopes (defense in depth)", () => {
+    // A folder id containing a slash slips past prefix matching but is
+    // rejected by parseDriveScope's id-charset check — the granted-card
+    // edit MUST NOT render a URL button derived from such a string.
+    expect(buildGrantedKeyboard("doc:gdrive:folder/abc/def/**")).toBeUndefined();
+    expect(buildGrantedKeyboard("doc:gdrive:write:abc?evil=1")).toBeUndefined();
+  });
+});

package/telegram-plugin/gateway/approval-callback.ts

@@ -21,13 +21,31 @@
  * approval_lookup (RFC §10) to discover the outcome and proceed.
  */
 
-import type { Context } from "grammy";
+import { type Context, InlineKeyboard } from "grammy";
 import { parseApprovalCallback, ttlMsFromToken } from "./approval-card.js";
 import {
   approvalConsume,
   approvalRecord,
 } from "../../src/vault/approvals/client.js";
 import type { ApprovalDecisionMode } from "../../src/vault/approvals/schema.js";
+import { scopeToOpenInDriveButton } from "../../src/drive/deep-links.js";
+
+/**
+ * Build the post-tap keyboard for a granted decision. Today this is
+ * just the `[ 📖 Open in Drive ]` button when the granted scope names
+ * a specific Drive doc or folder (RFC E §4.3 — granted-card
+ * confirmations gain the deep-link). Returns `undefined` when no
+ * post-tap keyboard applies, which the gateway translates into
+ * `reply_markup: undefined` to strip the original action buttons.
+ *
+ * Pure / scope-driven — no kernel I/O — so it stays unit-testable
+ * without mocking grammy's Context.
+ */
+export function buildGrantedKeyboard(scope: string): InlineKeyboard | undefined {
+  const btn = scopeToOpenInDriveButton(scope);
+  if (btn === null) return undefined;
+  return new InlineKeyboard().url(btn.text, btn.url);
+}
 
 export async function handleApprovalCallback(
   ctx: Context,
@@ -109,7 +127,10 @@ export async function handleApprovalCallback(
     return;
   }
 
-  // Edit the original card to its post-tap state and drop the keyboard.
+  // Edit the original card to its post-tap state. Drop the original
+  // action keyboard either way; on a successful grant for a Drive
+  // scope, surface `[ 📖 Open in Drive ]` so the user can jump
+  // straight from "agent has access" to the doc (RFC E §4.3).
   const icon = granted ? "✅" : "🚫";
   const newBody =
     `${icon} ${displayMode}` +
@@ -117,8 +138,15 @@ export async function handleApprovalCallback(
       ? ` · /approvals revoke <code>${decision_id}</code>`
       : "");
 
+  const postTapKeyboard = granted && consumed.scope
+    ? buildGrantedKeyboard(consumed.scope)
+    : undefined;
+
   try {
-    await ctx.editMessageText(newBody, { parse_mode: "HTML", reply_markup: undefined });
+    await ctx.editMessageText(newBody, {
+      parse_mode: "HTML",
+      reply_markup: postTapKeyboard,
+    });
   } catch {
     // Best-effort: card may have been edited or deleted under us.
   }

package/telegram-plugin/gateway/auth-broker-client.ts

@@ -30,6 +30,8 @@ export function createAuthBrokerClient(): {
     refreshAccount: (label: string) => broker.refreshAccount(label),
     setOverride: (agent: string, account: string | null) =>
       broker.setOverride(agent, account),
+    probeQuota: (accounts: readonly string[], timeoutMs?: number) =>
+      broker.probeQuota(accounts, timeoutMs),
   }
   return { client, close: () => broker.close() }
 }

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

@@ -29,6 +29,11 @@
  */
 
 import type { ListStateData, AccountState } from './auth-line.js'
+import {
+  buildSnapshotsFromState,
+  renderAuthSnapshotFormat2,
+  buildSnapshotKeyboard,
+} from '../auth-snapshot-format.js'
 
 // ─── Parser ────────────────────────────────────────────────────────────────
 
@@ -215,6 +220,16 @@ export interface AuthBrokerClient {
     agent: string,
     account: string | null,
   ): Promise<{ agent: string; account: string | null }>
+  /**
+   * Live Anthropic quota probe via the broker (#1336). The broker
+   * uses its stored accessTokens to hit `/v1/messages` server-side
+   * and returns parsed rate-limit headers. Tokens never reach the
+   * caller. Per-label results are returned in input order.
+   */
+  probeQuota(
+    accounts: readonly string[],
+    timeoutMs?: number,
+  ): Promise<{ results: Array<{ label: string; result: import('../quota-check.js').QuotaResult }> }>
 }
 
 export interface AuthCommandContext {
@@ -236,12 +251,43 @@ export interface AuthCommandContext {
    * that never reach the destructive branches can skip wiring it.
    */
   chatId?: string
+  /**
+   * Optional Format 2 enricher — when supplied, the `show`/`list`
+   * paths probe live quota for every account (in parallel) so the
+   * snapshot renders the new health-grouped shape with real-time
+   * percentages and reset countdowns. When omitted the legacy
+   * ASCII table renders, which keeps tests + broker-only callers
+   * working without spinning up the Anthropic API path.
+   *
+   * Returns a parallel array (same length, same order as
+   * `state.accounts`) of QuotaResult — the gateway passes
+   * `accounts.map(a => fetchAccountQuota(a.label, {force: true}))`.
+   */
+  liveQuotas?: (
+    accounts: AccountState[],
+  ) => Promise<import('../quota-check.js').QuotaResult[]>
+  /** Operator timezone forwarded to the Format 2 renderer. */
+  tz?: string
 }
 
 export interface AuthCommandReply {
   text: string
   /** True when the reply contains HTML markup. */
   html: boolean
+  /**
+   * Optional inline keyboard (rows of buttons). Format 2 attaches a
+   * smart-keyboard here for the fleet snapshot — switch buttons for
+   * healthy non-active accounts, plus refresh/usage/+add. Caller
+   * translates to grammy's `reply_markup` shape. Empty/missing means
+   * no keyboard.
+   */
+  keyboard?: Array<
+    Array<{
+      text: string
+      callbackData?: string
+      insertText?: string
+    }>
+  >
 }
 
 /**
@@ -282,7 +328,35 @@ export async function handleAuthCommand(
   ) {
     try {
       const state = await ctx.client.listState()
-      return { text: renderShowText(state), html: true }
+      let liveQuotas: import('../quota-check.js').QuotaResult[] | undefined
+      let liveProbedAtMs: number | undefined
+      if (ctx.liveQuotas && state.accounts.length > 0) {
+        try {
+          liveQuotas = await ctx.liveQuotas(state.accounts)
+          liveProbedAtMs = Date.now()
+        } catch {
+          // Live probe failed — fall back to legacy table silently.
+          liveQuotas = undefined
+        }
+      }
+      // Build the smart keyboard only when we have live quota data —
+      // without it we can't classify health and the buttons could
+      // tempt the user into a blocked account. When omitted, the
+      // text still renders (legacy table); just no keyboard.
+      let keyboard: AuthCommandReply['keyboard']
+      if (liveQuotas && liveQuotas.length === state.accounts.length) {
+        const snapshots = buildSnapshotsFromState(state, liveQuotas)
+        keyboard = buildSnapshotKeyboard(snapshots)
+      }
+      return {
+        text: renderShowText(state, Date.now(), {
+          liveQuotas,
+          tz: ctx.tz,
+          liveProbedAtMs,
+        }),
+        html: true,
+        keyboard,
+      }
     } catch (err) {
       return {
         text: `<b>/auth show failed:</b> ${escapeHtml((err as Error)?.message ?? String(err))}`,
@@ -609,17 +683,64 @@ export function pickRotateTarget(state: ListStateData, now: number = Date.now())
  * Telegram (HTML, monospace blocks). Three sections, each suppressed
  * when empty.
  */
-export function renderShowText(state: ListStateData, now: number = Date.now()): string {
+export interface RenderShowOpts {
+  /** Optional live quota probes, parallel to state.accounts. When
+   *  present, the Accounts section uses Format 2 (health-grouped,
+   *  causal-runway). When absent (legacy callers, broker-only render),
+   *  falls back to the original ASCII table. */
+  liveQuotas?: import('../quota-check.js').QuotaResult[]
+  /** Operator timezone for absolute reset times in Format 2. */
+  tz?: string
+  /** Wall-clock ms when the live probes returned, used for "refreshed
+   *  Ns ago" footer. Omit to suppress that footer line. */
+  liveProbedAtMs?: number
+}
+
+/**
+ * Render the fleet snapshot. Two shapes coexist transparently:
+ *
+ *   1. Format 2 (preferred) — when `opts.liveQuotas` is supplied:
+ *      health-grouped per-account view (🟢 HEALTHY / 🟡 THROTTLING /
+ *      🔴 BLOCKED), live percent + reset times, recommendation
+ *      footer. See `auth-snapshot-format.ts → renderAuthSnapshotFormat2`.
+ *
+ *   2. Legacy ASCII table — when no live data is available
+ *      (broker-only path, tests, or the live probe failed). Same
+ *      visual shape RFC §4.6 originally specified; preserved so the
+ *      broker can still answer `/auth show` with no Anthropic-API
+ *      round-trip.
+ *
+ * The Agents and Consumers tables render identically under both
+ * shapes — those tables don't depend on quota state.
+ */
+export function renderShowText(
+  state: ListStateData,
+  now: number = Date.now(),
+  opts: RenderShowOpts = {},
+): string {
   const lines: string[] = []
-  lines.push('<b>Auth — fleet snapshot</b>')
 
-  // Accounts table
-  if (state.accounts.length > 0) {
-    lines.push('')
-    lines.push('<b>Accounts</b>')
-    lines.push('<pre>')
-    lines.push(formatAccountsTable(state, now))
-    lines.push('</pre>')
+  if (state.accounts.length > 0 && opts.liveQuotas && opts.liveQuotas.length === state.accounts.length) {
+    // Format 2 path. Build snapshots, render the new shape inline at
+    // the top of the message — replaces the legacy "Auth — fleet
+    // snapshot" header + Accounts table.
+    const snapshots = buildSnapshotsFromState(state, opts.liveQuotas)
+    lines.push(
+      renderAuthSnapshotFormat2(snapshots, {
+        tz: opts.tz,
+        now: new Date(now),
+        liveProbedAtMs: opts.liveProbedAtMs,
+      }),
+    )
+  } else {
+    lines.push('<b>Auth — fleet snapshot</b>')
+    if (state.accounts.length > 0) {
+      lines.push('')
+      lines.push('<b>Accounts</b>')
+      lines.push('<pre>')
+      lines.push(formatAccountsTable(state, now))
+      lines.push('</pre>')
+    }
   }
 
   // Agents table

package/telegram-plugin/gateway/auth-status-adapter.ts

@@ -0,0 +1,101 @@
+/**
+ * Adapt the RFC H broker `auth show --json` / `auth list --json` payload
+ * (a `ListStateData`) into the per-agent `AuthSummary` shape the
+ * /status panel renders via `formatAuthLine`.
+ *
+ * Pre-RFC-H, gateway shelled out to `switchroom auth status --json`
+ * which already returned per-agent records in `AuthSummary` shape.
+ * That verb was retired; this adapter does the per-agent projection
+ * over the new fleet-broker payload.
+ *
+ * Pure & dependency-free so it can be unit-tested without a grammy
+ * Context or live broker.
+ */
+import type { AuthSummary } from '../welcome-text.js'
+
+/** Mirrors `ListStateData` in src/auth/broker/client.ts — duplicated as
+ *  a structural type so this adapter stays in the telegram-plugin
+ *  workspace without importing across the src/ boundary. */
+export interface BrokerStateView {
+  active: string
+  fallback_order: string[]
+  accounts: Array<{
+    label: string
+    expiresAt?: number
+    exhausted: boolean
+  }>
+  agents: Array<{
+    name: string
+    account: string
+    override: string | null
+  }>
+}
+
+/** Subset of `.claude.json` we need for billingType — duplicated for
+ *  the same reason as BrokerStateView. */
+export interface ClaudeJsonView {
+  oauthAccount?: {
+    billingType?: string
+  }
+}
+
+export function formatExpiresInRelative(expiresAt: number | undefined, now: number = Date.now()): string | null {
+  if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) return null
+  const delta = expiresAt - now
+  if (delta <= 0) return 'expired'
+  const days = Math.floor(delta / 86_400_000)
+  if (days >= 1) return `in ${days} day${days === 1 ? '' : 's'}`
+  const hours = Math.floor(delta / 3_600_000)
+  if (hours >= 1) return `in ${hours} hour${hours === 1 ? '' : 's'}`
+  const minutes = Math.max(1, Math.floor(delta / 60_000))
+  return `in ${minutes} minute${minutes === 1 ? '' : 's'}`
+}
+
+function mapBillingTypeToPlan(billingType: string | undefined): string | null {
+  if (!billingType) return null
+  const t = billingType.toLowerCase()
+  if (t.includes('max')) return 'Max'
+  if (t.includes('pro')) return 'Pro'
+  return billingType
+}
+
+/**
+ * Build the per-agent AuthSummary from broker state.
+ *
+ * - `authenticated` = the agent is bound to an account that the broker
+ *   knows about. Quota exhaustion is NOT counted as unauthenticated —
+ *   the agent still has valid credentials, it just can't make calls
+ *   until the broker rotates (which is a separate signal).
+ * - `auth_source` surfaces the bound account label (e.g. the email).
+ *   Under RFC H all auth flows through the broker, so the source is
+ *   "which account is currently mirrored to this agent", not the
+ *   transport.
+ * - `subscription_type` is read from the agent's `.claude.json`
+ *   because the broker doesn't track plan tier.
+ * - `expires_in` is computed from the bound account's `expiresAt`.
+ */
+export function buildAuthSummaryFromBroker(
+  state: BrokerStateView | null | undefined,
+  agentName: string,
+  claudeJson: ClaudeJsonView | null | undefined,
+  now: number = Date.now(),
+): AuthSummary | null {
+  if (!state) return null
+  const binding = state.agents.find((a) => a.name === agentName)
+  if (!binding) {
+    return {
+      authenticated: false,
+      subscription_type: mapBillingTypeToPlan(claudeJson?.oauthAccount?.billingType),
+      expires_in: null,
+      auth_source: null,
+    }
+  }
+  const account = state.accounts.find((a) => a.label === binding.account)
+  const authenticated = account !== undefined
+  return {
+    authenticated,
+    subscription_type: mapBillingTypeToPlan(claudeJson?.oauthAccount?.billingType),
+    expires_in: account ? formatExpiresInRelative(account.expiresAt, now) : null,
+    auth_source: binding.account,
+  }
+}

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

@@ -499,7 +499,7 @@ export async function runAllProbes(opts: RunProbesOpts): Promise<ProbeMap> {
   const slug = opts.agentSlug ?? opts.agentName
 
   await Promise.allSettled([
-    probeAccount(opts.agentDir, { agentName: opts.agentSlug ?? opts.agentName }).then(r => { probes.account = r }),
+    probeAccount(opts.agentDir).then(r => { probes.account = r }),
     probeAgentProcess(slug, { execFileImpl: opts.probeExecFileImpl, tmuxSupervisor: opts.tmuxSupervisor, dockerMode: opts.dockerMode }).then(r => { probes.agent = r }),
     probeGateway(opts.gatewayInfo).then(r => { probes.gateway = r }),
     probeQuota(claudeDir, opts.agentDir, opts.fetchImpl).then(r => { probes.quota = r }),

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

@@ -121,16 +121,10 @@ const TOKEN_EXPIRING_SOON_DAYS = 7
  */
 export async function probeAccount(
   agentDir: string,
-  opts: { agentName?: string } = {},
 ): Promise<ProbeResult> {
   return withTimeout('Account', (async (): Promise<ProbeResult> => {
     const claudeDir = join(agentDir, '.claude')
     const claudeJsonPath = join(claudeDir, '.claude.json')
-    // Fall back to the literal placeholder only when no agentName is plumbed
-    // through — the renderer's <code> escape will keep that safe in Telegram
-    // HTML, but real call sites should always pass the name so users can
-    // tap-to-copy a working command.
-    const agentRef = opts.agentName ?? '<agent>'
     let cfg: ClaudeJson = {}
     try {
       const raw = readFileSync(claudeJsonPath, 'utf8')
@@ -145,7 +139,10 @@ export async function probeAccount(
         status: 'degraded',
         label: 'Account',
         detail: 'not signed in',
-        nextStep: `Run \`switchroom auth login ${agentRef}\` to start the OAuth flow`,
+        // RFC H: auth is fleet-wide. Recovery is `auth add` + `auth use` —
+        // the broker then fans the active label out to every agent. There
+        // is no per-agent `auth login` verb anymore.
+        nextStep: 'Run `switchroom auth add <label> --from-oauth` then `switchroom auth use <label>` to authenticate the fleet',
       }
     }
 
@@ -176,9 +173,9 @@ export async function probeAccount(
     }
 
     const nextStep = status === 'fail'
-      ? `OAuth token expired — run \`switchroom auth login ${agentRef}\` to re-authenticate`
+      ? 'OAuth token expired — broker should auto-refresh; force with `switchroom auth refresh` or `switchroom auth add <label> --from-oauth --replace` if the refresh token is also bad'
       : status === 'degraded'
-        ? `Token expiring soon — run \`switchroom auth login ${agentRef}\` before it lapses`
+        ? 'Token expiring soon — broker auto-refreshes < 60min before expiry; force now with `switchroom auth refresh`'
         : undefined
     return {
       status,