switchroom 0.8.1 → 0.11.0

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

@@ -0,0 +1,123 @@
+/**
+ * Boot-card auth row formatter (RFC H §7.3).
+ *
+ * The old auth-dashboard exported `formatAccountQuotaLine` + an
+ * `AccountSummary` shape that the boot card consumed for its
+ * "Accounts (N)" section. Both source-of-truth and shape moved to
+ * the auth-broker's `list-state` response. This module reformats that
+ * response into the same one-line-per-account block the boot card
+ * used to render — visual output unchanged, data source is now the
+ * broker.
+ *
+ * Inputs: a `list-state` data shape (see
+ * `src/auth/broker/protocol.ts` → `ListStateDataSchema`) plus the
+ * caller agent's name.
+ *
+ * Output: an array of HTML-safe lines. Empty array when there's
+ * nothing to show — preserves the boot-card's silent-when-healthy
+ * default.
+ */
+
+import type { ListStateData, AccountState } from '../../src/auth/broker/client.js'
+
+export type { ListStateData, AccountState }
+
+// Local HTML-escape (mirrors the helper formerly co-located in
+// auth-dashboard.ts so we keep the same escaping discipline without
+// pulling in a heavier util).
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/** Format a duration in ms as a short relative string ("1h 22m", "12s"). */
+function formatRelativeMs(ms: number): string {
+  if (ms <= 0) return '0s'
+  const totalSec = Math.floor(ms / 1000)
+  const days = Math.floor(totalSec / 86400)
+  const hours = Math.floor((totalSec % 86400) / 3600)
+  const mins = Math.floor((totalSec % 3600) / 60)
+  const secs = totalSec % 60
+  if (days > 0) return `${days}d ${hours}h`
+  if (hours > 0) return `${hours}h ${mins}m`
+  if (mins > 0) return `${mins}m ${secs}s`
+  return `${secs}s`
+}
+
+/**
+ * Render the per-account quota inline for one account row. Returns
+ * null when there's nothing quota-shaped to say (account is healthy
+ * and we have no reset countdown to surface).
+ */
+export function formatAuthQuotaLine(acc: AccountState, now: number = Date.now()): string | null {
+  if (acc.exhausted) {
+    const until = acc.exhausted_until
+    if (until != null && until > now) {
+      return `<i>exhausted · resets in ${formatRelativeMs(until - now)}</i>`
+    }
+    return `<i>exhausted</i>`
+  }
+  return null
+}
+
+/**
+ * Boot-card auth-row block.
+ *
+ * Strategy:
+ *   1. Determine *which* account is active for `agentName` (per-agent
+ *      override wins over fleet-active).
+ *   2. Emit one row for that account marked with `▶` plus a
+ *      best-effort quota suffix.
+ *   3. Emit one row per other account in `fallback_order` marked with
+ *      `↳` so the operator sees the rollover plan at a glance.
+ *
+ * Returns an empty array when `state` is empty (no accounts) — the
+ * boot card's silent-when-healthy contract.
+ */
+export function renderAuthLine(
+  state: ListStateData,
+  agentName: string,
+  now: number = Date.now(),
+): string[] {
+  if (!state || state.accounts.length === 0) return []
+
+  const agentEntry = state.agents.find((a) => a.name === agentName)
+  const activeLabel = agentEntry?.override ?? agentEntry?.account ?? state.active
+
+  // Stable display order: active first, then `fallback_order` minus
+  // the active label, then any remaining accounts (defensive — should
+  // be empty in steady state) in account-list order.
+  const seen = new Set<string>()
+  const order: string[] = []
+  if (activeLabel) {
+    order.push(activeLabel)
+    seen.add(activeLabel)
+  }
+  for (const label of state.fallback_order) {
+    if (!seen.has(label)) {
+      order.push(label)
+      seen.add(label)
+    }
+  }
+  for (const acc of state.accounts) {
+    if (!seen.has(acc.label)) {
+      order.push(acc.label)
+      seen.add(acc.label)
+    }
+  }
+
+  const byLabel = new Map(state.accounts.map((a) => [a.label, a]))
+  const rows: string[] = []
+  rows.push(`<b>Accounts (${state.accounts.length})</b>`)
+  for (const label of order) {
+    const acc = byLabel.get(label)
+    if (!acc) continue
+    const marker = label === activeLabel ? '▶' : '↳'
+    const labelHtml = `<code>${escapeHtml(acc.label)}</code>`
+    const quotaLine = formatAuthQuotaLine(acc, now)
+    rows.push(quotaLine ? `${marker} ${labelHtml}  ${quotaLine}` : `${marker} ${labelHtml}`)
+  }
+  return rows
+}

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

@@ -33,8 +33,8 @@
  */
 
 import type { ProbeResult, GatewayRuntimeInfo } from './boot-probes.js'
-import type { AccountSummary } from '../auth-dashboard.js'
-import { formatAccountQuotaLine } from '../auth-dashboard.js'
+import type { ListStateData } from './auth-line.js'
+import { renderAuthLine } from './auth-line.js'
 import {
   probeAccount,
   probeAgentProcess,
@@ -274,9 +274,12 @@ export interface RenderBootCardOpts {
    * silent-when-healthy contract for callers that don't pass account
    * data (tests, harnesses, gateways without the auth model).
    *
-   * Closes #708.
+   * Post-RFC H (auth-broker rewire): this carries the broker's
+   * `list-state` shape — `renderAuthLine` consumes it to emit the
+   * same one-line-per-account rows as before. Callers that pass
+   * `null`/`undefined` get no section. Closes #708.
    */
-  accounts?: ReadonlyArray<AccountSummary>
+  accounts?: ListStateData | null
   /** Probe keys for which the prior boot saw degraded/fail and this boot
    *  sees ok. Rendered as a small ✅ line above the degraded section so
    *  the user gets positive-feedback that a known issue is gone. */
@@ -380,11 +383,13 @@ export function renderBootCard(opts: RenderBootCardOpts): string {
     }
   }
 
-  // Per-account quota section (issue #708) — one line per enabled
-  // account showing 5h % / 7d % / nearest reset, with the active
-  // account marked. Renders alongside the ack line so users see
-  // headroom without running /auth or /usage.
-  const accountRows = renderAccountRows(opts.accounts, opts.now ?? new Date())
+  // Per-account auth section (issue #708, RFC H rewire) — one line
+  // per known account with the active account marked. Renders
+  // alongside the ack line so users see headroom without running
+  // /auth or /usage. Source of truth: auth-broker list-state.
+  const accountRows = opts.accounts
+    ? renderAuthLine(opts.accounts, agentName, (opts.now ?? new Date()).getTime())
+    : []
 
   const sections: string[] = [ack]
   if (degradedRows.length > 0) sections.push('', ...degradedRows)
@@ -394,31 +399,12 @@ export function renderBootCard(opts: RenderBootCardOpts): string {
 }
 
 /**
- * Render the per-account quota rows. Returns an empty array when no
- * accounts are passed — keeping the boot card's silent-when-healthy
- * default for callers that don't supply account data.
- *
- * Reuses the dashboard's `formatAccountQuotaLine` so the two surfaces
- * speak with one voice.
+ * Re-export the broker-fed auth-row renderer under its historical
+ * name so direct callers (tests, harnesses) keep working without
+ * importing two modules. New code should import `renderAuthLine`
+ * from `./auth-line.js` directly.
  */
-export function renderAccountRows(
-  accounts: ReadonlyArray<AccountSummary> | undefined,
-  now: Date,
-): string[] {
-  if (!accounts || accounts.length === 0) return []
-  const rows: string[] = []
-  rows.push(`<b>Accounts (${accounts.length})</b>`)
-  const nowMs = now.getTime()
-  for (const a of accounts) {
-    const marker = a.activeForThisAgent ? '▶' : '↳'
-    const labelHtml = `<code>${escapeHtml(a.label)}</code>`
-    // formatAccountQuotaLine returns HTML (with <i> tags) so we don't
-    // re-escape — pass it through verbatim.
-    const quotaLine = formatAccountQuotaLine(a, nowMs)
-    rows.push(quotaLine ? `${marker} ${labelHtml}  ${quotaLine}` : `${marker} ${labelHtml}`)
-  }
-  return rows
-}
+export { renderAuthLine as renderAccountRows } from './auth-line.js'
 
 // ─── Probe orchestration ─────────────────────────────────────────────────────
 
@@ -480,9 +466,9 @@ export interface RunProbesOpts {
    * during the post-settle re-render so the first paint stays fast.
    */
   loadAccounts?: () =>
-    | ReadonlyArray<AccountSummary>
+    | ListStateData
     | null
-    | Promise<ReadonlyArray<AccountSummary> | null>
+    | Promise<ListStateData | null>
   /** When true, resolve the agent PID via cgroup walk instead of MainPID
    *  (which is the tmux server pid under tmux supervisor). */
   tmuxSupervisor?: boolean
@@ -513,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 }),
@@ -604,7 +590,7 @@ export async function startBootCard(
         // Per-account rows (issue #708). Loaded best-effort
         // alongside probes; failures are swallowed so the card still
         // renders correctly with no accounts section.
-        let accountRows: ReadonlyArray<AccountSummary> | null = null
+        let accountRows: ListStateData | null = null
         if (opts.loadAccounts) {
           try {
             accountRows = await opts.loadAccounts()

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,
@@ -861,7 +858,7 @@ export async function probeQuota(
         status: 'degraded',
         label: 'Quota',
         detail: 'no OAuth token',
-        nextStep: 'No OAuth token on disk — run `switchroom auth login <agent>` to authenticate',
+        nextStep: 'No OAuth token on disk — register a fleet account: `switchroom auth add <label> --from-oauth` then `switchroom auth use <label>` (RFC H)',
       }
     }
 
@@ -880,8 +877,8 @@ export async function probeQuota(
         label: 'Quota',
         detail: probe.reason,
         nextStep: isAuth
-          ? 'Auth rejected by Anthropic — re-authenticate with `switchroom auth login <agent>`'
-          : 'Anthropic quota probe failed — re-check after a minute; if persistent, `switchroom auth login <agent>`',
+          ? 'Auth rejected by Anthropic — broker auto-refreshes; if persistent, replace the account: `switchroom auth add <label> --from-oauth --replace`'
+          : 'Anthropic quota probe failed — re-check after a minute; broker auto-rotates per `auth.fallback_order`',
       }
     }
 

package/telegram-plugin/gateway/diff-preview-card.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Tests for the Telegram diff-preview card renderer — RFC E §4.2.
+ */
+
+import { describe, expect, it } from "vitest";
+import { InlineKeyboard } from "grammy";
+
+import { buildDiffPreview } from "../../src/drive/diff-preview.js";
+import type { DiffPreviewInput } from "../../src/drive/diff-preview.js";
+import { buildDiffPreviewCard } from "./diff-preview-card.js";
+
+/** Pull row-major button shape out of grammy's InlineKeyboard. */
+function rows(kb: InlineKeyboard): Array<Array<{ text: string; callback_data?: string; url?: string }>> {
+  return kb.inline_keyboard.map((row) =>
+    row.map((b) => ({
+      text: b.text,
+      ...("callback_data" in b ? { callback_data: b.callback_data } : {}),
+      ...("url" in b ? { url: b.url } : {}),
+    })),
+  );
+}
+
+function baseInput(overrides: Partial<DiffPreviewInput> = {}): DiffPreviewInput {
+  return {
+    agentName: "klanker",
+    docTitle: "Q3 Strategy Notes",
+    fileId: "DOC1",
+    mimeType: "application/vnd.google-apps.document",
+    resolvedAnchor: {
+      op: { kind: "insert_after", paragraphIndex: 4 },
+      displayName: "after heading 'Goals' (level 2)",
+    },
+    metrics: { linesAdded: 47, linesRemoved: 0 },
+    mode: "suggest",
+    ...overrides,
+  };
+}
+
+describe("buildDiffPreviewCard — suggest mode (default)", () => {
+  it("emits the wrapper-attested body + all four buttons in the RFC layout", () => {
+    const preview = buildDiffPreview(baseInput({ agentSummary: "Added Hiring section" }));
+    const card = buildDiffPreviewCard({
+      preview,
+      suggestRequestId: "aabbccdd",
+      writeRequestId: "11223344",
+    });
+
+    // Body: title bold + all preview lines.
+    expect(card.text).toContain("<b>");
+    expect(card.text).toContain("klanker");
+    expect(card.text).toContain("Q3 Strategy Notes");
+    expect(card.text).toContain("📍 after heading 'Goals' (level 2)");
+    expect(card.text).toContain("+47");
+    expect(card.text).toContain("💬");
+    expect(card.text).toContain("Added Hiring section");
+
+    const r = rows(card.reply_markup);
+    // Row 1: [Open in Drive] [Apply as suggestion]
+    expect(r[0]?.[0]?.text).toBe("📖 Open in Drive");
+    expect(r[0]?.[0]?.url).toBe("https://docs.google.com/document/d/DOC1/edit");
+    expect(r[0]?.[1]?.text).toBe("✅ Apply as suggestion");
+    expect(r[0]?.[1]?.callback_data).toBe("apv:aabbccdd:once");
+    // Row 2: [Apply directly] [Cancel]
+    expect(r[1]?.[0]?.text).toBe("⚠ Apply directly");
+    expect(r[1]?.[0]?.callback_data).toBe("apv:11223344:once");
+    expect(r[1]?.[1]?.text).toBe("🚫 Cancel");
+    expect(r[1]?.[1]?.callback_data).toBe("apv:aabbccdd:deny");
+  });
+
+  it("hides 'Apply directly' when writeRequestId is undefined", () => {
+    const preview = buildDiffPreview(baseInput());
+    const card = buildDiffPreviewCard({
+      preview,
+      suggestRequestId: "aabbccdd",
+    });
+    const flat = rows(card.reply_markup).flat();
+    expect(flat.find((b) => b.text === "⚠ Apply directly")).toBeUndefined();
+    // The other three buttons still present.
+    expect(flat.find((b) => b.text === "📖 Open in Drive")).toBeDefined();
+    expect(flat.find((b) => b.text === "✅ Apply as suggestion")).toBeDefined();
+    expect(flat.find((b) => b.text === "🚫 Cancel")).toBeDefined();
+  });
+});
+
+describe("buildDiffPreviewCard — write mode (opt-in via expand)", () => {
+  it("only emits Apply-directly + Open-in-Drive + Cancel (no suggest button)", () => {
+    const preview = buildDiffPreview(baseInput({ mode: "write" }));
+    const card = buildDiffPreviewCard({
+      preview,
+      // In write-mode the suggest id is still needed for the Cancel
+      // callback's deny channel — semantically Cancel is "don't grant
+      // either scope" but reusing the suggest id keeps the existing
+      // approval-callback handler stateless.
+      suggestRequestId: "aabbccdd",
+      writeRequestId: "11223344",
+    });
+
+    const r = rows(card.reply_markup);
+    const flat = r.flat();
+    expect(flat.find((b) => b.text === "✅ Apply as suggestion")).toBeUndefined();
+    const directly = flat.find((b) => b.text === "⚠ Apply directly");
+    expect(directly).toBeDefined();
+    expect(directly?.callback_data).toBe("apv:11223344:once");
+    // Title icon swaps to ⚠.
+    expect(card.text).toContain("⚠");
+  });
+});
+
+describe("buildDiffPreviewCard — input validation", () => {
+  it("throws on a malformed suggestRequestId", () => {
+    const preview = buildDiffPreview(baseInput());
+    expect(() =>
+      buildDiffPreviewCard({ preview, suggestRequestId: "not-hex" }),
+    ).toThrow(/8 hex chars/);
+  });
+
+  it("throws on a malformed writeRequestId", () => {
+    const preview = buildDiffPreview(baseInput());
+    expect(() =>
+      buildDiffPreviewCard({
+        preview,
+        suggestRequestId: "aabbccdd",
+        writeRequestId: "ABCDEF01", // wrong case
+      }),
+    ).toThrow(/8 hex chars/);
+  });
+});
+
+describe("buildDiffPreviewCard — fragility guards", () => {
+  it("drops the Open-in-Drive button when fileId is the 'pending-create' sentinel", () => {
+    // create_doc prep emits "pending-create" as a placeholder fileId
+    // (the doc doesn't exist yet). The renderer must NOT emit a Drive
+    // URL pointing at a nonexistent doc.
+    const preview = buildDiffPreview(
+      baseInput({ fileId: "pending-create" }),
+    );
+    const card = buildDiffPreviewCard({
+      preview,
+      suggestRequestId: "aabbccdd",
+    });
+    const flat = rows(card.reply_markup).flat();
+    expect(flat.find((b) => b.text === "📖 Open in Drive")).toBeUndefined();
+    // Apply buttons still present — the doc creation flow is still actionable.
+    expect(flat.find((b) => b.text === "✅ Apply as suggestion")).toBeDefined();
+  });
+
+  it("HTML-escapes title + lines (no markup injection from doc names)", () => {
+    const preview = buildDiffPreview(
+      baseInput({ docTitle: "<script>alert(1)</script>" }),
+    );
+    const card = buildDiffPreviewCard({
+      preview,
+      suggestRequestId: "aabbccdd",
+    });
+    expect(card.text).not.toContain("<script>");
+    expect(card.text).toContain("&lt;script&gt;");
+  });
+
+  it("HTML-escapes the agent-supplied summary", () => {
+    const preview = buildDiffPreview(
+      baseInput({ agentSummary: "Hi <b>bold</b> & <i>tags</i>" }),
+    );
+    const card = buildDiffPreviewCard({
+      preview,
+      suggestRequestId: "aabbccdd",
+    });
+    expect(card.text).not.toMatch(/💬.*<b>/);
+    expect(card.text).toContain("&lt;b&gt;");
+  });
+});
+
+describe("buildDiffPreviewCard — audit fidelity", () => {
+  it("preview audit row matches what the user sees on the card", () => {
+    const input = baseInput({ agentSummary: "Added the Hiring section" });
+    const preview = buildDiffPreview(input);
+    const card = buildDiffPreviewCard({
+      preview,
+      suggestRequestId: "aabbccdd",
+      writeRequestId: "11223344",
+    });
+    // The audit row captures both wrapper truth + agent framing,
+    // exactly as surfaced on the card.
+    expect(preview.audit.wrapperAttested.anchorDisplayName).toBe(
+      "after heading 'Goals' (level 2)",
+    );
+    expect(preview.audit.wrapperAttested.linesAdded).toBe(47);
+    expect(preview.audit.agentSupplied.summary).toBe("Added the Hiring section");
+    // Card body contains both.
+    expect(card.text).toContain("after heading 'Goals' (level 2)");
+    expect(card.text).toContain("Added the Hiring section");
+  });
+});