@cortexkit/opencode-antigravity-auth 1.1.0 → 2.0.1

package/src/sidebar-state.ts

@@ -0,0 +1,991 @@
+/**
+ * Sidebar state contract for the OpenTUI sidebar.
+ *
+ * This module is the read-only seam between the long-running plugin and the
+ * Solid/OpenTUI sidebar tree. It deliberately does NOT import account storage,
+ * the account manager, OAuth code, or any other privileged host-side module:
+ * the TUI is rendered inside the host's terminal and a single stray import
+ * could leak credentials or pull a heavy manager into the render path.
+ *
+ * The plugin writes a redacted snapshot to the file resolved by
+ * `getSidebarStateFile()` and the TUI polls it. The contract version is `1`:
+ * any future field that the TUI cannot understand must be ignored, and any
+ * broken/missing file must collapse to `DEFAULT_SIDEBAR_STATE`.
+ *
+ * ## Writer surface
+ *
+ * The plugin-side writers live here too so the read and write halves of the
+ * contract evolve together. They are imported by the plugin (auth-loader,
+ * quota, fetch-interceptor, event-handler, commands) but never invoked from
+ * the TUI's compiled tree — that tree only calls the readers, so the
+ * heavyweight core imports below never run inside the host's render path.
+ *
+ * Every disk mutation follows the same recipe:
+ *
+ *   1. Serialize through `sidebarWriteChain` so concurrent in-process calls
+ *      never interleave merges against the same file.
+ *   2. Acquire Task 7's `acquireFencedFileLock` with bounded retry+jitter
+ *      (≤2s). A live cross-process holder that does not release in time
+ *      surfaces as `SidebarStateLockContentionError`.
+ *   3. Re-read and normalize the on-disk state while holding the lock.
+ *   4. Merge the new machine or routing payload against the re-read state.
+ *   5. `assertOwned()` + `writeJsonAtomic` with mode 0o600, then release.
+ *
+ * The merge step is deterministic: machine fields adopt only when the new
+ * `checkedAt` is ≥ the on-disk one, `routingAuthoritative` is sticky-true,
+ * and `activeRouting` is merged independently and pruned to the freshest
+ * 100 entries within 24h.
+ */
+
+import { mkdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+// Subpath imports (not the barrel): this file ships into the TUI's
+// compiled tree, and the barrel re-exports account/OAuth/quota modules
+// that must never execute inside the host's render path.
+import { writeJsonAtomic } from '@cortexkit/antigravity-auth-core/atomic-write'
+import {
+  acquireFencedFileLock,
+  type FencedFileLock,
+} from '@cortexkit/antigravity-auth-core/file-lock'
+import { xdgState } from 'xdg-basedir'
+
+export const SIDEBAR_STATE_VERSION = 1 as const
+
+export type SidebarQuotaKey = 'gemini' | 'non-gemini'
+
+export interface SidebarQuotaWindowEntry {
+  window: 'weekly' | '5h'
+  remainingPercent: number
+  resetAt?: number
+}
+
+export interface SidebarQuotaEntry {
+  /** Most-constrained window's remaining % (derived, for back-compat). */
+  remainingPercent: number
+  resetAt?: number
+  /** Per-window breakdown. Omitted in pre-windows snapshots. */
+  windows?: SidebarQuotaWindowEntry[]
+}
+
+export interface SidebarAccountState {
+  id: string
+  label: string
+  enabled: boolean
+  health: number
+  current: boolean
+  cooldownUntil?: number
+  quota: Partial<Record<SidebarQuotaKey, SidebarQuotaEntry>>
+  /**
+   * Captured plan tier. Absent when unknown — do NOT default to `free-tier`.
+   * `id` is the raw upstream string (e.g. `"free-tier"`); never normalised.
+   */
+  tier?: { id: string; paidId?: string; capturedAt: number }
+}
+
+export interface SidebarRoutingEntry {
+  accountId: string
+  modelFamily: 'claude' | 'gemini'
+  headerStyle: 'antigravity' | 'gemini-cli'
+  strategy?: 'sticky' | 'round-robin' | 'hybrid'
+  updatedAt: number
+}
+
+export interface SidebarStateV1 {
+  version: typeof SIDEBAR_STATE_VERSION
+  checkedAt: number
+  accounts: SidebarAccountState[]
+  activeRouting: Record<string, SidebarRoutingEntry>
+  routingAuthoritative: boolean
+  quotaBackoffUntil?: number
+  lastError?: string
+}
+
+/**
+ * The subset of `SidebarStateV1` that a non-routing writer may set. The
+ * fetch interceptor writes `activeRouting` directly via its own entry point
+ * because routing is session-scoped, not machine-scoped.
+ */
+export interface SidebarMachineState {
+  checkedAt: number
+  accounts: SidebarAccountState[]
+  quotaBackoffUntil?: number
+  lastError?: string
+  /**
+   * Optional: opt in to mark the snapshot as authoritative. When `true`,
+   * the merge keeps the existing `routingAuthoritative: true` even if a
+   * later non-authoritative machine write lands. Sticky-true semantics.
+   */
+  routingAuthoritative?: boolean
+}
+
+export const DEFAULT_SIDEBAR_STATE: SidebarStateV1 = {
+  version: SIDEBAR_STATE_VERSION,
+  checkedAt: 0,
+  accounts: [],
+  activeRouting: {},
+  routingAuthoritative: false,
+}
+
+export const SIDEBAR_STATE_ENV = 'ANTIGRAVITY_AUTH_SIDEBAR_STATE_FILE'
+
+const SIDEBAR_STATE_DIR = 'cortexkit/antigravity-auth'
+const SIDEBAR_STATE_FILENAME = 'sidebar-state.json'
+
+/** Active routing entries older than this are dropped on every merge. */
+const ACTIVE_ROUTING_MAX_AGE_MS = 24 * 60 * 60 * 1000
+/** Active routing map is capped at this many newest entries. */
+const ACTIVE_ROUTING_MAX_ENTRIES = 100
+
+const SIDEBAR_LOCK_NAME = 'sidebar'
+const SIDEBAR_LOCK_TTL_MS = 10_000
+const SIDEBAR_LOCK_TIMEOUT_MS = 2_000
+const SIDEBAR_LOCK_RETRY_BASE_MS = 25
+const SIDEBAR_LOCK_RETRY_CAP_MS = 75
+const SIDEBAR_LOCK_JITTER_MS = 25
+const SIDEBAR_STATE_DIR_MODE = 0o700
+const SIDEBAR_STATE_FILE_MODE = 0o600
+
+/**
+ * Thrown by every writer when the cross-process lock cannot be acquired
+ * within `SIDEBAR_LOCK_TIMEOUT_MS`. The caller decides whether to surface
+ * a toast, drop the write, or retry the next tick.
+ */
+export class SidebarStateLockContentionError extends Error {
+  readonly details: { stateFile: string; timeoutMs: number }
+
+  constructor(stateFile: string, timeoutMs: number) {
+    super(
+      `Could not acquire sidebar-state lock at ${stateFile} within ${timeoutMs}ms`,
+    )
+    this.name = 'SidebarStateLockContentionError'
+    this.details = { stateFile, timeoutMs }
+  }
+}
+
+/**
+ * Steps exposed to the merge hooks. Race tests pause writers here; production
+ * callers leave the hooks unset (a no-op fast path).
+ *
+ * - `await-lock` — before invoking `acquireFencedFileLock`.
+ * - `acquired-lock` — after the lock is granted and before the read.
+ * - `read-state` — after the on-disk state is normalized.
+ * - `merged-state` — after the merge but before `writeJsonAtomic`.
+ * - `wrote-state` — after the rename but before `lock.release()`.
+ */
+export type SidebarMergeStep =
+  | 'await-lock'
+  | 'acquired-lock'
+  | 'read-state'
+  | 'merged-state'
+  | 'wrote-state'
+
+export interface SidebarMergeHooks {
+  onStep?: (step: SidebarMergeStep) => Promise<void> | void
+}
+
+let sidebarMergeHooks: SidebarMergeHooks | null = null
+
+/**
+ * Install (or clear with `null`) the deterministic race hooks. Tests use
+ * these to inject interleavings; production callers leave them unset. The
+ * module-level state means a test must reset hooks in its own `afterEach`
+ * to avoid bleeding into the next test.
+ */
+export function setSidebarMergeHooks(hooks: SidebarMergeHooks | null): void {
+  sidebarMergeHooks = hooks
+}
+
+async function emitMergeStep(step: SidebarMergeStep): Promise<void> {
+  await sidebarMergeHooks?.onStep?.(step)
+}
+
+/**
+ * Resolve the on-disk path the plugin writes to and the TUI reads from.
+ *
+ * - `ANTIGRAVITY_AUTH_SIDEBAR_STATE_FILE` wins when set (tests, packaged
+ *   installers, and any user override).
+ * - Otherwise fall back to the XDG state directory, mirroring the path
+ *   conventions used elsewhere in the project.
+ */
+export function getSidebarStateFile(): string {
+  const override = process.env[SIDEBAR_STATE_ENV]
+  if (override && override.trim().length > 0) return override
+  const base = xdgState ?? join(homedir(), '.local', 'state')
+  return join(base, SIDEBAR_STATE_DIR, SIDEBAR_STATE_FILENAME)
+}
+
+/**
+ * Read and normalize the sidebar state file. Returns the default state when
+ * the file is missing, unreadable, malformed, or schema-incompatible — the TUI
+ * must never throw out of `readSidebarState()`, the panel just shows
+ * "Awaiting Antigravity state" and the next poll retries.
+ *
+ * The read is sync on purpose: the TUI polls on a 2-second timer and the file
+ * is tiny (a handful of accounts); an async read here would just add race
+ * surface area against Solid's reactive render cycle.
+ */
+export function readSidebarState(
+  path: string = getSidebarStateFile(),
+): SidebarStateV1 {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf-8')
+  } catch {
+    return { ...DEFAULT_SIDEBAR_STATE }
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return { ...DEFAULT_SIDEBAR_STATE, lastError: 'malformed-json' }
+  }
+  return normalizeSidebarState(parsed)
+}
+
+function normalizeSidebarState(input: unknown): SidebarStateV1 {
+  if (!isObject(input)) {
+    return { ...DEFAULT_SIDEBAR_STATE, lastError: 'shape' }
+  }
+  const record = input as Record<string, unknown>
+  const version = record.version
+  if (version !== SIDEBAR_STATE_VERSION) {
+    return {
+      ...DEFAULT_SIDEBAR_STATE,
+      lastError: `unsupported-version:${stringifySafe(version)}`,
+    }
+  }
+
+  const accountsRaw = record.accounts
+  const accounts = Array.isArray(accountsRaw)
+    ? accountsRaw
+        .map((entry) => normalizeAccount(entry))
+        .filter((entry): entry is SidebarAccountState => entry !== null)
+    : []
+
+  const routingRaw = record.activeRouting
+  const activeRouting: Record<string, SidebarRoutingEntry> = {}
+  if (isObject(routingRaw)) {
+    for (const [sessionId, entry] of Object.entries(
+      routingRaw as Record<string, unknown>,
+    )) {
+      const normalized = normalizeRouting(entry)
+      if (normalized) activeRouting[sessionId] = normalized
+    }
+  }
+
+  const checkedAt = toFiniteNumber(record.checkedAt)
+  const routingAuthoritative = record.routingAuthoritative === true
+  const quotaBackoffUntil = toFiniteNumber(record.quotaBackoffUntil)
+  const lastError =
+    typeof record.lastError === 'string' ? record.lastError : undefined
+
+  return {
+    version: SIDEBAR_STATE_VERSION,
+    checkedAt: checkedAt ?? 0,
+    accounts,
+    activeRouting,
+    routingAuthoritative,
+    quotaBackoffUntil: quotaBackoffUntil ?? undefined,
+    lastError,
+  }
+}
+
+function normalizeAccount(input: unknown): SidebarAccountState | null {
+  if (!isObject(input)) return null
+  const record = input as Record<string, unknown>
+  const id = typeof record.id === 'string' ? record.id : null
+  const label = typeof record.label === 'string' ? record.label : null
+  if (!id || !label) return null
+  const enabled = record.enabled !== false
+  const health = clampNumber(toFiniteNumber(record.health), 0, 100)
+  const current = record.current === true
+  const cooldownUntil = toFiniteNumber(record.cooldownUntil) ?? undefined
+  const quotaRaw = record.quota
+  const quota: SidebarAccountState['quota'] = {}
+  if (isObject(quotaRaw)) {
+    for (const key of ['gemini', 'non-gemini'] as const) {
+      const entry = (quotaRaw as Record<string, unknown>)[key]
+      const normalized = normalizeQuota(entry)
+      if (normalized) quota[key] = normalized
+    }
+  }
+  const tier = normalizeTier(record.tier)
+  return {
+    id,
+    label,
+    enabled,
+    health,
+    current,
+    cooldownUntil,
+    quota,
+    ...(tier !== undefined ? { tier } : {}),
+  }
+}
+
+function normalizeTier(
+  input: unknown,
+): { id: string; paidId?: string; capturedAt: number } | undefined {
+  if (!isObject(input)) return undefined
+  const record = input as Record<string, unknown>
+  const id =
+    typeof record.id === 'string' && record.id.length > 0 ? record.id : null
+  const capturedAt = toFiniteNumber(record.capturedAt)
+  if (!id || capturedAt === null) return undefined
+  const paidId =
+    typeof record.paidId === 'string' && record.paidId.length > 0
+      ? record.paidId
+      : undefined
+  return { id, ...(paidId ? { paidId } : {}), capturedAt }
+}
+
+function normalizeQuota(input: unknown): SidebarQuotaEntry | null {
+  if (!isObject(input)) return null
+  const record = input as Record<string, unknown>
+  const remaining = toFiniteNumber(record.remainingPercent)
+  if (remaining === null) return null
+  const resetAt = toFiniteNumber(record.resetAt) ?? undefined
+
+  // Tolerant: deserialize windows array if present; drop malformed entries.
+  const windowsRaw = record.windows
+  let windows: SidebarQuotaEntry['windows']
+  if (Array.isArray(windowsRaw)) {
+    const parsed = windowsRaw
+      .filter(isObject)
+      .map((w) => {
+        const win = (w as Record<string, unknown>).window
+        const rp = toFiniteNumber(
+          (w as Record<string, unknown>).remainingPercent,
+        )
+        const ra = toFiniteNumber((w as Record<string, unknown>).resetAt)
+        if ((win !== 'weekly' && win !== '5h') || rp === null) return null
+        return {
+          window: win as 'weekly' | '5h',
+          remainingPercent: clampNumber(rp, 0, 100),
+          resetAt: ra ?? undefined,
+        }
+      })
+      .filter((v): v is NonNullable<typeof v> => v !== null)
+    if (parsed.length > 0) windows = parsed
+  }
+
+  return {
+    remainingPercent: clampNumber(remaining, 0, 100),
+    resetAt,
+    windows,
+  }
+}
+
+function normalizeRouting(input: unknown): SidebarRoutingEntry | null {
+  if (!isObject(input)) return null
+  const record = input as Record<string, unknown>
+  const accountId =
+    typeof record.accountId === 'string' ? record.accountId : null
+  const modelFamily = record.modelFamily
+  const headerStyle = record.headerStyle
+  const strategy = record.strategy
+  const updatedAt = toFiniteNumber(record.updatedAt) ?? 0
+  if (
+    !accountId ||
+    (modelFamily !== 'claude' && modelFamily !== 'gemini') ||
+    (headerStyle !== 'antigravity' && headerStyle !== 'gemini-cli')
+  ) {
+    return null
+  }
+  return {
+    accountId,
+    modelFamily,
+    headerStyle,
+    strategy:
+      strategy === 'sticky' ||
+      strategy === 'round-robin' ||
+      strategy === 'hybrid'
+        ? strategy
+        : undefined,
+    updatedAt,
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function toFiniteNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return null
+}
+
+function clampNumber(value: number | null, min: number, max: number): number {
+  if (value === null) return min
+  if (value < min) return min
+  if (value > max) return max
+  return value
+}
+
+function stringifySafe(value: unknown): string {
+  if (typeof value === 'string') return value
+  try {
+    return JSON.stringify(value) ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+/**
+ * Ensure the parent directory for the sidebar state file exists. Convenience
+ * helper used by writers (tests, plugins) — the TUI itself does not write.
+ */
+export function ensureSidebarStateDir(
+  path: string = getSidebarStateFile(),
+): void {
+  mkdirSync(dirname(path), { recursive: true, mode: SIDEBAR_STATE_DIR_MODE })
+}
+
+/**
+ * Drop active-routing entries older than 24h and cap the map at the freshest
+ * 100. Pure helper exposed for unit testing; the writers call it on every
+ * merge so the on-disk map never grows without bound.
+ */
+export function pruneActiveRouting(
+  map: Record<string, SidebarRoutingEntry>,
+  now: number,
+): Record<string, SidebarRoutingEntry> {
+  const cutoff = now - ACTIVE_ROUTING_MAX_AGE_MS
+  const filtered: Array<[string, SidebarRoutingEntry]> = []
+  for (const [sessionId, entry] of Object.entries(map)) {
+    if (entry.updatedAt >= cutoff) {
+      filtered.push([sessionId, entry])
+    }
+  }
+  filtered.sort((a, b) => b[1].updatedAt - a[1].updatedAt)
+  if (filtered.length <= ACTIVE_ROUTING_MAX_ENTRIES) {
+    return Object.fromEntries(filtered)
+  }
+  return Object.fromEntries(filtered.slice(0, ACTIVE_ROUTING_MAX_ENTRIES))
+}
+
+/**
+ * Structural input for `redactAccountForSidebar`. Decoupled from the core
+ * `ManagedAccount` type so this module never forces a type-level import
+ * shape on callers (and so the TUI's compiled tree does not see the core
+ * ManagedAccount shape beyond what's actually used).
+ *
+ * Deliberately excludes `email`: the sidebar/redaction boundary is a PII
+ * firewall. Adding `email` here would re-introduce the leak this boundary
+ * exists to prevent. Legacy profile labels are accepted but never serialized.
+ */
+export interface SidebarAccountRedactionInput {
+  /** Position in the harness-visible account array. */
+  index: number
+  /** Legacy profile label; deliberately ignored by the redactor. */
+  label?: string
+  enabled?: boolean
+  current?: boolean
+  coolingDownUntil?: number
+  /** Health score in `[0, 100]`. Defaults to 100 when missing. */
+  healthScore?: number
+  cachedQuota?: {
+    gemini?: {
+      remainingFraction?: number
+      resetTime?: string
+      windows?: Array<{
+        window: 'weekly' | '5h'
+        remainingFraction: number
+        resetTime: string
+      }>
+    }
+    'non-gemini'?: {
+      remainingFraction?: number
+      resetTime?: string
+      windows?: Array<{
+        window: 'weekly' | '5h'
+        remainingFraction: number
+        resetTime: string
+      }>
+    }
+    // Legacy per-pool keys written by older versions of the plugin.
+    // Accepted here so the normalizer can map them to the current pool
+    // keys at read time without requiring a disk migration.
+    [legacyKey: string]:
+      | {
+          remainingFraction?: number
+          resetTime?: string
+          modelCount?: number
+          windows?: Array<{
+            window: 'weekly' | '5h'
+            remainingFraction: number
+            resetTime: string
+          }>
+        }
+      | undefined
+  }
+  /**
+   * Opaque identity stamp that was attached to the persisted quota snapshot.
+   * Used together with `currentQuotaAccountId` to detect a stale cache that
+   * landed on the wrong account after an index shift or token replacement.
+   * PII-safe — it is a 16-char hash, not the refresh token itself.
+   */
+  cachedQuotaAccountId?: string
+  /**
+   * Opaque identity stamp for the account that is currently at this index.
+   * The redactor drops `cachedQuota` when `cachedQuotaAccountId` is set
+   * AND does not match this value, mirroring `toCommandAccountRow` in the
+   * command-data service. Omitted in the persisted sidebar state.
+   */
+  currentQuotaAccountId?: string
+  /**
+   * Captured plan tier from `loadCodeAssist`. Absent when unknown. The `id`
+   * is the raw upstream string; `capturedAt` is epoch ms. Not PII — tier
+   * metadata survives the redaction boundary unchanged.
+   */
+  tier?: { id: string; paidId?: string; capturedAt: number }
+}
+
+/**
+ * Build a `{ id, capturedAt }` tier object from account fields, or `undefined`
+ * when either field is absent. Centralised so every producer (index.ts,
+ * background-quota-refresh.ts, command-data.ts) uses the same guard and the
+ * same shape -- the same pattern shipped as inline literals across three files
+ * and produced six missed-field bugs; one helper ends that.
+ */
+export function toCapturedTier(account: {
+  capturedTierId?: string
+  capturedPaidTierId?: string
+  capturedTierAt?: number
+}): { id: string; paidId?: string; capturedAt: number } | undefined {
+  return account.capturedTierId !== undefined &&
+    account.capturedTierAt !== undefined
+    ? {
+        id: account.capturedTierId,
+        ...(account.capturedPaidTierId !== undefined
+          ? { paidId: account.capturedPaidTierId }
+          : {}),
+        capturedAt: account.capturedTierAt,
+      }
+    : undefined
+}
+
+/**
+ * Map pre-pool legacy quota keys to the current two-pool schema at read time.
+ *
+ * Legacy mappings (empirically settled from burn tests):
+ *   `gemini-pro` + `gemini-flash`  →  `gemini`
+ *   `claude`      + `gpt-oss`       →  `non-gemini`
+ *
+ * Where multiple legacy keys collapse into one pool the MIN remainingFraction
+ * and earliest resetTime are used (most-constrained-first, matching the
+ * window-level rule). No `windows` arrays are invented for migrated entries;
+ * the single aggregate bar is the correct render for pre-window snapshots.
+ *
+ * Non-legacy keys that are already canonical (`gemini`, `non-gemini`) are
+ * carried through unchanged. The next real quota refresh overwrites any
+ * migrated snapshot with authoritative data.
+ */
+export function normalizeLegacyCachedQuota(
+  raw: SidebarAccountRedactionInput['cachedQuota'],
+): SidebarAccountRedactionInput['cachedQuota'] {
+  if (!raw) return raw
+
+  // Pool already carries current keys — fast path when no legacy keys present.
+  const hasLegacy =
+    'gemini-pro' in raw ||
+    'gemini-flash' in raw ||
+    'claude' in raw ||
+    'gpt-oss' in raw
+  if (!hasLegacy) return raw
+
+  type PoolEntry = NonNullable<
+    SidebarAccountRedactionInput['cachedQuota']
+  >['gemini']
+
+  // Pick the earlier of two ISO reset timestamps, preferring a defined
+  // value over undefined. Extracted so both branches of minFraction use
+  // the same merge rather than the previous asymmetry where the a-wins
+  // branch dropped b's possibly-earlier resetTime.
+  const earlierResetTime = (
+    a: string | undefined,
+    b: string | undefined,
+  ): string | undefined => {
+    if (!a) return b
+    if (!b) return a
+    return a < b ? a : b
+  }
+
+  const minFraction = (a: PoolEntry, b: PoolEntry): PoolEntry => {
+    if (!a) return b
+    if (!b) return a
+    const fa = a.remainingFraction ?? 1
+    const fb = b.remainingFraction ?? 1
+    const winner = fa <= fb ? a : b
+    const loser = fa <= fb ? b : a
+    // Always merge to the earliest resetTime regardless of which pool wins
+    // the fraction comparison — an earlier window expiry from the loser
+    // pool must not be silently dropped.
+    return {
+      ...winner,
+      resetTime: earlierResetTime(winner.resetTime, loser.resetTime),
+    }
+  }
+
+  const gemini: PoolEntry =
+    minFraction(
+      raw.gemini,
+      minFraction(
+        raw['gemini-pro'] as PoolEntry,
+        raw['gemini-flash'] as PoolEntry,
+      ),
+    ) ?? raw.gemini
+
+  const nonGemini: PoolEntry =
+    minFraction(
+      raw['non-gemini'],
+      minFraction(raw.claude as PoolEntry, raw['gpt-oss'] as PoolEntry),
+    ) ?? raw['non-gemini']
+
+  return {
+    ...(gemini !== undefined ? { gemini } : {}),
+    ...(nonGemini !== undefined ? { 'non-gemini': nonGemini } : {}),
+  }
+}
+
+/**
+ * Project a raw cachedQuota pool entry into the sidebar-safe shape.
+ *
+ * Centralized seam — every producer (quota.ts pushSidebarQuotaSnapshot,
+ * auth-loader.ts materializer, command-data.ts writeSidebar) routes
+ * through here so the `windows` array is never dropped by an inline
+ * `{ remainingFraction, resetTime }` literal.
+ *
+ * Tolerant: returns `undefined` when the source is missing or the
+ * `remainingFraction` is not a finite number. Legacy entries without
+ * `windows` produce `{ remainingPercent, resetAt }` only — the TUI's
+ * legacy path then renders a single bar.
+ */
+export function projectQuotaPoolForSidebar(source: {
+  remainingFraction?: number
+  resetTime?: string
+  windows?: ReadonlyArray<{
+    window: 'weekly' | '5h'
+    remainingFraction: number
+    resetTime: string
+  }>
+}): SidebarQuotaEntry | undefined {
+  const fraction = source.remainingFraction
+  if (typeof fraction !== 'number' || !Number.isFinite(fraction))
+    return undefined
+  const remainingPercent = clampNumber(Math.round(fraction * 100), 0, 100)
+  let resetAt: number | undefined
+  if (typeof source.resetTime === 'string' && source.resetTime.length > 0) {
+    const parsed = Date.parse(source.resetTime)
+    if (Number.isFinite(parsed)) resetAt = parsed
+  }
+
+  const windows: SidebarQuotaEntry['windows'] = source.windows?.length
+    ? source.windows.map((w) => ({
+        window: w.window,
+        remainingPercent: clampNumber(
+          Math.round(w.remainingFraction * 100),
+          0,
+          100,
+        ),
+        resetAt:
+          typeof w.resetTime === 'string' && w.resetTime.length > 0
+            ? (() => {
+                const parsed = Date.parse(w.resetTime)
+                return Number.isFinite(parsed) ? parsed : undefined
+              })()
+            : undefined,
+      }))
+    : undefined
+
+  return { remainingPercent, resetAt, windows }
+}
+
+/**
+ * Returns `true` when an account at `index` is the active account for
+ * at least one model family. Two accounts CAN both be current — one
+ * serving claude, one serving gemini — so this must not collapse to one.
+ */
+export function isAccountCurrent(
+  index: number,
+  activeIndexByFamily: { claude: number; gemini: number },
+): boolean {
+  return (
+    index === activeIndexByFamily.claude || index === activeIndexByFamily.gemini
+  )
+}
+
+/**
+ * Convert a live account snapshot into the redacted shape the TUI renders.
+ * The redacted `SidebarAccountState` carries no email, refresh token, access
+ * token, project ID, fingerprint, OAuth profile name, or other personal or
+ * credential-shaped fields. Display labels are generated ordinal account names.
+ */
+export function redactAccountForSidebar(
+  source: SidebarAccountRedactionInput,
+): SidebarAccountState {
+  const id = `acct-${source.index}`
+  const label = `Account ${source.index + 1}`
+  const enabled = source.enabled !== false
+  const current = source.current === true
+  const cooldownUntil =
+    typeof source.coolingDownUntil === 'number' &&
+    Number.isFinite(source.coolingDownUntil)
+      ? source.coolingDownUntil
+      : undefined
+  const health = clampNumber(
+    typeof source.healthScore === 'number' ? source.healthScore : 100,
+    0,
+    100,
+  )
+
+  const quota: SidebarAccountState['quota'] = {}
+  // Stamp mismatch: the persisted quota snapshot was captured for a
+  // different account than the one currently at this index. Drop the
+  // stale cache rather than rendering the wrong account's quota
+  // percentages. Mirrors `toCommandAccountRow` in command-data.
+  const staleCachedQuota =
+    typeof source.cachedQuotaAccountId === 'string' &&
+    typeof source.currentQuotaAccountId === 'string' &&
+    source.cachedQuotaAccountId !== source.currentQuotaAccountId
+  // Normalize legacy per-pool keys to the current two-pool schema before
+  // reading. This is non-destructive: the next real quota refresh will
+  // overwrite the migrated snapshot with authoritative data.
+  const cached = staleCachedQuota
+    ? undefined
+    : normalizeLegacyCachedQuota(source.cachedQuota)
+  if (cached) {
+    for (const key of ['gemini', 'non-gemini'] as const) {
+      const entry = cached[key]
+      if (!entry) continue
+      const projected = projectQuotaPoolForSidebar(entry)
+      if (projected) quota[key] = projected
+    }
+  }
+
+  return {
+    id,
+    label,
+    enabled,
+    health,
+    current,
+    cooldownUntil,
+    quota,
+    // Tier is plan metadata, not PII — it passes the redaction boundary.
+    ...(source.tier !== undefined ? { tier: source.tier } : {}),
+  }
+}
+
+/**
+ * Build a `SidebarMachineState` from a list of live account snapshots.
+ * Convenience for the auth-loader / quota writer call sites that already
+ * hold an array of accounts and want to push a single snapshot.
+ */
+export function buildSidebarMachineStateFromAccounts(
+  accounts: SidebarAccountRedactionInput[],
+  options: {
+    checkedAt?: number
+    quotaBackoffUntil?: number
+    lastError?: string
+    routingAuthoritative?: boolean
+  } = {},
+): SidebarMachineState {
+  return {
+    checkedAt: options.checkedAt ?? Date.now(),
+    accounts: accounts.map((entry) => redactAccountForSidebar(entry)),
+    quotaBackoffUntil: options.quotaBackoffUntil,
+    lastError: options.lastError,
+    routingAuthoritative: options.routingAuthoritative,
+  }
+}
+
+interface SidebarStateWriteOptions {
+  stateFile?: string
+}
+
+let sidebarWriteChain: Promise<void> = Promise.resolve()
+
+function enqueueSidebarWrite<T>(work: () => Promise<T>): Promise<T> {
+  // Always run `work` regardless of whether the prior link resolved or
+  // rejected — a failed write must not poison the chain for the next caller.
+  const next = sidebarWriteChain.then(work, work)
+  sidebarWriteChain = next.then(
+    () => undefined,
+    () => undefined,
+  )
+  return next
+}
+
+/**
+ * Wait for any in-flight sidebar state write to drain. The plugin lifecycle
+ * calls this during `dispose()` so the file logger and RPC server are torn
+ * down only after every queued write has either landed or thrown.
+ */
+export function drainSidebarWrites(): Promise<void> {
+  return sidebarWriteChain
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function acquireSidebarLockWithRetry(
+  stateFile: string,
+): Promise<FencedFileLock> {
+  const start = Date.now()
+  let attempt = 0
+  while (true) {
+    await emitMergeStep('await-lock')
+    const lock = await acquireFencedFileLock({
+      path: stateFile,
+      name: SIDEBAR_LOCK_NAME,
+      ttlMs: SIDEBAR_LOCK_TTL_MS,
+      renew: true,
+    })
+    if (lock) {
+      await emitMergeStep('acquired-lock')
+      return lock
+    }
+    const elapsed = Date.now() - start
+    if (elapsed >= SIDEBAR_LOCK_TIMEOUT_MS) {
+      throw new SidebarStateLockContentionError(
+        stateFile,
+        SIDEBAR_LOCK_TIMEOUT_MS,
+      )
+    }
+    const backoff = Math.min(
+      SIDEBAR_LOCK_RETRY_CAP_MS,
+      SIDEBAR_LOCK_RETRY_BASE_MS + attempt * 10,
+    )
+    const jitter = Math.floor(Math.random() * SIDEBAR_LOCK_JITTER_MS)
+    await sleep(backoff + jitter)
+    attempt++
+  }
+}
+
+async function performSidebarWrite(
+  stateFile: string,
+  merge: (existing: SidebarStateV1) => SidebarStateV1,
+): Promise<void> {
+  await enqueueSidebarWrite(async () => {
+    ensureSidebarStateDir(stateFile)
+    const lock = await acquireSidebarLockWithRetry(stateFile)
+    try {
+      await lock.assertOwned()
+      const existing = readSidebarState(stateFile)
+      await emitMergeStep('read-state')
+      const merged = merge(existing)
+      await emitMergeStep('merged-state')
+      await writeJsonAtomic(stateFile, merged)
+      // `writeJsonAtomic` stages a tmp file with mode 0o600 and renames onto
+      // the target; POSIX rename replaces the inode so the new file inherits
+      // the staged mode bits. Windows ignores POSIX modes so the assertion
+      // in tests is best-effort there.
+      await emitMergeStep('wrote-state')
+    } finally {
+      await lock.release().catch(() => {})
+    }
+  })
+}
+
+/**
+ * Merge a new machine-state payload against the on-disk state.
+ *
+ * Stale writes (new `checkedAt` < existing) are dropped — only newer/equal
+ * `checkedAt` may replace machine fields. The merge preserves
+ * `routingAuthoritative: true` once it is true (sticky-true), keeps the
+ * existing `activeRouting` intact (routing is merged via its own writer),
+ * and prunes any expired routing entries as a side effect.
+ */
+function mergeMachineState(
+  existing: SidebarStateV1,
+  next: SidebarMachineState,
+): SidebarStateV1 {
+  if (next.checkedAt < existing.checkedAt) {
+    return {
+      ...existing,
+      activeRouting: pruneActiveRouting(existing.activeRouting, Date.now()),
+    }
+  }
+  return {
+    version: SIDEBAR_STATE_VERSION,
+    checkedAt: next.checkedAt,
+    accounts: next.accounts,
+    quotaBackoffUntil: next.quotaBackoffUntil,
+    lastError: next.lastError,
+    routingAuthoritative:
+      existing.routingAuthoritative === true ||
+      next.routingAuthoritative === true,
+    // Symmetric with the stale-write branch: every machine-write merge
+    // re-prunes activeRouting so a long-running TUI session eventually
+    // drops dead routes even when no fresh routing upsert lands. Cheap
+    // (a single Object.entries + sort over ≤100 entries) and bounded.
+    activeRouting: pruneActiveRouting(existing.activeRouting, Date.now()),
+  }
+}
+
+/**
+ * Upsert a single session's active routing entry. The fetch interceptor calls
+ * this with `authoritative: true` after every final route selection; the
+ * `accountId`/`modelFamily`/`headerStyle` fields are already redacted by the
+ * caller (the writer never sees token or project fields).
+ */
+export async function upsertSidebarActiveRouting(
+  sessionId: string,
+  entry: SidebarRoutingEntry,
+  options: SidebarStateWriteOptions & { authoritative?: boolean } = {},
+): Promise<void> {
+  const stateFile = options.stateFile ?? getSidebarStateFile()
+  await performSidebarWrite(stateFile, (existing) => {
+    const activeRouting = { ...existing.activeRouting, [sessionId]: entry }
+    return {
+      ...existing,
+      routingAuthoritative:
+        options.authoritative === true ? true : existing.routingAuthoritative,
+      activeRouting: pruneActiveRouting(activeRouting, Date.now()),
+    }
+  })
+}
+
+/**
+ * Remove one session's active routing entry. The event handler calls this
+ * when a session is deleted so the sidebar does not retain dead routes.
+ */
+export async function removeSidebarActiveRouting(
+  sessionId: string,
+  options: SidebarStateWriteOptions = {},
+): Promise<void> {
+  const stateFile = options.stateFile ?? getSidebarStateFile()
+  await performSidebarWrite(stateFile, (existing) => {
+    if (!(sessionId in existing.activeRouting)) {
+      return existing
+    }
+    const activeRouting = { ...existing.activeRouting }
+    delete activeRouting[sessionId]
+    return {
+      ...existing,
+      activeRouting,
+    }
+  })
+}
+
+/**
+ * Write a new machine-state snapshot. The fetch interceptor and quota
+ * manager call this after each refresh; auth-loader calls it after the
+ * account pool is materialized.
+ */
+export async function setSidebarMachineState(
+  next: SidebarMachineState,
+  options: SidebarStateWriteOptions = {},
+): Promise<void> {
+  const stateFile = options.stateFile ?? getSidebarStateFile()
+  await performSidebarWrite(stateFile, (existing) =>
+    mergeMachineState(existing, next),
+  )
+}
+
+void SIDEBAR_STATE_FILE_MODE