switchroom 0.19.1 → 0.19.3

package/telegram-plugin/tests/auth-add-flow.test.ts

@@ -60,6 +60,10 @@ import {
   handleAuthCommand,
   isAuthAdmin,
   validateAuthAddLabel,
+  readdPrecheckError,
+  runReaddPrecheck,
+  formatGrantedScopesReply,
+  REQUIRED_USAGE_SCOPE,
 } from '../gateway/auth-command.js'
 import {
   pendingAuthAddFlows,
@@ -111,6 +115,7 @@ function makeMockTmuxOps(opts: {
 } = {}): AuthAddTmuxOps & {
   newSessionCalls: Array<{ socket: string; session: string; env: Record<string, string>; cmd: string }>
   sendCalls: Array<{ socket: string; session: string; text: string }>
+  sendKeyCalls: Array<{ socket: string; session: string; key: string }>
   killCalls: Array<{ socket: string; session: string }>
   captureCallCount: number
   sessionAlive: boolean
@@ -123,12 +128,14 @@ function makeMockTmuxOps(opts: {
   let sessionAlive = opts.initialSessionAlive ?? true
   const newSessionCalls: Array<{ socket: string; session: string; env: Record<string, string>; cmd: string }> = []
   const sendCalls: Array<{ socket: string; session: string; text: string }> = []
+  const sendKeyCalls: Array<{ socket: string; session: string; key: string }> = []
   const killCalls: Array<{ socket: string; session: string }> = []
   let captureCallCount = 0
 
   const mock = {
     get newSessionCalls() { return newSessionCalls },
     get sendCalls() { return sendCalls },
+    get sendKeyCalls() { return sendKeyCalls },
     get killCalls() { return killCalls },
     get captureCallCount() { return captureCallCount },
     get sessionAlive() { return sessionAlive },
@@ -149,6 +156,9 @@ function makeMockTmuxOps(opts: {
       sendCalls.push({ socket, session, text })
       mock.onSend?.(socket, session, text)
     },
+    sendKey(socket: string, session: string, key: string) {
+      sendKeyCalls.push({ socket, session, key })
+    },
     hasSession(socket: string, session: string): boolean {
       void socket; void session
       return sessionAlive
@@ -166,12 +176,12 @@ function makeMockTmuxOps(opts: {
 describe('parseAuthCommand — /auth add and /auth cancel', () => {
   it('recognises "/auth add <label>" with a valid label', () => {
     const p = parseAuthCommand('/auth add alice@example.com')
-    expect(p).toEqual({ kind: 'add', label: 'alice@example.com' })
+    expect(p).toEqual({ kind: 'add', label: 'alice@example.com', replace: false })
   })
 
   it('recognises gmail-tag labels (the + character)', () => {
     const p = parseAuthCommand('/auth add alice+work@example.com')
-    expect(p).toEqual({ kind: 'add', label: 'alice+work@example.com' })
+    expect(p).toEqual({ kind: 'add', label: 'alice+work@example.com', replace: false })
   })
 
   it('treats "/auth add" with no label as a help reply', () => {
@@ -191,7 +201,7 @@ describe('parseAuthCommand — /auth add and /auth cancel', () => {
     // whitespace is the parser's contract — the validator catches
     // shape violations on the first token.
     const p = parseAuthCommand('/auth add foo bar')
-    expect(p).toEqual({ kind: 'add', label: 'foo' })
+    expect(p).toEqual({ kind: 'add', label: 'foo', replace: false })
   })
 
   it('rejects an over-length label (>64 chars)', () => {
@@ -260,7 +270,7 @@ describe('isAuthAdmin', () => {
 describe('handleAuthCommand — add/cancel are gateway-routed (defensive contract)', () => {
   it('returns a "not routed" error for parsed.kind === "add" so the contract is loud if a future refactor forgets the gateway dispatch', async () => {
     const reply = await handleAuthCommand(
-      { kind: 'add', label: 'foo' },
+      { kind: 'add', label: 'foo', replace: false },
       {
         agentName: 'clerk',
         isAdmin: true,
@@ -272,7 +282,7 @@ describe('handleAuthCommand — add/cancel are gateway-routed (defensive contrac
 
   it('refuses /auth add for non-admin before the not-routed branch', async () => {
     const reply = await handleAuthCommand(
-      { kind: 'add', label: 'foo' },
+      { kind: 'add', label: 'foo', replace: false },
       {
         agentName: 'other',
         isAdmin: false,
@@ -657,6 +667,161 @@ describe('mocked-broker addAccount integration sketch', () => {
       expect(addAccountSpy).toHaveBeenCalledTimes(1)
     })
   })
+
+  it('readd threads replace=true through to the broker addAccount verb', async () => {
+    const fakeCredentials = {
+      claudeAiOauth: {
+        accessToken: 'sk-ant-oat01-test-' + 'x'.repeat(40),
+        expiresAt: Date.now() + 3600_000,
+        scopes: ['org:create_api_key', 'user:profile', 'user:inference'],
+      },
+    }
+    const addAccountSpy = vi.fn(async (label: string, _c: typeof fakeCredentials, replace?: boolean) => ({
+      label,
+      replace,
+    }))
+    // Plain add → replace false; readd → replace true. Both round-trip.
+    const added = await addAccountSpy('pooled@example.com', fakeCredentials, false)
+    const readded = await addAccountSpy('pooled@example.com', fakeCredentials, true)
+    expect(added.replace).toBe(false)
+    expect(readded.replace).toBe(true)
+    expect(addAccountSpy).toHaveBeenCalledTimes(2)
+  })
+})
+
+/* ── 9b. /auth readd parser + precheck + scope reply (PR C) ────────────── */
+
+describe('parseAuthCommand — /auth readd and add --replace', () => {
+  it('parses "/auth readd <label>" as an add with replace=true', () => {
+    expect(parseAuthCommand('/auth readd pooled@example.com')).toEqual({
+      kind: 'add',
+      label: 'pooled@example.com',
+      replace: true,
+    })
+  })
+
+  it('parses "/auth add <label> --replace" as replace=true too', () => {
+    expect(parseAuthCommand('/auth add pooled@example.com --replace')).toEqual({
+      kind: 'add',
+      label: 'pooled@example.com',
+      replace: true,
+    })
+  })
+
+  it('plain "/auth add <label>" stays replace=false', () => {
+    expect(parseAuthCommand('/auth add fresh@example.com')).toEqual({
+      kind: 'add',
+      label: 'fresh@example.com',
+      replace: false,
+    })
+  })
+
+  it('"/auth readd" with no label is a help reply', () => {
+    const p = parseAuthCommand('/auth readd')
+    expect(p?.kind).toBe('help')
+    if (p?.kind === 'help') expect(p.reason).toMatch(/Usage: \/auth readd/)
+  })
+
+  it('rejects an unknown flag on add/readd', () => {
+    const p = parseAuthCommand('/auth add foo --wipe')
+    expect(p?.kind).toBe('help')
+    if (p?.kind === 'help') expect(p.reason).toMatch(/Unknown flag/i)
+  })
+
+  it('is case-insensitive on the readd verb', () => {
+    expect(parseAuthCommand('/auth READD foo')).toEqual({ kind: 'add', label: 'foo', replace: true })
+  })
+})
+
+describe('readdPrecheckError — exists gate', () => {
+  it('readd of a NONEXISTENT label errors clearly', () => {
+    const err = readdPrecheckError('ghost@example.com', true, false)
+    expect(err).toMatch(/no account named/i)
+    expect(err).toMatch(/ghost@example\.com/)
+  })
+
+  it('readd of an EXISTING label passes (null)', () => {
+    expect(readdPrecheckError('pooled@example.com', true, true)).toBeNull()
+  })
+
+  it('plain add of an EXISTING label errors and points at readd', () => {
+    const err = readdPrecheckError('pooled@example.com', false, true)
+    expect(err).toMatch(/already exists/i)
+    expect(err).toMatch(/\/auth readd/)
+  })
+
+  it('plain add of a NEW label passes (null)', () => {
+    expect(readdPrecheckError('fresh@example.com', false, false)).toBeNull()
+  })
+})
+
+describe('runReaddPrecheck — broker-backed wrapper (extracted from gateway.ts)', () => {
+  const clientWith = (labels: string[]) => ({
+    listState: async () => ({ accounts: labels.map((label) => ({ label })) }) as any,
+  })
+
+  it('readd of an EXISTING label queries the broker and passes (null)', async () => {
+    const err = await runReaddPrecheck(
+      async () => clientWith(['pooled@example.com']) as any,
+      'pooled@example.com',
+      true,
+    )
+    expect(err).toBeNull()
+  })
+
+  it('readd of a NONEXISTENT label surfaces the precheck error', async () => {
+    const err = await runReaddPrecheck(
+      async () => clientWith([]) as any,
+      'ghost@example.com',
+      true,
+    )
+    expect(err).toMatch(/no account named/i)
+  })
+
+  it('plain add of an EXISTING label surfaces the precheck error', async () => {
+    const err = await runReaddPrecheck(
+      async () => clientWith(['pooled@example.com']) as any,
+      'pooled@example.com',
+      false,
+    )
+    expect(err).toMatch(/already exists/i)
+  })
+
+  it('best-effort: null client (broker unreachable) skips the precheck (null)', async () => {
+    const err = await runReaddPrecheck(async () => null, 'x@example.com', true)
+    expect(err).toBeNull()
+  })
+
+  it('best-effort: a throwing broker is swallowed and skips the precheck (null)', async () => {
+    const err = await runReaddPrecheck(
+      async () => ({ listState: async () => { throw new Error('broker down') } }) as any,
+      'x@example.com',
+      false,
+    )
+    expect(err).toBeNull()
+  })
+})
+
+describe('formatGrantedScopesReply — scope-in-reply (structured, no scraping)', () => {
+  it('lists granted scopes and confirms when user:profile is present', () => {
+    const r = formatGrantedScopesReply(['org:create_api_key', 'user:profile', 'user:inference'])
+    expect(r.hasUsageScope).toBe(true)
+    expect(r.text).toContain('user:profile')
+    expect(r.text).toMatch(/unlocked/i)
+  })
+
+  it('warns LOUDLY when user:profile is absent (the setup-token footgun)', () => {
+    const r = formatGrantedScopesReply(['user:inference'])
+    expect(r.hasUsageScope).toBe(false)
+    expect(r.text).toMatch(/MISSING/)
+    expect(r.text).toContain(REQUIRED_USAGE_SCOPE)
+  })
+
+  it('warns when the token reports no scopes at all', () => {
+    const r = formatGrantedScopesReply(undefined)
+    expect(r.hasUsageScope).toBe(false)
+    expect(r.text).toMatch(/No scopes reported/i)
+  })
 })
 
 /* ── 10. Help text mentions add + cancel ─────────────────────────────── */
@@ -773,6 +938,9 @@ printf '{\\n  "claudeAiOauth": {\\n    "accessToken": "${fakeAccessToken}",\\n
       send(_socket, session, text) {
         return realOps.send(tmuxSocket, session, text)
       },
+      sendKey(_socket, session, key) {
+        return realOps.sendKey(tmuxSocket, session, key)
+      },
       hasSession(_socket, session) {
         return realOps.hasSession(tmuxSocket, session)
       },
@@ -816,6 +984,200 @@ printf '{\\n  "claudeAiOauth": {\\n    "accessToken": "${fakeAccessToken}",\\n
   }, 30_000)
 })
 
+/* ── 12. via-claude broad-scope minter (PR B) ─────────────────────────── */
+
+describe('startAccountAuthSession — via-claude mode (broad scope)', () => {
+  // The picker-rendered broad-scope authorize URL (org:create_api_key +
+  // user:profile + user:inference …). This is what `claude` (not setup-token)
+  // emits after "Claude account with subscription".
+  const BROAD_URL =
+    'https://claude.com/cai/oauth/authorize?code=true&client_id=x&response_type=code' +
+    '&scope=org%3Acreate_api_key+user%3Aprofile+user%3Ainference+user%3Asessions%3Aclaude_code' +
+    '&code_challenge=AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-z&state=s'
+
+  it('defaults to via-claude mode: spawns bare `claude` (NOT `claude setup-token`) and reports mode', async () => {
+    const mock = makeMockTmuxOps({ captureResponses: [BROAD_URL] })
+    const result = await startAccountAuthSession('broad@example.com', {
+      home: workspace,
+      tmuxOps: mock,
+      urlTimeoutMs: 3_000,
+    })
+    expect(result.mode).toBe('via-claude')
+    // cmd must be the bare login picker, not setup-token (setup-token mints
+    // only user:inference, which server: agents refuse).
+    expect(mock.newSessionCalls[0].cmd).toBe('claude')
+    expect(mock.newSessionCalls[0].cmd).not.toMatch(/setup-token/)
+    cleanScratchDir(result.scratchDir)
+  })
+
+  it('dispatches the pre-paste picker choreography (theme + login-method Enter) via sendKey before the URL', async () => {
+    // Pane walks: theme picker → login-method picker → URL. Each fires one
+    // Enter via sendKey (bare key, never the literal-code `send`).
+    const mock = makeMockTmuxOps({
+      captureResponses: [
+        'Choose the text style that looks best with your terminal',
+        'Select login method:\n  1. Claude account with subscription',
+        BROAD_URL,
+      ],
+    })
+    const result = await startAccountAuthSession('picker@example.com', {
+      home: workspace,
+      tmuxOps: mock,
+      urlTimeoutMs: 5_000,
+    })
+    // Two pre-paste Enters dispatched via sendKey, both bare "Enter".
+    expect(mock.sendKeyCalls.map((c) => c.key)).toEqual(['Enter', 'Enter'])
+    // The literal-code `send` (which would echo a secret) is NOT used pre-paste.
+    expect(mock.sendCalls).toHaveLength(0)
+    expect(result.loginUrl).toMatch(/^https:\/\/claude\.com\/cai\/oauth\/authorize\?/)
+    cleanScratchDir(result.scratchDir)
+  })
+
+  it('surfaces both URL shapes the picker can render (claude.ai/ and claude.com/cai/)', async () => {
+    for (const url of [
+      'https://claude.ai/oauth/authorize?client_id=x&code=true&scope=user%3Aprofile',
+      BROAD_URL,
+    ]) {
+      const mock = makeMockTmuxOps({ captureResponses: [`\x1b[0m${url}\nPaste code here:\n`] })
+      const result = await startAccountAuthSession('urlshape', {
+        home: workspace,
+        tmuxOps: mock,
+        urlTimeoutMs: 3_000,
+      })
+      expect(result.loginUrl).toContain('/oauth/authorize?')
+      expect(result.loginUrl).not.toMatch(/\s/) // line-wrap collapsed
+      cleanScratchDir(result.scratchDir)
+    }
+  })
+
+  it('setup-token mode is still available and uses `claude setup-token` with no picker dispatch', async () => {
+    const url =
+      'https://claude.com/cai/oauth/authorize?code=true&client_id=y&response_type=code&code_challenge=AbCdEfGhIjKlMnOpQrStUvWxYz0123456789_-z'
+    const mock = makeMockTmuxOps({ captureResponses: [url] })
+    const result = await startAccountAuthSession('narrow@example.com', {
+      home: workspace,
+      tmuxOps: mock,
+      urlTimeoutMs: 3_000,
+      mode: 'setup-token',
+    })
+    expect(result.mode).toBe('setup-token')
+    expect(mock.newSessionCalls[0].cmd).toBe('claude setup-token')
+    expect(mock.sendKeyCalls).toHaveLength(0) // no picker choreography
+    cleanScratchDir(result.scratchDir)
+  })
+})
+
+describe('submitAccountAuthCode — via-claude broad-scope + blind post-paste Enter (PR B)', () => {
+  function makeFlow(scratchDir: string, mode: 'via-claude' | 'setup-token'): PendingAuthAddFlow {
+    return {
+      label: 'broad@example.com',
+      scratchDir,
+      tmuxSocket: 'switchroom-test',
+      tmuxSession: 'auth-add-broad-abc123',
+      startedAt: Date.now(),
+      mode,
+    }
+  }
+
+  it('returns the minted broad scopes (user:profile present) and NEVER captures after the code', async () => {
+    const scratchDir = mkdtempSync(join(workspace, 'broad-'))
+    const credPath = join(scratchDir, '.credentials.json')
+    const broadCreds = JSON.stringify({
+      claudeAiOauth: {
+        accessToken: 'sk-ant-oat01-test-' + 'e'.repeat(40),
+        refreshToken: 'sk-ant-ort01-test',
+        expiresAt: Date.now() + 8 * 3600_000,
+        scopes: [
+          'org:create_api_key',
+          'user:profile',
+          'user:inference',
+          'user:sessions:claude_code',
+          'user:mcp_servers',
+          'user:file_upload',
+        ],
+        subscriptionType: 'max',
+      },
+    })
+    const mock = makeMockTmuxOps({ initialSessionAlive: true })
+    let sendCalled = false
+    let captureAfterSend = false
+    mock.onSend = () => {
+      sendCalled = true
+      writeFileSync(credPath, broadCreds, 'utf8')
+    }
+    mock.onCapture = () => { if (sendCalled) captureAfterSend = true }
+
+    const creds = await submitAccountAuthCode(makeFlow(scratchDir, 'via-claude'), 'browser-code-xyz', {
+      pollIntervalMs: 20,
+      pollTimeoutMs: 3_000,
+      tmuxOps: mock,
+    })
+
+    // The actual mission outcome: user:profile made it through.
+    expect(creds.claudeAiOauth.scopes).toContain('user:profile')
+    expect(creds.claudeAiOauth.scopes).toEqual(
+      expect.arrayContaining(['org:create_api_key', 'user:profile', 'user:inference']),
+    )
+    // Invariant preserved: no capture-pane after the code paste.
+    expect(captureAfterSend).toBe(false)
+    expect(mock.captureCallCount).toBe(0)
+  })
+
+  it('dispatches BLIND Enter key-presses after the code (no capture) to clear picker screens', async () => {
+    const scratchDir = mkdtempSync(join(workspace, 'blind-'))
+    const credPath = join(scratchDir, '.credentials.json')
+    const mock = makeMockTmuxOps({ initialSessionAlive: true })
+    // Materialise creds only AFTER the blind Enters have had a chance to fire
+    // (mimics a picker screen Enter-gating the credentials flush).
+    let ticks = 0
+    mock.onSend = () => {
+      // schedule cred write a few polls later via the poll loop below
+      ticks = 0
+    }
+    // Use a tight blind-enter schedule so the test is fast.
+    const submitP = submitAccountAuthCode(makeFlow(scratchDir, 'via-claude'), 'code-abc', {
+      pollIntervalMs: 10,
+      pollTimeoutMs: 3_000,
+      tmuxOps: mock,
+      blindEnterDelaysMs: [15, 30],
+    })
+    // Write creds after the blind Enters would have fired.
+    const timer = setInterval(() => {
+      ticks++
+      if (ticks >= 6) {
+        writeFileSync(credPath, JSON.stringify({
+          claudeAiOauth: { accessToken: 'sk-ant-oat01-test-' + 'f'.repeat(40), scopes: ['user:profile'] },
+        }), 'utf8')
+        clearInterval(timer)
+      }
+    }, 10)
+    const creds = await submitP
+    clearInterval(timer)
+    // Blind Enters were dispatched via sendKey, and capture-pane never was.
+    expect(mock.sendKeyCalls.every((c) => c.key === 'Enter')).toBe(true)
+    expect(mock.sendKeyCalls.length).toBeGreaterThanOrEqual(1)
+    expect(mock.captureCallCount).toBe(0)
+    expect(creds.claudeAiOauth.scopes).toContain('user:profile')
+  })
+
+  it('setup-token mode dispatches NO blind Enters (session exits on its own)', async () => {
+    const scratchDir = mkdtempSync(join(workspace, 'st-'))
+    const credPath = join(scratchDir, '.credentials.json')
+    const mock = makeMockTmuxOps({ initialSessionAlive: true })
+    mock.onSend = () => {
+      writeFileSync(credPath, JSON.stringify({
+        claudeAiOauth: { accessToken: 'sk-ant-oat01-test-' + 'g'.repeat(40), scopes: ['user:inference'] },
+      }), 'utf8')
+    }
+    await submitAccountAuthCode(makeFlow(scratchDir, 'setup-token'), 'code', {
+      pollIntervalMs: 20,
+      pollTimeoutMs: 2_000,
+      tmuxOps: mock,
+    })
+    expect(mock.sendKeyCalls).toHaveLength(0)
+  })
+})
+
 /* ── helpers ─────────────────────────────────────────────────────────── */
 
 function randomHex(): string {

package/telegram-plugin/tests/auth-snapshot-format.test.ts

@@ -1199,3 +1199,44 @@ describe('#2494 — renderAuthSnapshotFormat2 row rendering (out_of_credits demo
     expect(out).not.toContain('All accounts blocked');
   });
 });
+
+// ── retired / org-blocked (in-service classification, PR1) ────────────
+describe('classifyHealth — retired / org-blocked precedence', () => {
+  // A retired/org-disabled account must NEVER read as available: config and
+  // entitlement outrank the quota windows for any non-active account.
+  const healthyQ = quota({ fiveHourUtilizationPct: 5, sevenDayUtilizationPct: 10 });
+
+  it('non-active account with inService:false → retired, even on healthy quota', () => {
+    expect(classifyHealth(snap({ inService: false, quota: healthyQ }))).toBe('retired');
+  });
+  it('non-active account with entitlementBlocked → org-blocked', () => {
+    expect(classifyHealth(snap({ entitlementBlocked: true, quota: healthyQ }))).toBe('org-blocked');
+  });
+  it('entitlement block outranks retirement', () => {
+    expect(
+      classifyHealth(snap({ inService: false, entitlementBlocked: true, quota: healthyQ })),
+    ).toBe('org-blocked');
+  });
+  it('absent inService defaults to in-service (a pre-field broker is never falsely retired)', () => {
+    expect(classifyHealth(snap({ quota: healthyQ }))).toBe('healthy');
+  });
+  it('the active account keeps its quota-derived health even if inService is false', () => {
+    // active is in-service by definition; the guard skips retirement for it.
+    expect(classifyHealth(snap({ isActive: true, inService: false, quota: healthyQ }))).toBe('healthy');
+  });
+});
+
+describe('recommendation — excludes retired/org-blocked accounts', () => {
+  it('a retired account (even with healthy quota) is never offered as a switch target', () => {
+    // active is throttling; the only OTHER account is retired but at 0% util.
+    // Without the exclusion it would be recommended as a healthy switch target;
+    // with it, the retired account is invisible → "no healthy alternative".
+    const snaps: AccountSnapshot[] = [
+      snap({ label: 'a@x', isActive: true, quota: quota({ fiveHourUtilizationPct: 90 }) }),
+      snap({ label: 'retired@x', inService: false, quota: quota({ fiveHourUtilizationPct: 0 }) }),
+    ];
+    const out = recommendation(snaps, NOW);
+    expect(out).not.toContain('retired@x');
+    expect(out).toContain('no healthy alternative');
+  });
+});

package/telegram-plugin/tests/external-spend.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for External OpenRouter/$ spend (layout B on /usage).
+ * Pure filter/format coverage lives primarily in
+ * `src/litellm/external-spend.test.ts`. This file covers the card
+ * block formatter + broker-backed fetch ExternalSpendSummary path.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  formatExternalSpendBlock,
+  fetchExternalSpendSummary,
+  clearExternalSpendCache,
+  formatUsd,
+  isExternalModel,
+  shortModelLabel,
+  summarizeExternalSpend,
+} from '../external-spend.js';
+import { renderUsageCard } from '../quota-bar-format.js';
+import type { AccountSnapshot } from '../auth-snapshot-format.js';
+import type { QuotaUtilization } from '../quota-check.js';
+
+const NOW = new Date('2026-07-19T15:30:00.000Z');
+
+beforeEach(() => {
+  clearExternalSpendCache();
+});
+
+describe('re-exported pure helpers', () => {
+  it('filter / labels / money still work from the telegram module', () => {
+    expect(isExternalModel('openrouter/openai/gpt-oss-20b')).toBe(true);
+    expect(isExternalModel('claude-sonnet-5')).toBe(false);
+    expect(shortModelLabel('openrouter/x-ai/grok-4.5')).toBe('grok-4.5');
+    expect(formatUsd(8.07)).toBe('$8.07');
+    const s = summarizeExternalSpend(
+      [
+        {
+          startTime: '2026-07-19',
+          models: { 'openrouter/openai/gpt-oss-20b': 1.5, 'claude-sonnet-5': 9 },
+        },
+      ],
+      NOW,
+    );
+    expect(s.day24hUsd).toBeCloseTo(1.5, 5);
+  });
+});
+
+describe('formatExternalSpendBlock', () => {
+  it('renders locked layout B', () => {
+    expect(
+      formatExternalSpendBlock({
+        day24hUsd: 8.07,
+        day7dUsd: 119.89,
+        top: [
+          { label: 'gpt-oss-20b', usd: 6.1 },
+          { label: 'grok-4.5', usd: 1.18 },
+          { label: 'gemini-3.1-flash-lite', usd: 0.79 },
+        ],
+      }),
+    ).toEqual([
+      '- 💸 External',
+      '- 24h `$8.07` · 7d `$119.89`',
+      '- top `gpt-oss-20b $6.10` · `grok-4.5 $1.18` · `gemini-3.1-flash-lite $0.79`',
+    ]);
+  });
+
+  it('omits top and returns [] for null', () => {
+    expect(formatExternalSpendBlock({ day24hUsd: 0, day7dUsd: 0, top: [] })).toEqual([
+      '- 💸 External',
+      '- 24h `$0.00` · 7d `$0.00`',
+    ]);
+    expect(formatExternalSpendBlock(null)).toEqual([]);
+  });
+});
+
+describe('fetchExternalSpendSummary (broker path)', () => {
+  it('returns null when broker says unavailable', async () => {
+    const s = await fetchExternalSpendSummary({
+      getExternalSpend: async () => ({ available: false, reason: 'master_key_unavailable' }),
+      bypassCache: true,
+    });
+    expect(s).toBeNull();
+  });
+
+  it('maps available broker payload + caches', async () => {
+    let calls = 0;
+    const getExternalSpend = vi.fn(async () => {
+      calls += 1;
+      return {
+        available: true,
+        day24hUsd: 1.5,
+        day7dUsd: 10,
+        top: [{ label: 'gpt-oss-20b', usd: 1.5 }],
+        served: 'live' as const,
+        capturedAtMs: Date.now(),
+      };
+    });
+    const first = await fetchExternalSpendSummary({
+      getExternalSpend,
+      bypassCache: true,
+    });
+    expect(first).toEqual({
+      day24hUsd: 1.5,
+      day7dUsd: 10,
+      top: [{ label: 'gpt-oss-20b', usd: 1.5 }],
+    });
+    const second = await fetchExternalSpendSummary({ getExternalSpend });
+    expect(second?.day24hUsd).toBeCloseTo(1.5, 5);
+    expect(calls).toBe(1);
+  });
+
+  it('returns null on thrown broker error', async () => {
+    const s = await fetchExternalSpendSummary({
+      getExternalSpend: async () => {
+        throw new Error('unreachable');
+      },
+      bypassCache: true,
+    });
+    expect(s).toBeNull();
+  });
+});
+
+describe('renderUsageCard + externalSpend', () => {
+  function quota(part: Partial<QuotaUtilization>): QuotaUtilization {
+    return {
+      fiveHourUtilizationPct: 0,
+      sevenDayUtilizationPct: 0,
+      fiveHourResetAt: null,
+      sevenDayResetAt: null,
+      representativeClaim: null,
+      overageStatus: null,
+      overageDisabledReason: null,
+      ...part,
+    };
+  }
+  const snapshots: AccountSnapshot[] = [
+    {
+      label: 'ken@example.com',
+      isActive: true,
+      quota: quota({
+        fiveHourUtilizationPct: 0,
+        sevenDayUtilizationPct: 47,
+        fiveHourResetAt: new Date(NOW.getTime() + 60 * 60_000),
+        sevenDayResetAt: new Date(NOW.getTime() + (3 * 24 + 1) * 60 * 60_000),
+      }),
+    },
+  ];
+  const exhausted = new Map<string, boolean>([['ken@example.com', false]]);
+
+  it('inserts External between recommendation and freshness', () => {
+    const out = renderUsageCard(snapshots, exhausted, {
+      now: NOW,
+      externalSpend: {
+        day24hUsd: 8.07,
+        day7dUsd: 119.89,
+        top: [{ label: 'gpt-oss-20b', usd: 6.1 }],
+      },
+    });
+    const lines = out.split('\n');
+    const recIdx = lines.findIndex((l) => l.includes('Recommendation'));
+    const extIdx = lines.findIndex((l) => l.includes('💸 External'));
+    expect(extIdx).toBe(recIdx + 1);
+    expect(lines[lines.length - 1]).toBe('_Live_');
+  });
+
+  it('omits External when null', () => {
+    const out = renderUsageCard(snapshots, exhausted, { now: NOW, externalSpend: null });
+    expect(out).not.toContain('💸 External');
+  });
+});