@cortexkit/opencode-openai-auth 0.4.2 → 0.5.0

package/src/sidebar-state.ts

@@ -1,11 +1,13 @@
 export interface QuotaWindow {
   usedPercent: number
   remainingPercent: number
+  checkedAt?: number
   resetsAt?: string
   windowMinutes?: number
 }
 
 export interface AccountQuota {
+  checkedAt?: number
   primary?: QuotaWindow
   secondary?: QuotaWindow
   resetCreditsAvailable?: number
@@ -80,6 +82,8 @@ export function getPresentQuotaWindows(
 export interface SidebarAccountState {
   id: string
   label: string | undefined
+  /** ChatGPT identity of the account this quota belongs to. */
+  accountId?: string
   quota: AccountQuota | null
   killed: boolean
   enabled: boolean
@@ -94,9 +98,38 @@ export interface ActiveRoutingEntry {
 
 export type ActiveRoutingMap = Record<string, ActiveRoutingEntry>
 
+export interface StickyAssignment {
+  accountId: string
+  assignedAt: number
+  lastSeenAt: number
+  inputBytes: number
+  quotaCheckedAt?: number
+}
+
+export type StickyAssignmentMap = Record<string, StickyAssignment>
+
+export interface StickyAssignmentChoice {
+  accountId: string
+  quotaCheckedAt?: number
+}
+
+export interface ResolveStickyAssignmentInput {
+  sessionId: string
+  requestBytes: number
+  now: number
+  validPinnedAccountIds: readonly string[]
+  excludeAccountIds?: readonly string[]
+  quotaCheckedAtByAccount: Readonly<Record<string, number | undefined>>
+  choose: (
+    pendingBytes: ReadonlyMap<string, number>,
+  ) => StickyAssignmentChoice | undefined
+}
+
 export interface SidebarState {
   main: {
     quota: AccountQuota | null
+    /** ChatGPT identity of the main account this quota belongs to. */
+    mainAccountId?: string
     killed: boolean
     quotaBackedOff?: boolean
     quotaBackoffUntil?: number
@@ -110,13 +143,14 @@ export interface SidebarState {
   /** Machine-global routing mode and compatibility value for older readers. */
   route: string
   activeRouting?: ActiveRoutingMap
+  stickyAssignments?: StickyAssignmentMap
   planType?: string
   credits?: number
   lastUpdated: number
 }
 
-import { randomUUID } from 'node:crypto'
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { createHash, randomUUID } from 'node:crypto'
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { acquireRefreshFileLock } from './core/refresh-file-lock'
@@ -127,6 +161,14 @@ const logSb = createLogger('sidebar')
 const STATE_FILE_ENV = 'OPENCODE_OPENAI_AUTH_SIDEBAR_STATE_FILE'
 const DEFAULT_STATE_DIR = join(tmpdir(), 'opencode-openai-auth')
 const DEFAULT_STATE_FILE = join(DEFAULT_STATE_DIR, 'sidebar-state.json')
+const SESSION_HASH_PATTERN = /^[a-f0-9]{64}$/
+export const STICKY_ASSIGNMENT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+export const STICKY_ASSIGNMENT_MAX_ENTRIES = 256
+const STICKY_ASSIGNMENT_LAST_SEEN_TOUCH_MS = 60 * 60 * 1000
+
+export function hashSidebarSessionId(sessionId: string): string {
+  return createHash('sha256').update(sessionId).digest('hex')
+}
 
 function normalizeResetCredits(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) && value >= 0
@@ -172,6 +214,60 @@ function normalizeActiveRouting(value: unknown): ActiveRoutingMap | undefined {
   return Object.keys(normalized).length > 0 ? normalized : undefined
 }
 
+function normalizeStickyAssignments(
+  value: unknown,
+): StickyAssignmentMap | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined
+  }
+
+  const normalized: StickyAssignmentMap = {}
+  for (const [sessionHash, rawAssignment] of Object.entries(value)) {
+    if (
+      !SESSION_HASH_PATTERN.test(sessionHash) ||
+      rawAssignment === null ||
+      typeof rawAssignment !== 'object' ||
+      Array.isArray(rawAssignment)
+    ) {
+      continue
+    }
+    const assignment = rawAssignment as Record<string, unknown>
+    if (
+      typeof assignment.accountId !== 'string' ||
+      assignment.accountId.length === 0 ||
+      typeof assignment.assignedAt !== 'number' ||
+      !Number.isFinite(assignment.assignedAt) ||
+      assignment.assignedAt < 0 ||
+      typeof assignment.lastSeenAt !== 'number' ||
+      !Number.isFinite(assignment.lastSeenAt) ||
+      assignment.lastSeenAt < 0 ||
+      typeof assignment.inputBytes !== 'number' ||
+      !Number.isFinite(assignment.inputBytes) ||
+      assignment.inputBytes < 0
+    ) {
+      continue
+    }
+    const quotaCheckedAt = assignment.quotaCheckedAt
+    if (
+      quotaCheckedAt !== undefined &&
+      (typeof quotaCheckedAt !== 'number' ||
+        !Number.isFinite(quotaCheckedAt) ||
+        quotaCheckedAt < 0)
+    ) {
+      continue
+    }
+    normalized[sessionHash] = {
+      accountId: assignment.accountId,
+      assignedAt: assignment.assignedAt,
+      lastSeenAt: assignment.lastSeenAt,
+      inputBytes: assignment.inputBytes,
+      ...(quotaCheckedAt === undefined ? {} : { quotaCheckedAt }),
+    }
+  }
+
+  return Object.keys(normalized).length > 0 ? normalized : undefined
+}
+
 export function getSidebarStateFile(): string {
   return process.env[STATE_FILE_ENV] || DEFAULT_STATE_FILE
 }
@@ -212,6 +308,9 @@ export function normalizeSidebarState(raw: unknown): SidebarState {
     main = {
       quota: ('quota' in m ? m.quota : null) as AccountQuota | null,
       killed: typeof m.killed === 'boolean' ? m.killed : false,
+      ...(typeof m.mainAccountId === 'string'
+        ? { mainAccountId: m.mainAccountId }
+        : {}),
       // Preserve optional backoff fields if present
       ...(typeof m.quotaBackedOff === 'boolean'
         ? { quotaBackedOff: m.quotaBackedOff }
@@ -247,6 +346,9 @@ export function normalizeSidebarState(raw: unknown): SidebarState {
         .map((e) => ({
           id: e.id as string,
           label: typeof e.label === 'string' ? e.label : undefined,
+          ...(typeof e.accountId === 'string'
+            ? { accountId: e.accountId }
+            : {}),
           quota: ('quota' in e ? e.quota : null) as AccountQuota | null,
           killed: typeof e.killed === 'boolean' ? e.killed : false,
           enabled: typeof e.enabled === 'boolean' ? e.enabled : true,
@@ -268,6 +370,7 @@ export function normalizeSidebarState(raw: unknown): SidebarState {
   const planType = typeof r.planType === 'string' ? r.planType : undefined
   const credits = typeof r.credits === 'number' ? r.credits : undefined
   const activeRouting = normalizeActiveRouting(r.activeRouting)
+  const stickyAssignments = normalizeStickyAssignments(r.stickyAssignments)
   return {
     main,
     fallbacks,
@@ -275,14 +378,17 @@ export function normalizeSidebarState(raw: unknown): SidebarState {
     route,
     lastUpdated,
     ...(activeRouting !== undefined ? { activeRouting } : {}),
+    ...(stickyAssignments !== undefined ? { stickyAssignments } : {}),
     ...(planType !== undefined ? { planType } : {}),
     ...(credits !== undefined ? { credits } : {}),
   }
 }
 
-export async function getSidebarState(): Promise<SidebarState> {
+export async function getSidebarState(
+  stateFile = getSidebarStateFile(),
+): Promise<SidebarState> {
   try {
-    const raw = await readFile(getSidebarStateFile(), 'utf8')
+    const raw = await readFile(stateFile, 'utf8')
     return normalizeSidebarState(JSON.parse(raw))
   } catch {
     return DEFAULT_SIDEBAR_STATE
@@ -295,24 +401,97 @@ export const ACTIVE_ROUTING_MAX_ENTRIES = 128
 export type SidebarRoutingAccount = {
   id: string
   enabled?: boolean
+  killed?: boolean
 }
 
 export function isUsableRoutingEntry(
   entry: ActiveRoutingEntry,
-  accounts: readonly SidebarRoutingAccount[],
+  accounts: readonly SidebarRoutingAccount[] | undefined,
   now = Date.now(),
 ): boolean {
   const fresh =
     entry.updatedAt >= now - ACTIVE_ROUTING_MAX_AGE_MS && entry.updatedAt <= now
   if (!fresh) return false
+  if (accounts === undefined) return true
   return (
     entry.activeId === 'main' ||
     accounts.some(
-      (account) => account.enabled !== false && account.id === entry.activeId,
+      (account) =>
+        account.enabled !== false &&
+        account.killed !== true &&
+        account.id === entry.activeId,
     )
   )
 }
 
+// Earliest future reset among the quota's exhausted windows, or undefined when
+// no present window is exhausted. Every present window is evaluated — matching
+// the admission policy, which rejects an account when ANY live window is below
+// its threshold — and each check fails open: a missing/malformed usage, a
+// missing/unparsable reset, or a reset already in the past never counts as
+// exhausted, so a stale or corrupt snapshot can never block routing.
+export function exhaustedQuotaResetAt(
+  quota: AccountQuota | null | undefined,
+  now = Date.now(),
+): { resetsAt: string; resetAtMs: number } | undefined {
+  let earliest: { resetsAt: string; resetAtMs: number } | undefined
+  for (const key of QUOTA_WINDOW_KEYS) {
+    const window = quota?.[key]
+    if (
+      typeof window?.resetsAt !== 'string' ||
+      !Number.isFinite(window.usedPercent) ||
+      window.usedPercent < 100
+    ) {
+      continue
+    }
+    const resetAtMs = Date.parse(window.resetsAt)
+    if (!Number.isFinite(resetAtMs) || resetAtMs <= now) continue
+    if (!earliest || resetAtMs < earliest.resetAtMs) {
+      earliest = { resetsAt: window.resetsAt, resetAtMs }
+    }
+  }
+  return earliest
+}
+
+export function isQuotaExhausted(
+  quota: AccountQuota | null | undefined,
+  now = Date.now(),
+): boolean {
+  return exhaustedQuotaResetAt(quota, now) !== undefined
+}
+
+export function resolveSessionStickyAccount(
+  state: SidebarState,
+  sessionId: string | undefined,
+  now = Date.now(),
+): string | undefined {
+  if (!sessionId || state.route !== 'sticky-balanced') return undefined
+  const assignment = state.stickyAssignments?.[hashSidebarSessionId(sessionId)]
+  if (
+    !assignment ||
+    assignment.lastSeenAt < now - STICKY_ASSIGNMENT_MAX_AGE_MS
+  ) {
+    return undefined
+  }
+  if (assignment.accountId === 'main') {
+    return state.main?.killed || isQuotaExhausted(state.main?.quota, now)
+      ? undefined
+      : 'main'
+  }
+  const fallback = state.fallbacks?.find(
+    (account) => account.id === assignment.accountId,
+  )
+  if (
+    !fallback ||
+    fallback.enabled === false ||
+    fallback.killed === true ||
+    isQuotaExhausted(fallback.quota, now)
+  ) {
+    return undefined
+  }
+  return fallback.id
+}
+
 export function resolveSessionSidebarRouting(
   state: SidebarState,
   sessionId?: string,
@@ -322,13 +501,29 @@ export function resolveSessionSidebarRouting(
     return { activeId: state.activeId ?? 'main', route: state.route }
   }
   const own = sessionId ? state.activeRouting?.[sessionId] : undefined
-  if (own && isUsableRoutingEntry(own, state.fallbacks, now)) {
+  const ownQuota =
+    own?.activeId === 'main'
+      ? state.main.quota
+      : state.fallbacks.find((account) => account.id === own?.activeId)?.quota
+  if (
+    own &&
+    isUsableRoutingEntry(own, state.fallbacks, now) &&
+    !isQuotaExhausted(ownQuota, now)
+  ) {
     return { activeId: own.activeId, route: own.route }
   }
 
-  const fallback = state.fallbacks.find(
+  const stickyAccountId = resolveSessionStickyAccount(state, sessionId, now)
+  if (stickyAccountId) {
+    return { activeId: stickyAccountId, route: state.route }
+  }
+
+  const enabledFallbacks = state.fallbacks.filter(
     (account) => account.enabled && !account.killed,
   )
+  const fallback =
+    enabledFallbacks.find((account) => !isQuotaExhausted(account.quota, now)) ??
+    enabledFallbacks[0]
   return {
     activeId:
       state.route === 'fallback-first' && fallback ? fallback.id : 'main',
@@ -338,7 +533,7 @@ export function resolveSessionSidebarRouting(
 
 export function pruneActiveRouting(
   activeRouting: ActiveRoutingMap | undefined,
-  accounts: readonly SidebarRoutingAccount[],
+  accounts: readonly SidebarRoutingAccount[] | undefined,
   now = Date.now(),
   removedSessionId?: string,
 ): ActiveRoutingMap | undefined {
@@ -357,6 +552,175 @@ export function pruneActiveRouting(
   return bounded.length > 0 ? Object.fromEntries(bounded) : undefined
 }
 
+export function pruneStickyAssignments(
+  assignments: StickyAssignmentMap | undefined,
+  validAccountIds: ReadonlySet<string> | undefined,
+  now = Date.now(),
+  removedSessionHash?: string,
+): StickyAssignmentMap | undefined {
+  if (!assignments) return undefined
+  let accountNotInRoster = 0
+  let expired = 0
+  let explicitRemoval = 0
+  const kept: [string, StickyAssignment][] = []
+  for (const [sessionHash, assignment] of Object.entries(assignments)) {
+    if (sessionHash === removedSessionHash) {
+      explicitRemoval += 1
+      continue
+    }
+    if (assignment.lastSeenAt < now - STICKY_ASSIGNMENT_MAX_AGE_MS) {
+      expired += 1
+      continue
+    }
+    if (
+      validAccountIds !== undefined &&
+      !validAccountIds.has(assignment.accountId)
+    ) {
+      accountNotInRoster += 1
+      continue
+    }
+    kept.push([sessionHash, assignment])
+  }
+  const removed = accountNotInRoster + expired + explicitRemoval
+  if (removed > 0) {
+    logSb.debug('pruned sticky assignments', {
+      pid: process.pid,
+      removed,
+      reasons: {
+        'account-not-in-roster': accountNotInRoster,
+        expired,
+        'explicit-removal': explicitRemoval,
+      },
+    })
+  }
+  return kept.length > 0 ? Object.fromEntries(kept) : undefined
+}
+
+function limitStickyAssignments(
+  assignments: StickyAssignmentMap,
+  protectedSessionHash: string,
+): StickyAssignmentMap {
+  const overflow =
+    Object.keys(assignments).length - STICKY_ASSIGNMENT_MAX_ENTRIES
+  if (overflow <= 0) return assignments
+  const evicted = new Set(
+    Object.entries(assignments)
+      .filter(([sessionHash]) => sessionHash !== protectedSessionHash)
+      .sort(
+        ([leftHash, left], [rightHash, right]) =>
+          left.lastSeenAt - right.lastSeenAt ||
+          leftHash.localeCompare(rightHash),
+      )
+      .slice(0, overflow)
+      .map(([sessionHash]) => sessionHash),
+  )
+  return Object.fromEntries(
+    Object.entries(assignments).filter(
+      ([sessionHash]) => !evicted.has(sessionHash),
+    ),
+  )
+}
+
+function stickyAssignmentsEqual(
+  left: StickyAssignmentMap | undefined,
+  right: StickyAssignmentMap | undefined,
+): boolean {
+  if (left === right) return true
+  if (!left || !right) return false
+  const leftEntries = Object.entries(left)
+  if (leftEntries.length !== Object.keys(right).length) return false
+  return leftEntries.every(([sessionHash, assignment]) =>
+    Object.is(right[sessionHash], assignment),
+  )
+}
+
+function isValidStickyAssignment(
+  assignment: StickyAssignment | undefined,
+  validPinnedAccountIds: ReadonlySet<string>,
+  excludedAccountIds: ReadonlySet<string>,
+  now: number,
+): assignment is StickyAssignment {
+  return (
+    assignment !== undefined &&
+    validPinnedAccountIds.has(assignment.accountId) &&
+    !excludedAccountIds.has(assignment.accountId) &&
+    assignment.lastSeenAt >= now - STICKY_ASSIGNMENT_MAX_AGE_MS
+  )
+}
+
+function stickyAssignmentNeedsMetadataUpdate(
+  assignment: StickyAssignment,
+  requestBytes: number,
+  now: number,
+): boolean {
+  return (
+    requestBytes > assignment.inputBytes ||
+    now - assignment.lastSeenAt >= STICKY_ASSIGNMENT_LAST_SEEN_TOUCH_MS
+  )
+}
+
+function readonlyPendingBytes(
+  pendingBytes: Map<string, number>,
+): ReadonlyMap<string, number> {
+  const snapshot = new Map(pendingBytes)
+  const view: ReadonlyMap<string, number> = {
+    get size() {
+      return snapshot.size
+    },
+    has: (key: string) => snapshot.has(key),
+    get: (key: string) => snapshot.get(key),
+    entries: () => snapshot.entries(),
+    keys: () => snapshot.keys(),
+    values: () => snapshot.values(),
+    forEach: (
+      callback: (
+        value: number,
+        key: string,
+        map: ReadonlyMap<string, number>,
+      ) => void,
+      thisArg?: unknown,
+    ) => {
+      snapshot.forEach((value, key) => {
+        callback.call(thisArg, value, key, view)
+      })
+    },
+    [Symbol.iterator]: () => snapshot[Symbol.iterator](),
+  }
+  return Object.freeze(view)
+}
+
+function pendingBytesForAssignments(
+  assignments: StickyAssignmentMap | undefined,
+  quotaCheckedAtByAccount: Readonly<Record<string, number | undefined>>,
+): ReadonlyMap<string, number> {
+  const pendingBytes = new Map<string, number>()
+  for (const assignment of Object.values(assignments ?? {})) {
+    if (
+      assignment.quotaCheckedAt !==
+      quotaCheckedAtByAccount[assignment.accountId]
+    ) {
+      continue
+    }
+    pendingBytes.set(
+      assignment.accountId,
+      (pendingBytes.get(assignment.accountId) ?? 0) + assignment.inputBytes,
+    )
+  }
+  return readonlyPendingBytes(pendingBytes)
+}
+
+function usableRoutingAccountIds(
+  accounts: readonly SidebarRoutingAccount[] | undefined,
+): ReadonlySet<string> | undefined {
+  if (accounts === undefined) return undefined
+  return new Set([
+    'main',
+    ...accounts
+      .filter((account) => account.enabled !== false && account.killed !== true)
+      .map((account) => account.id),
+  ])
+}
+
 // Serialization chain: concurrent calls are queued so a stale background
 // write cannot land after a newer one and corrupt the file.
 let sidebarWriteChain: Promise<void> = Promise.resolve()
@@ -419,7 +783,7 @@ function parseSidebarState(raw: string): SidebarState {
 }
 
 async function acquireSidebarWriteLock(file: string) {
-  await mkdir(dirname(file), { recursive: true })
+  await ensureSidebarStateDirectory(file)
   const deadline = Date.now() + SIDEBAR_WRITE_LOCK_WAIT_MS
   while (Date.now() <= deadline) {
     const lock = await acquireRefreshFileLock({
@@ -434,9 +798,21 @@ async function acquireSidebarWriteLock(file: string) {
   throw new Error('Timed out waiting for the sidebar state write lock')
 }
 
+async function ensureSidebarStateDirectory(file: string): Promise<void> {
+  const dir = dirname(file)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  if (file !== DEFAULT_STATE_FILE) return
+  await chmod(dir, 0o700).catch((error) => {
+    logSb.warn('sidebar directory permission remediation failed', {
+      pid: process.pid,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  })
+}
+
 async function writeMergedSidebarState(
   file: string,
-  merge: (latest: SidebarState) => SidebarState,
+  merge: (latest: SidebarState) => SidebarState | undefined,
   hooks?: SidebarMergeHooks,
 ): Promise<void> {
   const lock = await acquireSidebarWriteLock(file)
@@ -446,6 +822,7 @@ async function writeMergedSidebarState(
     for (let attempt = 0; attempt < MAX_MERGE_ATTEMPTS; attempt += 1) {
       const rawBefore = await readRawSidebar(file)
       const next = merge(parseSidebarState(rawBefore))
+      if (!next) return
       if (attempt === 0) await hooks?.beforeRecheck?.()
       const rawRecheck = await readRawSidebar(file)
       if (rawRecheck !== rawBefore) continue
@@ -454,7 +831,8 @@ async function writeMergedSidebarState(
     }
 
     const latest = await readSidebarState(file)
-    await doWriteSidebarState(merge(latest), file)
+    const next = merge(latest)
+    if (next) await doWriteSidebarState(next, file)
   } finally {
     await lock.release()
   }
@@ -465,6 +843,156 @@ export type SidebarMachineState = Pick<
   'main' | 'fallbacks' | 'planType' | 'credits' | 'lastUpdated'
 > & { route: string }
 
+// The freshest signal across every timestamp a snapshot carries: either window
+// (primary/secondary) or the legacy top-level stamp. A retired primary window
+// (null) with a fresh secondary must still outrank an older incoming primary, so
+// the comparison takes the max rather than the first present value.
+function latestQuotaCheckedAt(quota: AccountQuota | null): number | undefined {
+  let latest: number | undefined
+  for (const checkedAt of [
+    quota?.primary?.checkedAt,
+    quota?.secondary?.checkedAt,
+    quota?.checkedAt,
+  ]) {
+    if (typeof checkedAt === 'number' && Number.isFinite(checkedAt)) {
+      latest = latest === undefined ? checkedAt : Math.max(latest, checkedAt)
+    }
+  }
+  return latest
+}
+
+function freshestQuota(
+  incoming: AccountQuota | null,
+  existing: AccountQuota | null,
+): AccountQuota | null {
+  const incomingCheckedAt = latestQuotaCheckedAt(incoming)
+  const existingCheckedAt = latestQuotaCheckedAt(existing)
+  if (
+    existingCheckedAt !== undefined &&
+    (incomingCheckedAt === undefined || existingCheckedAt > incomingCheckedAt)
+  ) {
+    return existing
+  }
+  return incoming
+}
+
+// True when both sides assert the same stable account identity. An unknown
+// identity on either side is NOT a confirmed match — merging windows across an
+// unconfirmed identity could combine two accounts' quota, so the caller
+// whole-picks instead.
+function sameAccountIdentity(
+  incoming: string | undefined,
+  existing: string | undefined,
+): boolean {
+  return (
+    incoming !== undefined && existing !== undefined && incoming === existing
+  )
+}
+
+// A window's checkedAt when it is a usable timestamp, else undefined — so an
+// absent or invalid stamp sorts oldest and a timestamped window always wins
+// over an untimestamped one. The optional fallback is the enclosing snapshot's
+// checkedAt, used when the window itself carries no usable stamp (files written
+// by versions that did not propagate the entry timestamp onto each present
+// window): a present window with no stamp is still "live", so it must sort by
+// SOME timestamp — the snapshot's is the next-best signal.
+function finiteWindowCheckedAt(
+  window: QuotaWindow | undefined,
+  fallback?: number,
+): number | undefined {
+  const checkedAt = window?.checkedAt
+  if (typeof checkedAt === 'number' && Number.isFinite(checkedAt)) {
+    return checkedAt
+  }
+  if (typeof fallback === 'number' && Number.isFinite(fallback)) {
+    return fallback
+  }
+  return undefined
+}
+
+// Fresher of two same-slot windows. When both sides report the window, the
+// window's own stamp decides (falling back to each side's snapshot stamp when
+// the window itself has none). When the slots disagree on presence, the FRESHER
+// snapshot's slot is authoritative — a quota snapshot reports every live window,
+// so an absent slot there means the wire retired it, which a stale window on the
+// other side must not resurrect (and a fresher snapshot's present window must
+// not be dropped by a stale window-less write).
+function freshestWindow(
+  incoming: QuotaWindow | undefined,
+  existing: QuotaWindow | undefined,
+  existingSnapshotIsFresher: boolean,
+  incomingSnapshotCheckedAt: number | undefined,
+  existingSnapshotCheckedAt: number | undefined,
+): QuotaWindow | undefined {
+  if (incoming && existing) {
+    const incomingAt = finiteWindowCheckedAt(
+      incoming,
+      incomingSnapshotCheckedAt,
+    )
+    const existingAt = finiteWindowCheckedAt(
+      existing,
+      existingSnapshotCheckedAt,
+    )
+    if (
+      existingAt !== undefined &&
+      (incomingAt === undefined || existingAt > incomingAt)
+    ) {
+      return existing
+    }
+    return incoming
+  }
+  return existingSnapshotIsFresher ? existing : incoming
+}
+
+// Merge two same-account snapshots window-by-window: each slot keeps the
+// fresher of the two sides, so a newer primary on one side and a newer
+// secondary on the other both survive instead of one side's whole snapshot
+// replacing the other's. The snapshot stamp becomes the freshest window stamp
+// of the merged result. Only safe when both snapshots share an account identity
+// (sameAccountIdentity) — an identity switch must whole-pick (freshestQuota) so
+// windows from two accounts are never combined.
+function mergeQuotaByWindow(
+  incoming: AccountQuota | null,
+  existing: AccountQuota | null,
+): AccountQuota | null {
+  if (!incoming) return existing
+  if (!existing) return incoming
+  const incomingAt = latestQuotaCheckedAt(incoming)
+  const existingAt = latestQuotaCheckedAt(existing)
+  const existingSnapshotIsFresher =
+    existingAt !== undefined &&
+    (incomingAt === undefined || existingAt > incomingAt)
+  const primary = freshestWindow(
+    incoming.primary,
+    existing.primary,
+    existingSnapshotIsFresher,
+    incoming.checkedAt,
+    existing.checkedAt,
+  )
+  const secondary = freshestWindow(
+    incoming.secondary,
+    existing.secondary,
+    existingSnapshotIsFresher,
+    incoming.checkedAt,
+    existing.checkedAt,
+  )
+  let checkedAt: number | undefined
+  for (const stamp of [
+    finiteWindowCheckedAt(primary),
+    finiteWindowCheckedAt(secondary),
+  ]) {
+    if (stamp !== undefined) {
+      checkedAt = checkedAt === undefined ? stamp : Math.max(checkedAt, stamp)
+    }
+  }
+  return {
+    ...incoming,
+    primary,
+    secondary,
+    checkedAt: checkedAt ?? incoming.checkedAt,
+  }
+}
+
 export function setSidebarMachineState(
   machineState: SidebarMachineState,
   file = getSidebarStateFile(),
@@ -473,13 +1001,70 @@ export function setSidebarMachineState(
   return enqueueSidebarWrite(async () => {
     await writeMergedSidebarState(
       file,
-      (latest) => ({
-        ...latest,
-        ...machineState,
-        activeId: latest.activeId,
-        activeRouting: latest.activeRouting,
-        lastUpdated: Math.max(Date.now(), latest.lastUpdated + 1),
-      }),
+      (latest) => {
+        const latestFallbacks = new Map(
+          latest.fallbacks.map((account) => [account.id, account]),
+        )
+        // A same-identity merge combines the freshest of each window across the
+        // two sides; a differing or unknown identity whole-picks the fresher
+        // snapshot so windows from two accounts are never combined.
+        const mainSameIdentity = sameAccountIdentity(
+          machineState.main.mainAccountId,
+          latest.main.mainAccountId,
+        )
+        const mergedMainQuota = mainSameIdentity
+          ? mergeQuotaByWindow(machineState.main.quota, latest.main.quota)
+          : freshestQuota(machineState.main.quota, latest.main.quota)
+        const now = Date.now()
+        const stickyAssignments = pruneStickyAssignments(
+          latest.stickyAssignments,
+          usableRoutingAccountIds(machineState.fallbacks),
+          now,
+        )
+        return {
+          ...latest,
+          ...machineState,
+          main: {
+            ...machineState.main,
+            quota: mergedMainQuota,
+            // On a whole-pick the identity follows the winning snapshot, so a
+            // reader never pairs one account's id with another account's quota
+            // (a re-login race would otherwise resurrect the stale-account bug).
+            // On a same-identity merge both sides already agree, so the incoming
+            // id is the shared one.
+            mainAccountId: mainSameIdentity
+              ? machineState.main.mainAccountId
+              : mergedMainQuota === latest.main.quota &&
+                  mergedMainQuota !== machineState.main.quota
+                ? latest.main.mainAccountId
+                : machineState.main.mainAccountId,
+          },
+          fallbacks: machineState.fallbacks.map((account) => {
+            const existing = latestFallbacks.get(account.id)
+            const fallbackSameIdentity = sameAccountIdentity(
+              account.accountId,
+              existing?.accountId,
+            )
+            const mergedQuota = fallbackSameIdentity
+              ? mergeQuotaByWindow(account.quota, existing?.quota ?? null)
+              : freshestQuota(account.quota, existing?.quota ?? null)
+            return {
+              ...account,
+              quota: mergedQuota,
+              accountId: fallbackSameIdentity
+                ? account.accountId
+                : mergedQuota === existing?.quota &&
+                    mergedQuota !== account.quota
+                  ? existing?.accountId
+                  : account.accountId,
+            }
+          }),
+          activeId: latest.activeId,
+          activeRouting: latest.activeRouting,
+          stickyAssignments,
+          lastUpdated: Math.max(now, latest.lastUpdated + 1),
+        }
+      },
       hooks,
     )
   })
@@ -487,7 +1072,7 @@ export function setSidebarMachineState(
 
 export function upsertSidebarActiveRouting(
   input: { sessionId: string } & ActiveRoutingEntry,
-  accounts: readonly SidebarRoutingAccount[],
+  accounts: readonly SidebarRoutingAccount[] | undefined,
   file = getSidebarStateFile(),
   hooks?: SidebarMergeHooks,
 ): Promise<void> {
@@ -507,11 +1092,17 @@ export function upsertSidebarActiveRouting(
           accounts,
           Date.now(),
         )
+        const stickyAssignments = pruneStickyAssignments(
+          latest.stickyAssignments,
+          usableRoutingAccountIds(accounts),
+          Date.now(),
+        )
         return {
           ...latest,
           activeId: input.activeId,
           route: input.route,
           activeRouting,
+          stickyAssignments,
           lastUpdated: Math.max(Date.now(), latest.lastUpdated + 1),
         }
       },
@@ -536,7 +1127,7 @@ export function setSidebarLegacyRouting(
 
 export function removeSidebarActiveRouting(
   sessionId: string,
-  accounts: readonly SidebarRoutingAccount[],
+  accounts: readonly SidebarRoutingAccount[] | undefined,
   file = getSidebarStateFile(),
   hooks?: SidebarMergeHooks,
 ): Promise<void> {
@@ -551,9 +1142,16 @@ export function removeSidebarActiveRouting(
           now,
           sessionId,
         )
+        const stickyAssignments = pruneStickyAssignments(
+          latest.stickyAssignments,
+          usableRoutingAccountIds(accounts),
+          now,
+          hashSidebarSessionId(sessionId),
+        )
         return {
           ...latest,
           activeRouting,
+          stickyAssignments,
           lastUpdated: Math.max(Date.now(), latest.lastUpdated + 1),
         }
       },
@@ -562,14 +1160,164 @@ export function removeSidebarActiveRouting(
   })
 }
 
+export async function resolveSidebarStickyAssignment(
+  input: ResolveStickyAssignmentInput,
+  file = getSidebarStateFile(),
+  hooks?: SidebarMergeHooks,
+): Promise<StickyAssignment | undefined> {
+  const sessionHash = hashSidebarSessionId(input.sessionId)
+  const validPinnedAccountIds = new Set(input.validPinnedAccountIds)
+  const excludedAccountIds = new Set(input.excludeAccountIds)
+  const existing = (await readSidebarState(file)).stickyAssignments?.[
+    sessionHash
+  ]
+  if (
+    isValidStickyAssignment(
+      existing,
+      validPinnedAccountIds,
+      excludedAccountIds,
+      input.now,
+    ) &&
+    !stickyAssignmentNeedsMetadataUpdate(
+      existing,
+      input.requestBytes,
+      input.now,
+    )
+  ) {
+    return existing
+  }
+
+  let resolved: StickyAssignment | undefined
+  await enqueueSidebarWrite(async () => {
+    await writeMergedSidebarState(
+      file,
+      (latest) => {
+        const stickyAssignments = pruneStickyAssignments(
+          latest.stickyAssignments,
+          validPinnedAccountIds,
+          input.now,
+        )
+        const assignmentsPruned = !stickyAssignmentsEqual(
+          latest.stickyAssignments,
+          stickyAssignments,
+        )
+        const current = stickyAssignments?.[sessionHash]
+        if (
+          isValidStickyAssignment(
+            current,
+            validPinnedAccountIds,
+            excludedAccountIds,
+            input.now,
+          )
+        ) {
+          const metadataNeedsUpdate = stickyAssignmentNeedsMetadataUpdate(
+            current,
+            input.requestBytes,
+            input.now,
+          )
+          const assignment = metadataNeedsUpdate
+            ? {
+                ...current,
+                inputBytes: Math.max(current.inputBytes, input.requestBytes),
+                ...(input.now - current.lastSeenAt >=
+                STICKY_ASSIGNMENT_LAST_SEEN_TOUCH_MS
+                  ? { lastSeenAt: input.now }
+                  : {}),
+              }
+            : current
+          resolved = assignment
+          if (!assignmentsPruned && !metadataNeedsUpdate) return undefined
+          return {
+            ...latest,
+            stickyAssignments: {
+              ...stickyAssignments,
+              [sessionHash]: assignment,
+            },
+            lastUpdated: Math.max(input.now, latest.lastUpdated + 1),
+          }
+        }
+
+        const choice = input.choose(
+          pendingBytesForAssignments(
+            stickyAssignments,
+            input.quotaCheckedAtByAccount,
+          ),
+        )
+        if (!choice) {
+          resolved = undefined
+          if (!assignmentsPruned) return undefined
+          return {
+            ...latest,
+            stickyAssignments,
+            lastUpdated: Math.max(input.now, latest.lastUpdated + 1),
+          }
+        }
+
+        resolved = {
+          accountId: choice.accountId,
+          assignedAt: input.now,
+          lastSeenAt: input.now,
+          inputBytes: input.requestBytes,
+          ...(choice.quotaCheckedAt === undefined
+            ? {}
+            : { quotaCheckedAt: choice.quotaCheckedAt }),
+        }
+        return {
+          ...latest,
+          stickyAssignments: limitStickyAssignments(
+            {
+              ...stickyAssignments,
+              [sessionHash]: resolved,
+            },
+            sessionHash,
+          ),
+          lastUpdated: Math.max(input.now, latest.lastUpdated + 1),
+        }
+      },
+      hooks,
+    )
+  })
+  return resolved
+}
+
+export async function clearSidebarStickyAssignment(
+  sessionId: string,
+  file = getSidebarStateFile(),
+): Promise<boolean> {
+  const sessionHash = hashSidebarSessionId(sessionId)
+  let removed = false
+  await enqueueSidebarWrite(async () => {
+    await writeMergedSidebarState(file, (latest) => {
+      const assignments = latest.stickyAssignments
+      if (assignments?.[sessionHash] === undefined) {
+        removed = false
+        return undefined
+      }
+      removed = true
+      const { [sessionHash]: _removed, ...remaining } = assignments
+      return {
+        ...latest,
+        ...(Object.keys(remaining).length > 0
+          ? { stickyAssignments: remaining }
+          : { stickyAssignments: undefined }),
+        lastUpdated: Math.max(Date.now(), latest.lastUpdated + 1),
+      }
+    })
+  })
+  return removed
+}
+
 async function doWriteSidebarState(
   state: SidebarState,
   file: string,
 ): Promise<void> {
   const tempPath = `${file}.${randomUUID()}.tmp`
   try {
-    await mkdir(dirname(file), { recursive: true })
-    await writeFile(tempPath, JSON.stringify(state), 'utf8')
+    await ensureSidebarStateDirectory(file)
+    await writeFile(tempPath, JSON.stringify(normalizeSidebarState(state)), {
+      encoding: 'utf8',
+      mode: 0o600,
+    })
     await rename(tempPath, file)
   } catch (e) {
     await rm(tempPath, { force: true }).catch(() => {})