switchroom 0.8.1 → 0.11.0

package/telegram-plugin/tests/auth-command-format2.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Integration test for the Format 2 wiring through `renderShowText` +
+ * `handleAuthCommand`. The pure formatter has dedicated tests in
+ * auth-snapshot-format.test.ts; here we cover the seam between the
+ * legacy ASCII-table path and the new health-grouped path.
+ *
+ * Headline guarantees:
+ *
+ *   1. With no liveQuotas, renderShowText produces the legacy ASCII
+ *      table shape (back-compat preserved).
+ *   2. With liveQuotas matching state.accounts.length, renderShowText
+ *      produces the Format 2 health-grouped shape (Recommendation
+ *      footer present, ASCII column header absent).
+ *   3. handleAuthCommand attaches a keyboard ONLY when liveQuotas is
+ *      supplied AND yields one quota per account (no half-rendered
+ *      buttons under partial-failure).
+ *   4. The keyboard emitted by handleAuthCommand never references a
+ *      blocked or unknown-health account in a switch button (smart-
+ *      hide rule, integration variant of the unit test in
+ *      auth-snapshot-format.test.ts).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderShowText, handleAuthCommand } from '../gateway/auth-command.js';
+import type { AuthBrokerClient, AuthCommandContext } from '../gateway/auth-command.js';
+import type { ListStateData } from '../../src/auth/broker/client.js';
+import type { QuotaResult, QuotaUtilization } from '../quota-check.js';
+
+function quota(part: Partial<QuotaUtilization>): QuotaUtilization {
+  return {
+    fiveHourUtilizationPct: 0,
+    sevenDayUtilizationPct: 0,
+    fiveHourResetAt: null,
+    sevenDayResetAt: null,
+    representativeClaim: null,
+    overageStatus: null,
+    overageDisabledReason: null,
+    ...part,
+  };
+}
+
+function qOk(part: Partial<QuotaUtilization>): QuotaResult {
+  return { ok: true, data: quota(part) };
+}
+
+const NOW_MS = new Date('2026-05-15T00:53:00Z').getTime();
+
+const FIXTURE_STATE: ListStateData = {
+  active: 'pixsoul@x',
+  fallback_order: ['ken@x', 'me@x', 'pixsoul@x'],
+  accounts: [
+    { label: 'ken@x', exhausted: false },
+    { label: 'me@x', exhausted: false },
+    { label: 'pixsoul@x', exhausted: false },
+  ],
+  agents: [{ name: 'carrie', account: 'pixsoul@x', override: null }],
+  consumers: [],
+};
+
+const FIXTURE_QUOTAS: QuotaResult[] = [
+  qOk({ fiveHourUtilizationPct: 0, sevenDayUtilizationPct: 23 }),
+  qOk({ sevenDayUtilizationPct: 100 }), // blocked
+  qOk({ fiveHourUtilizationPct: 8, sevenDayUtilizationPct: 20 }),
+];
+
+function mockClient(over: Partial<AuthBrokerClient> = {}): AuthBrokerClient {
+  return {
+    listState: vi.fn(async () => FIXTURE_STATE),
+    setActive: vi.fn(async (label: string) => ({ active: label, fanned: ['carrie'] })),
+    rmAccount: vi.fn(async (label: string) => ({ label })),
+    refreshAccount: vi.fn(async (label: string) => ({ account: label })),
+    setOverride: vi.fn(async (agent: string, account: string | null) => ({ agent, account })),
+    ...over,
+  };
+}
+
+describe('renderShowText — Format 2 vs legacy', () => {
+  it('falls back to legacy ASCII table when no liveQuotas given', () => {
+    const out = renderShowText(FIXTURE_STATE, NOW_MS);
+    expect(out).toContain('<b>Auth — fleet snapshot</b>');
+    expect(out).toContain('ACCOUNT');
+    expect(out).toContain('STATUS');
+    expect(out).toContain('EXPIRES');
+    expect(out).not.toContain('🔋');
+    expect(out).not.toContain('Recommendation:');
+  });
+
+  it('renders Format 2 when liveQuotas length matches accounts length', () => {
+    const out = renderShowText(FIXTURE_STATE, NOW_MS, {
+      liveQuotas: FIXTURE_QUOTAS,
+      tz: 'UTC',
+      liveProbedAtMs: NOW_MS,
+    });
+    expect(out).toContain('🔋 <b>Auth — fleet status</b>');
+    expect(out).toContain('Recommendation:');
+    expect(out).toContain('🔴 <b>BLOCKED</b>');
+    expect(out).toContain('🟢 <b>HEALTHY</b>');
+    // Legacy ASCII column headers should be absent
+    expect(out).not.toContain('ACCOUNT     STATUS');
+  });
+
+  it('falls back to legacy when liveQuotas length disagrees with accounts (defensive)', () => {
+    const out = renderShowText(FIXTURE_STATE, NOW_MS, {
+      liveQuotas: FIXTURE_QUOTAS.slice(0, 2), // wrong length
+    });
+    expect(out).not.toContain('🔋');
+    expect(out).toContain('ACCOUNT');
+  });
+});
+
+describe('handleAuthCommand — keyboard attachment', () => {
+  function makeCtx(overrides: Partial<AuthCommandContext> = {}): AuthCommandContext {
+    return {
+      agentName: 'carrie',
+      isAdmin: true,
+      client: mockClient(),
+      chatId: 'chat-1',
+      ...overrides,
+    };
+  }
+
+  it('attaches NO keyboard when liveQuotas is omitted (legacy callers)', async () => {
+    const reply = await handleAuthCommand({ kind: 'show' }, makeCtx());
+    expect(reply.keyboard).toBeUndefined();
+    expect(reply.text).toContain('ACCOUNT'); // legacy table
+  });
+
+  it('attaches a smart keyboard when liveQuotas yields one result per account', async () => {
+    const reply = await handleAuthCommand(
+      { kind: 'show' },
+      makeCtx({ liveQuotas: async () => FIXTURE_QUOTAS, tz: 'UTC' }),
+    );
+    expect(reply.keyboard).toBeDefined();
+    const allButtonText = reply.keyboard!.flat().map((b) => b.text);
+    // Switch button should exist for ken@x (healthy, not active)
+    expect(allButtonText).toContain('Switch fleet → ken@x');
+    // me@x is blocked — must NOT appear as a switch target
+    expect(allButtonText).not.toContain('Switch fleet → me@x');
+    // Bottom row hardware
+    expect(allButtonText).toContain('↻ Refresh');
+    expect(allButtonText).toContain('/usage');
+    expect(allButtonText).toContain('+ Add');
+  });
+
+  it('attaches no keyboard when the live probe throws (graceful degrade)', async () => {
+    const reply = await handleAuthCommand(
+      { kind: 'show' },
+      makeCtx({
+        liveQuotas: async () => {
+          throw new Error('network down');
+        },
+      }),
+    );
+    expect(reply.keyboard).toBeUndefined();
+    expect(reply.text).toContain('ACCOUNT'); // legacy table fallback
+  });
+});

package/telegram-plugin/tests/auth-command-vernacular.test.ts

@@ -0,0 +1,531 @@
+/**
+ * `/auth` CLI-vernacular alignment coverage (RFC H Decision 11 —
+ * "same shape on the CLI and in Telegram").
+ *
+ * Pins the post-/auth-add verb tree that mirrors `switchroom auth`:
+ *
+ *   list / show [<agent>] / rm <label> [confirm] / refresh [<label>]
+ *   / agent override <agent> <label|clear> / help
+ *
+ * The headline guarantees:
+ *
+ *   1. Every verb resolves through the pure parser to the right
+ *      ParsedAuthCommand kind (no I/O in `parseAuthCommand`).
+ *   2. Read verbs (`show`, `list`, `show <agent>`, `help`) are open
+ *      to any agent; mutating verbs are admin-gated.
+ *   3. The `rm` two-step confirm is paired by chat id + label and
+ *      respects the 60s TTL.
+ *   4. `rm` refuses to even prompt when the label is the fleet active
+ *      (broker enforces too, but the chat surface short-circuits for
+ *      a cleaner error).
+ *   5. `refresh` (no label) iterates every known account, once each.
+ *   6. `override` set vs clear translates the chat-ergonomic `clear`
+ *      keyword to a `null` broker argument.
+ *   7. Help text lists every verb (string-contains).
+ *
+ * Sibling to `auth-add-flow.test.ts` — keeps the new surface's tests
+ * scoped to a dedicated file rather than ballooning that one further.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+import {
+  parseAuthCommand,
+  handleAuthCommand,
+  pendingAuthRmFlows,
+  AUTH_RM_CONFIRM_TTL_MS,
+  type AuthBrokerClient,
+  type ListStateData,
+} from '../gateway/auth-command.js'
+
+/* ── Fixture builders ─────────────────────────────────────────────────── */
+
+function fakeState(over: Partial<ListStateData> = {}): ListStateData {
+  return {
+    active: 'primary',
+    fallback_order: ['primary', 'spare'],
+    accounts: [
+      {
+        label: 'primary',
+        expiresAt: Date.now() + 6 * 3600_000,
+        exhausted: false,
+        last_refreshed_at: Date.now() - 600_000,
+      },
+      {
+        label: 'spare',
+        expiresAt: Date.now() + 4 * 3600_000,
+        exhausted: false,
+      },
+    ],
+    agents: [
+      { name: 'clerk', account: 'primary', override: null },
+      { name: 'researcher', account: 'spare', override: 'spare' },
+    ],
+    consumers: [],
+    ...over,
+  }
+}
+
+interface MockClient extends AuthBrokerClient {
+  listState: ReturnType<typeof vi.fn>
+  setActive: ReturnType<typeof vi.fn>
+  rmAccount: ReturnType<typeof vi.fn>
+  refreshAccount: ReturnType<typeof vi.fn>
+  setOverride: ReturnType<typeof vi.fn>
+}
+
+function mockClient(state: ListStateData = fakeState()): MockClient {
+  return {
+    listState: vi.fn().mockResolvedValue(state),
+    setActive: vi.fn().mockResolvedValue({ active: 'spare', fanned: ['clerk'] }),
+    rmAccount: vi.fn().mockImplementation(async (label: string) => ({ label })),
+    refreshAccount: vi.fn().mockImplementation(async (label: string) => ({
+      account: label,
+      expiresAt: Date.now() + 8 * 3600_000,
+    })),
+    setOverride: vi
+      .fn()
+      .mockImplementation(async (agent: string, account: string | null) => ({
+        agent,
+        account,
+      })),
+  }
+}
+
+beforeEach(() => {
+  pendingAuthRmFlows.clear()
+})
+
+/* ── 1. Parser ────────────────────────────────────────────────────────── */
+
+describe('parseAuthCommand — new verbs', () => {
+  it('parses /auth list as { kind: "list" }', () => {
+    expect(parseAuthCommand('/auth list')).toEqual({ kind: 'list' })
+  })
+
+  it('parses /auth show <agent> as { kind: "show", agent }', () => {
+    expect(parseAuthCommand('/auth show clerk')).toEqual({
+      kind: 'show',
+      agent: 'clerk',
+    })
+  })
+
+  it('bare /auth show stays kindshow with no agent field set', () => {
+    const p = parseAuthCommand('/auth show')
+    expect(p?.kind).toBe('show')
+    expect((p as { agent?: string }).agent).toBeUndefined()
+  })
+
+  it('parses /auth rm <label> as rm-prompt', () => {
+    expect(parseAuthCommand('/auth rm spare')).toEqual({
+      kind: 'rm-prompt',
+      label: 'spare',
+    })
+  })
+
+  it('parses /auth rm <label> confirm as rm-confirmed (case-insensitive)', () => {
+    expect(parseAuthCommand('/auth rm spare confirm')).toEqual({
+      kind: 'rm-confirmed',
+      label: 'spare',
+    })
+    expect(parseAuthCommand('/auth rm spare CONFIRM')).toEqual({
+      kind: 'rm-confirmed',
+      label: 'spare',
+    })
+  })
+
+  it('rejects /auth rm <label> <bogus> with a help reason', () => {
+    const p = parseAuthCommand('/auth rm spare yesplease')
+    expect(p?.kind).toBe('help')
+    expect((p as { reason?: string }).reason).toMatch(/confirm/i)
+  })
+
+  it('rejects /auth rm with no label', () => {
+    const p = parseAuthCommand('/auth rm')
+    expect(p?.kind).toBe('help')
+    expect((p as { reason?: string }).reason).toMatch(/usage/i)
+  })
+
+  it('parses /auth refresh (no label)', () => {
+    expect(parseAuthCommand('/auth refresh')).toEqual({ kind: 'refresh' })
+  })
+
+  it('parses /auth refresh <label>', () => {
+    expect(parseAuthCommand('/auth refresh primary')).toEqual({
+      kind: 'refresh',
+      label: 'primary',
+    })
+  })
+
+  it('parses /auth agent override <agent> <label>', () => {
+    expect(parseAuthCommand('/auth agent override clerk primary')).toEqual({
+      kind: 'override-set',
+      agent: 'clerk',
+      label: 'primary',
+    })
+  })
+
+  it('parses /auth agent override <agent> clear as override-clear', () => {
+    expect(parseAuthCommand('/auth agent override clerk clear')).toEqual({
+      kind: 'override-clear',
+      agent: 'clerk',
+    })
+    // case-insensitive
+    expect(parseAuthCommand('/auth agent override clerk CLEAR')).toEqual({
+      kind: 'override-clear',
+      agent: 'clerk',
+    })
+  })
+
+  it('rejects /auth agent override with missing args', () => {
+    const a = parseAuthCommand('/auth agent override')
+    const b = parseAuthCommand('/auth agent override clerk')
+    expect(a?.kind).toBe('help')
+    expect(b?.kind).toBe('help')
+  })
+
+  it('rejects /auth agent <unknown-sub>', () => {
+    const p = parseAuthCommand('/auth agent pin clerk primary')
+    expect(p?.kind).toBe('help')
+    expect((p as { reason?: string }).reason).toMatch(/override/i)
+  })
+
+  it('parses /auth help explicitly', () => {
+    expect(parseAuthCommand('/auth help')).toEqual({ kind: 'help' })
+  })
+
+  it('routes unknown verbs to help with a reason', () => {
+    const p = parseAuthCommand('/auth nonsense')
+    expect(p?.kind).toBe('help')
+    expect((p as { reason?: string }).reason).toMatch(/unknown/i)
+  })
+
+  it('tolerates extra whitespace and bot-suffix', () => {
+    expect(parseAuthCommand('   /auth   list  ')).toEqual({ kind: 'list' })
+    expect(parseAuthCommand('/auth@switchroombot list')).toEqual({ kind: 'list' })
+    expect(parseAuthCommand('/auth\tshow\tclerk')).toEqual({
+      kind: 'show',
+      agent: 'clerk',
+    })
+  })
+
+  it('is case-insensitive on the verb', () => {
+    expect(parseAuthCommand('/auth LIST')?.kind).toBe('list')
+    expect(parseAuthCommand('/auth REFRESH')?.kind).toBe('refresh')
+    expect(parseAuthCommand('/auth Agent OVERRIDE clerk clear')).toEqual({
+      kind: 'override-clear',
+      agent: 'clerk',
+    })
+  })
+})
+
+/* ── 2. Read-verb open access ─────────────────────────────────────────── */
+
+describe('handleAuthCommand — read verbs are open to any agent', () => {
+  it('/auth list renders the fleet snapshot without an admin gate', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'list' },
+      { agentName: 'random-agent', isAdmin: false, client },
+    )
+    expect(reply.html).toBe(true)
+    expect(reply.text).toMatch(/Auth — fleet snapshot/)
+    expect(reply.text).not.toMatch(/Not authorized/i)
+    expect(client.listState).toHaveBeenCalledTimes(1)
+  })
+
+  it('/auth show <agent> renders per-agent detail for any agent', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'show', agent: 'researcher' },
+      { agentName: 'random', isAdmin: false, client },
+    )
+    expect(reply.text).toMatch(/researcher/)
+    expect(reply.text).toMatch(/override/)
+    expect(reply.text).toMatch(/spare/)
+  })
+
+  it('/auth show <unknown-agent> returns a friendly error', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'show', agent: 'ghost' },
+      { agentName: 'random', isAdmin: false, client },
+    )
+    expect(reply.text).toMatch(/no agent named/i)
+    expect(reply.text).toMatch(/ghost/)
+  })
+})
+
+/* ── 3. Admin gating ──────────────────────────────────────────────────── */
+
+describe('handleAuthCommand — admin gating', () => {
+  const nonAdmin = { agentName: 'snooper', isAdmin: false }
+
+  it('refuses /auth rm <label> for non-admin', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'rm-prompt', label: 'spare' },
+      { ...nonAdmin, client },
+    )
+    expect(reply.text).toMatch(/Not authorized/i)
+    expect(client.listState).not.toHaveBeenCalled()
+  })
+
+  it('refuses /auth rm <label> confirm for non-admin', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'rm-confirmed', label: 'spare' },
+      { ...nonAdmin, client },
+    )
+    expect(reply.text).toMatch(/Not authorized/i)
+    expect(client.rmAccount).not.toHaveBeenCalled()
+  })
+
+  it('refuses /auth refresh for non-admin', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'refresh' },
+      { ...nonAdmin, client },
+    )
+    expect(reply.text).toMatch(/Not authorized/i)
+    expect(client.refreshAccount).not.toHaveBeenCalled()
+  })
+
+  it('refuses /auth agent override <set> for non-admin', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'override-set', agent: 'clerk', label: 'spare' },
+      { ...nonAdmin, client },
+    )
+    expect(reply.text).toMatch(/Not authorized/i)
+    expect(client.setOverride).not.toHaveBeenCalled()
+  })
+
+  it('refuses /auth agent override <clear> for non-admin', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'override-clear', agent: 'clerk' },
+      { ...nonAdmin, client },
+    )
+    expect(reply.text).toMatch(/Not authorized/i)
+    expect(client.setOverride).not.toHaveBeenCalled()
+  })
+})
+
+/* ── 4. rm two-step confirm flow ──────────────────────────────────────── */
+
+describe('handleAuthCommand — /auth rm two-step confirm', () => {
+  const admin = { agentName: 'clerk', isAdmin: true }
+
+  it('prompt phase succeeds for a valid non-active label and stashes a pending entry', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'rm-prompt', label: 'spare' },
+      { ...admin, client, chatId: '999' },
+    )
+    expect(reply.text).toMatch(/about to remove/i)
+    expect(reply.text).toMatch(/spare/)
+    expect(reply.text).toMatch(/confirm/i)
+    expect(pendingAuthRmFlows.get('999')?.label).toBe('spare')
+  })
+
+  it('refuses to prompt when the label is unknown', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'rm-prompt', label: 'doesnotexist' },
+      { ...admin, client, chatId: '999' },
+    )
+    expect(reply.text).toMatch(/no account named/i)
+    expect(client.rmAccount).not.toHaveBeenCalled()
+    expect(pendingAuthRmFlows.size).toBe(0)
+  })
+
+  it('refuses to prompt when the label is the fleet active', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'rm-prompt', label: 'primary' },
+      { ...admin, client, chatId: '999' },
+    )
+    expect(reply.text).toMatch(/fleet active/i)
+    expect(reply.text).toMatch(/use/)
+    expect(client.rmAccount).not.toHaveBeenCalled()
+    expect(pendingAuthRmFlows.size).toBe(0)
+  })
+
+  it('confirm phase only fires when a matching pending entry exists', async () => {
+    const client = mockClient()
+    // Phase 1
+    await handleAuthCommand(
+      { kind: 'rm-prompt', label: 'spare' },
+      { ...admin, client, chatId: 'C' },
+    )
+    // Phase 2
+    const reply = await handleAuthCommand(
+      { kind: 'rm-confirmed', label: 'spare' },
+      { ...admin, client, chatId: 'C' },
+    )
+    expect(reply.text).toMatch(/Removed/i)
+    expect(client.rmAccount).toHaveBeenCalledTimes(1)
+    expect(client.rmAccount).toHaveBeenCalledWith('spare')
+    expect(pendingAuthRmFlows.has('C')).toBe(false)
+  })
+
+  it('confirm refuses when no prompt was issued', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'rm-confirmed', label: 'spare' },
+      { ...admin, client, chatId: 'C' },
+    )
+    expect(reply.text).toMatch(/no pending confirm/i)
+    expect(client.rmAccount).not.toHaveBeenCalled()
+  })
+
+  it('confirm refuses when the pending label does not match', async () => {
+    const client = mockClient()
+    pendingAuthRmFlows.set('C', {
+      label: 'other-label',
+      expiresAt: Date.now() + AUTH_RM_CONFIRM_TTL_MS,
+    })
+    const reply = await handleAuthCommand(
+      { kind: 'rm-confirmed', label: 'spare' },
+      { ...admin, client, chatId: 'C' },
+    )
+    expect(reply.text).toMatch(/no pending confirm/i)
+    expect(client.rmAccount).not.toHaveBeenCalled()
+  })
+
+  it('confirm refuses when the pending entry has expired', async () => {
+    const client = mockClient()
+    pendingAuthRmFlows.set('C', {
+      label: 'spare',
+      expiresAt: Date.now() - 1, // expired
+    })
+    const reply = await handleAuthCommand(
+      { kind: 'rm-confirmed', label: 'spare' },
+      { ...admin, client, chatId: 'C' },
+    )
+    expect(reply.text).toMatch(/expired|no pending confirm/i)
+    expect(client.rmAccount).not.toHaveBeenCalled()
+    // Stale entry should be reaped.
+    expect(pendingAuthRmFlows.has('C')).toBe(false)
+  })
+
+  it('TTL is the documented 60 seconds', () => {
+    expect(AUTH_RM_CONFIRM_TTL_MS).toBe(60_000)
+  })
+})
+
+/* ── 5. refresh ───────────────────────────────────────────────────────── */
+
+describe('handleAuthCommand — /auth refresh', () => {
+  const admin = { agentName: 'clerk', isAdmin: true }
+
+  it('without a label refreshes every account, once each', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'refresh' },
+      { ...admin, client },
+    )
+    expect(reply.text).toMatch(/Refreshed/)
+    expect(client.refreshAccount).toHaveBeenCalledTimes(2)
+    expect(client.refreshAccount).toHaveBeenCalledWith('primary')
+    expect(client.refreshAccount).toHaveBeenCalledWith('spare')
+  })
+
+  it('with a label refreshes that account once', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'refresh', label: 'spare' },
+      { ...admin, client },
+    )
+    expect(reply.text).toMatch(/Refreshed/)
+    expect(reply.text).toMatch(/spare/)
+    expect(client.refreshAccount).toHaveBeenCalledTimes(1)
+    expect(client.refreshAccount).toHaveBeenCalledWith('spare')
+  })
+
+  it('with an unknown label returns a friendly error and does not call the broker', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'refresh', label: 'ghost' },
+      { ...admin, client },
+    )
+    expect(reply.text).toMatch(/no account named/i)
+    expect(client.refreshAccount).not.toHaveBeenCalled()
+  })
+
+  it('reports per-account failures without aborting the whole sweep', async () => {
+    const client = mockClient()
+    client.refreshAccount.mockImplementation(async (label: string) => {
+      if (label === 'primary') throw new Error('rate-limited')
+      return { account: label, expiresAt: Date.now() + 1000 }
+    })
+    const reply = await handleAuthCommand(
+      { kind: 'refresh' },
+      { ...admin, client },
+    )
+    expect(client.refreshAccount).toHaveBeenCalledTimes(2)
+    expect(reply.text).toMatch(/Failures/i)
+    expect(reply.text).toMatch(/rate-limited/)
+  })
+})
+
+/* ── 6. override set + clear ──────────────────────────────────────────── */
+
+describe('handleAuthCommand — /auth agent override', () => {
+  const admin = { agentName: 'clerk', isAdmin: true }
+
+  it('set calls setOverride(agent, label)', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'override-set', agent: 'researcher', label: 'primary' },
+      { ...admin, client },
+    )
+    expect(client.setOverride).toHaveBeenCalledTimes(1)
+    expect(client.setOverride).toHaveBeenCalledWith('researcher', 'primary')
+    expect(reply.text).toMatch(/Override set/i)
+    expect(reply.text).toMatch(/researcher/)
+    expect(reply.text).toMatch(/primary/)
+  })
+
+  it('clear calls setOverride(agent, null) — chat "clear" → null arg', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'override-clear', agent: 'researcher' },
+      { ...admin, client },
+    )
+    expect(client.setOverride).toHaveBeenCalledTimes(1)
+    expect(client.setOverride).toHaveBeenCalledWith('researcher', null)
+    expect(reply.text).toMatch(/Override cleared/i)
+    expect(reply.text).toMatch(/researcher/)
+  })
+})
+
+/* ── 7. help text contents ────────────────────────────────────────────── */
+
+describe('handleAuthCommand — help text lists every verb', () => {
+  it('help reply mentions all the load-bearing verbs', async () => {
+    const client = mockClient()
+    const reply = await handleAuthCommand(
+      { kind: 'help' },
+      { agentName: 'x', isAdmin: true, client },
+    )
+    const text = reply.text
+    // Verbs (all variants). The help is HTML; <code> wraps each verb.
+    for (const fragment of [
+      '/auth show',
+      '/auth show &lt;agent&gt;',
+      '/auth list',
+      '/auth use',
+      '/auth rotate',
+      '/auth add',
+      '/auth cancel',
+      '/auth rm',
+      '/auth refresh',
+      '/auth agent override',
+      '/auth help',
+    ]) {
+      expect(text).toContain(fragment)
+    }
+  })
+})