@crouton-kit/crouter 0.3.78 → 0.3.79

package/dist/builtin-pi-packages/pi-crtr-extensions/lib/subscription-state.ts

@@ -1,787 +1,2 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { defaultModelLaddersConfig } from "../../../types.js";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-export const ANTHROPIC_PROVIDER_ID = "anthropic";
-export const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
-
-export type ManagedProviderId = typeof ANTHROPIC_PROVIDER_ID | typeof OPENAI_CODEX_PROVIDER_ID;
-export type LadderProviderId = "anthropic" | "openai";
-export type ModelStrength = "ultra" | "strong" | "medium" | "light";
-
-// The default label's slot (`label === providerId`) is the OAuth-login-linked credential --
-// its live value (`refresh`/`access`/`expires`) is owned exclusively by pi's auth.json (see
-// provider-rotation.ts's `refreshDefaultSlotCredential`/`reauthenticateCredential`), so those
-// fields are absent on that entry. Any OTHER explicitly-added account (`/provider-sub add`,
-// label !== providerId) keeps the full value here, unchanged.
-export type SubscriptionCredential = {
-  label: string;
-  refresh?: string;
-  access?: string;
-  expires?: number;
-  rateLimitedUntil: number;
-  lastAttemptAt: number;
-  lastRateLimitedAt: number;
-  // Provider account identity, captured at login for Codex (the JWT `chatgpt_account_id`).
-  // Absent on Anthropic entries (their OAuth token carries no account claim) and on legacy
-  // entries added before identity capture -- a missing `accountId` means "unknown identity"
-  // and makes no dedupe claim.
-  accountId?: string;
-};
-
-export type ModelRef = {
-  providerId: ManagedProviderId;
-  modelId: string;
-};
-
-export type RotationConfig = {
-  defaultFallbackStrength?: ModelStrength;
-  revertWhenAvailable?: boolean;
-  preferredModel?: ModelRef;
-};
-
-type RotationConfigUpdate = {
-  defaultFallbackStrength?: ModelStrength;
-  revertWhenAvailable?: boolean;
-  preferredModel?: ModelRef | null;
-};
-
-export type FallbackTarget = {
-  providerId: ManagedProviderId;
-  modelId: string;
-  label: string;
-  strength: ModelStrength;
-  thinkingLevel?: ThinkingLevel;
-};
-
-type ModelLadderConfig = Partial<Record<ModelStrength, string>>;
-type ModelLaddersConfig = Partial<Record<LadderProviderId, ModelLadderConfig>>;
-const AGENT_DIR = join(homedir(), ".pi", "agent");
-const ROTATION_CONFIG_FILE = join(AGENT_DIR, "provider-rotation.json");
-const CROUTER_CONFIG_FILE = join(homedir(), ".crouter", "config.json");
-const DEFAULT_FALLBACK_STRENGTH: ModelStrength = "strong";
-
-const PROVIDERS: Record<
-  ManagedProviderId,
-  {
-    label: string;
-    ladderProviderId: LadderProviderId;
-    poolFile: string;
-  }
-> = {
-  [ANTHROPIC_PROVIDER_ID]: {
-    label: "Claude",
-    ladderProviderId: "anthropic",
-    poolFile: join(AGENT_DIR, "anthropic-subscriptions.json"),
-  },
-  [OPENAI_CODEX_PROVIDER_ID]: {
-    label: "OpenAI Codex",
-    ladderProviderId: "openai",
-    poolFile: join(AGENT_DIR, "openai-codex-subscriptions.json"),
-  },
-};
-
-function readJsonFile<T>(path: string): T | undefined {
-  if (!existsSync(path)) return undefined;
-  try {
-    const raw = readFileSync(path, "utf8").trim();
-    if (!raw) return undefined;
-    return JSON.parse(raw) as T;
-  } catch {
-    return undefined;
-  }
-}
-
-function writeJsonFile(path: string, value: unknown, mode?: number): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, mode === undefined ? "utf8" : { encoding: "utf8", mode });
-  if (mode !== undefined) chmodSync(tmp, mode);
-  renameSync(tmp, path);
-}
-
-function normalizeStrength(value: unknown): ModelStrength | undefined {
-  return value === "ultra" || value === "strong" || value === "medium" || value === "light" ? value : undefined;
-}
-
-function normalizeTiming(value: unknown): number {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : 0;
-}
-
-function normalizeCredential(value: Partial<SubscriptionCredential> & { label?: string }): SubscriptionCredential | undefined {
-  const label = typeof value.label === "string" ? value.label.trim() : "";
-  if (!label) return undefined;
-  const refresh = typeof value.refresh === "string" ? value.refresh.trim() : "";
-  const access = typeof value.access === "string" ? value.access.trim() : "";
-  const accountId = typeof value.accountId === "string" ? value.accountId.trim() : "";
-  const expires = Number(value.expires);
-  const rateLimitedUntil = Number(value.rateLimitedUntil);
-  return {
-    label,
-    ...(refresh && access ? { refresh, access, expires: Number.isFinite(expires) ? expires : 0 } : {}),
-    ...(accountId ? { accountId } : {}),
-    rateLimitedUntil: Number.isFinite(rateLimitedUntil) ? rateLimitedUntil : 0,
-    lastAttemptAt: normalizeTiming(value.lastAttemptAt),
-    lastRateLimitedAt: normalizeTiming(value.lastRateLimitedAt),
-  };
-}
-
-function normalizeCredentials(values: unknown): SubscriptionCredential[] {
-  if (!Array.isArray(values)) return [];
-  return values.map((entry) => normalizeCredential(entry as Partial<SubscriptionCredential> & { label?: string })).filter((entry): entry is SubscriptionCredential => Boolean(entry));
-}
-
-function getCurrentModelRef(model?: { provider: string; id: string }): ModelRef | undefined {
-  return isManagedProvider(model?.provider) ? { providerId: model.provider, modelId: model.id } : undefined;
-}
-
-type AuthFileData = Record<string, { type?: string; accountId?: unknown }>;
-
-function readAuthCredential(providerId: ManagedProviderId): { type?: string; accountId?: string } | undefined {
-  return new FileAuthStorageBackend().withLock((current) => {
-    if (!current) return { result: undefined };
-    const data = JSON.parse(current) as AuthFileData;
-    const record = data[providerId];
-    if (!record) return { result: undefined };
-    const accountId = typeof record.accountId === "string" && record.accountId.trim() ? record.accountId.trim() : undefined;
-    return { result: { type: record.type, accountId } };
-  });
-}
-
-// Reconciles the METADATA-ONLY pool entry for the default label (`label === providerId`)
-// against auth.json, which is the source of truth for the default slot's identity. auth.json
-// is read through FileAuthStorageBackend's real lock so a held auth.json lock or parse failure
-// is surfaced instead of silently pretending the default credential is absent. Gated
-// specifically on an OAUTH auth.json record (`type === "oauth"`) rather than the presence of
-// any credential, because an api_key credential has no refresh token -- a metadata-only
-// "default" slot seeded for one would be a slot `refreshDefaultSlotCredential` can never
-// actually refresh; with no oauth record the pool is left exactly as-is (never seeded, never
-// stripped). When an oauth record exists this ALWAYS re-derives the default entry's identity:
-// it seeds a missing entry and rewrites an existing entry's `accountId` to match auth.json's
-// (dropping it when auth.json carries none), preserving that entry's cooldown/timing fields.
-// A NEW array reference is returned only when something actually changed -- an in-sync pool
-// returns the SAME reference, which is what lets `readSubscriptionPool`'s heal-trigger and the
-// mutate primitive's change detection stay sound. No token is ever copied into the pool: the
-// value lives exclusively in auth.json. `accountId` IS identity metadata, so the default slot
-// participates in duplicate detection and `/provider-sub list` rendering like an explicit account.
-function ensureDefaultSubscriptionMetadata(providerId: ManagedProviderId, pool: SubscriptionCredential[]): SubscriptionCredential[] {
-  const authCred = readAuthCredential(providerId);
-  if (authCred?.type !== "oauth") return pool;
-  const desired = authCred.accountId;
-  const idx = pool.findIndex((entry) => entry.label === providerId);
-  if (idx === -1) {
-    const seeded = normalizeCredential({
-      label: providerId,
-      ...(desired ? { accountId: desired } : {}),
-      rateLimitedUntil: 0,
-      lastAttemptAt: 0,
-      lastRateLimitedAt: 0,
-    });
-    return seeded ? [...pool, seeded] : pool;
-  }
-  const existing = pool[idx];
-  if ((existing.accountId ?? undefined) === (desired ?? undefined)) return pool;
-  const next = [...pool];
-  if (desired) {
-    next[idx] = { ...existing, accountId: desired };
-  } else {
-    const { accountId: _drop, ...rest } = existing;
-    next[idx] = rest;
-  }
-  return next;
-}
-
-// The default label's value lives exclusively in auth.json, so its pool entry must never
-// carry `refresh`/`access`/`expires`; this strips those fields on every read and write,
-// self-healing any pool file that has them physically present on disk. `changed` tells
-// the caller whether anything was actually stripped, so `readSubscriptionPool` can
-// persist the metadata-only result immediately rather than leaving a stale copy on disk
-// until some unrelated write.
-function scrubDefaultValue(providerId: ManagedProviderId, pool: SubscriptionCredential[]): { pool: SubscriptionCredential[]; changed: boolean } {
-  let changed = false;
-  const next = pool.map((entry) => {
-    if (entry.label !== providerId || (entry.refresh === undefined && entry.access === undefined && entry.expires === undefined)) return entry;
-    changed = true;
-    const { refresh: _refresh, access: _access, expires: _expires, ...meta } = entry;
-    return meta;
-  });
-  return { pool: next, changed };
-}
-
-export function isManagedProvider(providerId: string | undefined): providerId is ManagedProviderId {
-  return providerId === ANTHROPIC_PROVIDER_ID || providerId === OPENAI_CODEX_PROVIDER_ID;
-}
-
-/** The `modelLadders` CONFIG key for a runtime provider id -- `openai-codex`
- *  (the runtime/auth id) maps to the `openai` ladder key used in
- *  ~/.crouter/config.json. Callers building a repair command that a user can
- *  paste into `crtr sys config set modelLadders.<key>...` must use THIS key,
- *  not the runtime provider id. */
-export function getLadderProviderId(providerId: ManagedProviderId): LadderProviderId {
-  return PROVIDERS[providerId].ladderProviderId;
-}
-
-export function getProviderLabel(providerId: ManagedProviderId): string {
-  return PROVIDERS[providerId].label;
-}
-
-// The ONE locked read/modify/write primitive for a provider pool file (design §1). Acquires
-// a cross-process lock ON THE POOL FILE via the same proper-lockfile-backed backend pi uses
-// for auth.json, re-reads + normalizes the pool UNDER the lock, applies the caller's pure
-// transform, and persists atomically (tmp+rename, mode 0600) before releasing. Every write to
-// a pool file goes through here -- that is what finally makes the causal cooldown guards sound
-// (they compare against fresh-under-lock state, not a stale snapshot).
-//
-// `fn` returning `undefined` means "no change, skip the write" (used by the timestamp guards).
-// `withLock` seeds a missing file with `{}` (an OBJECT, not an array) -- normalizeCredentials
-// coerces any non-array to [] so that first-lock seed is harmless; do not "fix" it into a parse
-// error. We do our OWN atomic write inside the callback and return `next: undefined` so the
-// backend's non-atomic writeFileSync path never runs and lock-free readers always observe a
-// whole snapshot.
-//
-// Lock ordering (contract): pool lock -> auth lock is legal (seeding reads auth.json under its
-// own FileAuthStorageBackend lock while holding the pool lock, via ensureDefaultSubscriptionMetadata
-// -> readAuthCredential). NEVER acquire a pool lock inside an auth-lock callback. Throws (rather
-// than proceeding unlocked) if lock acquisition is exhausted -- callers surface that as a visible
-// error, never a silent lost write.
-export function mutateSubscriptionPool(
-  providerId: ManagedProviderId,
-  fn: (pool: SubscriptionCredential[]) => SubscriptionCredential[] | undefined,
-): SubscriptionCredential[] {
-  const poolFile = PROVIDERS[providerId].poolFile;
-  const backend = new FileAuthStorageBackend(poolFile);
-  return backend.withLock((current) => {
-    let parsed: unknown;
-    try {
-      parsed = current ? JSON.parse(current) : undefined;
-    } catch {
-      parsed = undefined;
-    }
-    const { pool: scrubbed, changed: wasScrubbed } = scrubDefaultValue(providerId, normalizeCredentials(parsed));
-    const base = ensureDefaultSubscriptionMetadata(providerId, scrubbed);
-    const transformed = fn(base);
-    if (transformed === undefined) {
-      assertDefaultAccountAvailable(base, providerId);
-      // A causal timestamp guard may reject the caller's update while auth-driven identity
-      // reconciliation or token scrubbing still needs to heal the stored metadata.
-      if (wasScrubbed || base !== scrubbed) {
-        const healed = scrubDefaultValue(providerId, normalizeCredentials(base)).pool;
-        writeJsonFile(poolFile, healed, 0o600);
-        return { result: healed };
-      }
-      return { result: base };
-    }
-    const normalized = scrubDefaultValue(providerId, normalizeCredentials(transformed)).pool;
-    // Reconciliation may have projected a new default identity from auth.json. Validate the
-    // final candidate while the pool lock is still held, after the transform so a removal or
-    // default-account switch can repair an externally-created collision instead of bricking it.
-    assertDefaultAccountAvailable(normalized, providerId);
-    writeJsonFile(poolFile, normalized, 0o600);
-    return { result: normalized };
-  });
-}
-
-export function readSubscriptionPool(providerId: ManagedProviderId): SubscriptionCredential[] {
-  const poolFile = PROVIDERS[providerId].poolFile;
-  const raw = normalizeCredentials(readJsonFile<unknown>(poolFile));
-  const { pool: scrubbed, changed: wasScrubbed } = scrubDefaultValue(providerId, raw);
-  const withDefaultSlot = ensureDefaultSubscriptionMetadata(providerId, scrubbed);
-  // Reads are lock-free (a whole-file tmp+rename write means a reader always sees a complete
-  // snapshot). Only when the on-disk pool actually needs self-healing -- a stray default-slot
-  // value to scrub, or default metadata to reconcile with auth.json -- do we take the lock and
-  // re-derive the healed pool from fresh state through the write primitive.
-  // A source-of-truth auth change can reconcile the default slot into an explicit account.
-  // Force that case through the locked mutation path too: it either validates a fresh snapshot
-  // and persists a unique identity, or throws without returning/writing a duplicate pool.
-  if (wasScrubbed || withDefaultSlot !== scrubbed || findDefaultAccountCollision(withDefaultSlot, providerId)) {
-    return mutateSubscriptionPool(providerId, (pool) => pool);
-  }
-  return withDefaultSlot;
-}
-
-// Seed/replace the entire pool under the lock. Production mutation goes through the specific
-// mutators below (each a thin transform over `mutateSubscriptionPool`); this whole-array replace
-// exists for test seeding and is still locked, never an unlocked write surface.
-export function writeSubscriptionPool(providerId: ManagedProviderId, next: SubscriptionCredential[]): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, () => next);
-}
-
-function resolveCredentialIndex(pool: SubscriptionCredential[], ref: string): number {
-  const needle = ref.trim().toLowerCase();
-  const numeric = Number.parseInt(needle, 10);
-  if (Number.isFinite(numeric) && String(numeric) === needle && numeric >= 1 && numeric <= pool.length) {
-    return numeric - 1;
-  }
-  return pool.findIndex((entry) => entry.label.toLowerCase() === needle);
-}
-
-// Merge an incoming upsert onto an existing same-label entry (design §1). Credential VALUE
-// fields always come from the incoming entry (that is the point of the upsert); timing/cooldown
-// state is reconciled causally so a refresh/reauth upsert built from a snapshot taken before a
-// concurrent 429 can never erase that newer cooldown. The `>=` on `lastRateLimitedAt` is
-// deliberate: reauth clears a cooldown after a successful re-login while preserving
-// `lastRateLimitedAt`, so its equal-timestamp write wins and clears -- but a 429 that landed
-// AFTER the reauth snapshot has a strictly greater `lastRateLimitedAt` and survives.
-function mergeUpsert(existing: SubscriptionCredential, incoming: SubscriptionCredential): SubscriptionCredential {
-  const cooldownFromIncoming = incoming.lastRateLimitedAt >= existing.lastRateLimitedAt;
-  const accountId = incoming.accountId ?? existing.accountId;
-  return {
-    ...incoming,
-    ...(accountId ? { accountId } : {}),
-    lastAttemptAt: Math.max(existing.lastAttemptAt, incoming.lastAttemptAt),
-    lastRateLimitedAt: cooldownFromIncoming ? incoming.lastRateLimitedAt : existing.lastRateLimitedAt,
-    rateLimitedUntil: cooldownFromIncoming ? incoming.rateLimitedUntil : existing.rateLimitedUntil,
-  };
-}
-
-export function upsertSubscription(providerId: ManagedProviderId, next: SubscriptionCredential): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    const index = pool.findIndex((entry) => entry.label.toLowerCase() === next.label.toLowerCase());
-    if (index === -1) return [...pool, next];
-    const merged = [...pool];
-    merged[index] = mergeUpsert(pool[index], next);
-    return merged;
-  });
-}
-
-// Thrown from inside the locked add transform when a label or Codex account already exists. A
-// typed error so the /provider-sub handler surfaces a precise, user-facing message while the
-// uniqueness decision itself stays atomic under the pool lock.
-export class DuplicateSubscriptionError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "DuplicateSubscriptionError";
-  }
-}
-
-// The ONE account-uniqueness gate, shared by every identity write (explicit add, explicit
-// reauth, default (re)login). Called INSIDE a `mutateSubscriptionPool` transform so it sees
-// fresh-under-lock state. `exceptLabel` is the slot being updated -- excluded from the scan so
-// a reauth/relogin of a slot into the SAME account it already holds is not a self-collision.
-// A missing `accountId` makes no dedupe claim (Anthropic has no account claim, and legacy
-// entries predate identity capture), so it is a no-op. Throws the typed error the handler
-// surfaces to the user.
-function findAccountCollision(pool: SubscriptionCredential[], accountId: string | undefined, exceptLabel: string): SubscriptionCredential | undefined {
-  if (!accountId) return undefined;
-  return pool.find((entry) => entry.label.toLowerCase() !== exceptLabel.toLowerCase() && entry.accountId === accountId);
-}
-
-function assertAccountAvailable(pool: SubscriptionCredential[], providerId: ManagedProviderId, accountId: string | undefined, exceptLabel: string): void {
-  const collision = findAccountCollision(pool, accountId, exceptLabel);
-  if (collision) {
-    throw new DuplicateSubscriptionError(
-      `This ${getProviderLabel(providerId)} account is already added as “${collision.label}” — it shares the same quota, so a second slot adds no redundancy.`,
-    );
-  }
-}
-
-function findDefaultAccountCollision(pool: SubscriptionCredential[], providerId: ManagedProviderId): SubscriptionCredential | undefined {
-  const defaultSlot = pool.find((entry) => entry.label === providerId);
-  return findAccountCollision(pool, defaultSlot?.accountId, providerId);
-}
-
-function assertDefaultAccountAvailable(pool: SubscriptionCredential[], providerId: ManagedProviderId): void {
-  const defaultSlot = pool.find((entry) => entry.label === providerId);
-  assertAccountAvailable(pool, providerId, defaultSlot?.accountId, providerId);
-}
-
-// Atomically append a NEW explicit subscription (non-default label), enforcing label AND Codex
-// account uniqueness INSIDE the pool lock (design finding 2). The long OAuth flow stays outside
-// the lock; only this final validate-then-append is serialized, so two brokers that both finish
-// OAuth for the same account cannot each slip a second label onto one quota. Account uniqueness
-// also catches a collision with the default slot, whose identity is seeded from auth.json.
-export function addSubscription(providerId: ManagedProviderId, entry: SubscriptionCredential): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    // Normalize the candidate label BEFORE the locked uniqueness check: `normalizeCredentials`
-    // trims on persist, so a raw " work " that passed an untrimmed check would land as a
-    // duplicate "work". Reject an empty/whitespace label here too -- the storage primitive
-    // stays defensive regardless of what the handler validated.
-    const label = entry.label.trim();
-    if (!label) throw new Error(`${getProviderLabel(providerId)} subscription label cannot be empty`);
-    if (pool.some((existing) => existing.label.toLowerCase() === label.toLowerCase())) {
-      throw new DuplicateSubscriptionError(`${getProviderLabel(providerId)} subscription already exists: ${label}`);
-    }
-    assertAccountAvailable(pool, providerId, entry.accountId, label);
-    return [...pool, { ...entry, label }];
-  });
-}
-
-// Identity-checked upsert for an EXPLICIT slot's reauth (label !== providerId). Same merge
-// semantics as `upsertSubscription` (append-or-`mergeUpsert`, preserving cooldown causality),
-// but gated by `assertAccountAvailable` first: reauthenticating a slot into an account already
-// held by ANOTHER slot (default or explicit) throws instead of creating a duplicate quota entry.
-// `next.label` is excluded from the uniqueness scan so a reauth into the slot's OWN account passes.
-export function upsertSubscriptionWithUniqueAccount(providerId: ManagedProviderId, next: SubscriptionCredential): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    assertAccountAvailable(pool, providerId, next.accountId, next.label);
-    const index = pool.findIndex((entry) => entry.label.toLowerCase() === next.label.toLowerCase());
-    if (index === -1) return [...pool, next];
-    const merged = [...pool];
-    merged[index] = mergeUpsert(pool[index], next);
-    return merged;
-  });
-}
-
-// The token-bearing half of a default-slot (re)login, destined for auth.json ONLY -- never the
-// pool (the default pool entry is metadata-only). `accountId` is optional (Anthropic carries none).
-export type DefaultSlotLogin = {
-  refresh: string;
-  access: string;
-  expires: number;
-  accountId?: string;
-  // The default entry's rate-limit timestamp observed before OAuth began. A newer timestamp
-  // found under the commit lock belongs to a concurrent 429 and must survive a same-account login.
-  lastRateLimitedAt: number;
-};
-
-// Persist the default slot's freshly-logged-in credential into auth.json under the auth lock.
-// Called ONLY from `commitDefaultIdentity`, while the pool lock is already held, so the effective
-// order is pool-lock -> auth-lock (the legal direction). Writes the full oauth record (tokens +
-// optional accountId); a blank/whitespace accountId is dropped.
-function persistDefaultAuthRecordSync(providerId: ManagedProviderId, login: DefaultSlotLogin): void {
-  const accountId = login.accountId?.trim() || undefined;
-  new FileAuthStorageBackend().withLock((current) => {
-    // Corrupt credential storage is never equivalent to an empty file: parsing must fail before
-    // either store changes rather than silently deleting every other provider's credential.
-    const data = current ? (JSON.parse(current) as Record<string, unknown>) : {};
-    data[providerId] = { type: "oauth", refresh: login.refresh, access: login.access, expires: login.expires, ...(accountId ? { accountId } : {}) };
-    return { result: undefined, next: `${JSON.stringify(data, null, 2)}\n` };
-  });
-}
-
-// Atomically commit a (re)login of the DEFAULT slot (design finding 2). Under the pool lock it:
-// (1) validates account-uniqueness EXCLUDING the default slot -- throwing BEFORE any auth write,
-// so a rejection never partially switches auth.json; (2) persists the credential to auth.json
-// under the nested auth lock (pool -> auth order); (3) reflects the new identity and causally
-// reconciles the cooldown on the metadata-only default pool entry (NO tokens copied -- the entry
-// stays metadata-only; scrubDefaultValue enforces this on write regardless). Seeds the default entry
-// if it is absent. The account uniqueness catches a collision with any explicit slot.
-export function commitDefaultIdentity(providerId: ManagedProviderId, login: DefaultSlotLogin): SubscriptionCredential[] {
-  const accountId = login.accountId?.trim() || undefined;
-  return mutateSubscriptionPool(providerId, (pool) => {
-    assertAccountAvailable(pool, providerId, accountId, providerId);
-    persistDefaultAuthRecordSync(providerId, login);
-    const index = pool.findIndex((entry) => entry.label === providerId);
-    const now = Date.now();
-    const existing = index === -1 ? undefined : pool[index];
-    // Cooldowns belong to an account identity. A login that actually switches accounts starts
-    // the new quota clean. For the same account, mirror mergeUpsert's causal rule: only a login
-    // whose snapshot includes the latest 429 may clear it; a strictly newer concurrent 429 wins.
-    const sameAccount = (existing?.accountId ?? undefined) === (accountId ?? undefined);
-    const loginCanClearCooldown = !existing || !sameAccount || login.lastRateLimitedAt >= existing.lastRateLimitedAt;
-    const base =
-      existing === undefined
-        ? { label: providerId, rateLimitedUntil: 0, lastAttemptAt: now, lastRateLimitedAt: 0 }
-        : {
-            ...existing,
-            rateLimitedUntil: loginCanClearCooldown ? 0 : existing.rateLimitedUntil,
-            lastAttemptAt: Math.max(existing.lastAttemptAt, now),
-          };
-    const entry: SubscriptionCredential = accountId
-      ? { ...base, accountId }
-      : (() => {
-          const { accountId: _drop, ...rest } = base;
-          return rest;
-        })();
-    const next = [...pool];
-    if (index === -1) next.push(entry);
-    else next[index] = entry;
-    return next;
-  });
-}
-
-export function removeSubscription(providerId: ManagedProviderId, ref: string): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    const index = resolveCredentialIndex(pool, ref);
-    if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-    const next = [...pool];
-    next.splice(index, 1);
-    return next;
-  });
-}
-
-export function promoteSubscription(providerId: ManagedProviderId, ref: string): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    const index = resolveCredentialIndex(pool, ref);
-    if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-    if (index === 0) return pool;
-    const next = [...pool];
-    next.unshift(next.splice(index, 1)[0]);
-    return next;
-  });
-}
-
-export function markSubscriptionAttempt(providerId: ManagedProviderId, ref: string, attemptAt = Date.now()): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    const index = resolveCredentialIndex(pool, ref);
-    if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-    const next = [...pool];
-    next[index] = { ...pool[index], lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt) };
-    return next;
-  });
-}
-
-export function markSubscriptionRateLimited(
-  providerId: ManagedProviderId,
-  ref: string,
-  retryAfterMs: number,
-  attemptAt = Date.now(),
-  rateLimitedAt = Date.now(),
-): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    const index = resolveCredentialIndex(pool, ref);
-    if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-    // A later rate-limit is authoritative until it expires: an out-of-order (stale) 429 whose
-    // basis predates the slot's newest cooldown must not reopen or shorten it.
-    if (rateLimitedAt < pool[index].lastRateLimitedAt) return undefined;
-    const next = [...pool];
-    next[index] = {
-      ...pool[index],
-      lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt),
-      lastRateLimitedAt: Math.max(pool[index].lastRateLimitedAt, rateLimitedAt),
-      rateLimitedUntil: rateLimitedAt + Math.max(0, retryAfterMs),
-    };
-    return next;
-  });
-}
-
-export function markSubscriptionSuccess(providerId: ManagedProviderId, ref: string, attemptAt = Date.now()): SubscriptionCredential[] {
-  return mutateSubscriptionPool(providerId, (pool) => {
-    const index = resolveCredentialIndex(pool, ref);
-    if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-    // A success whose attempt started before the slot's newest 429 must not clear that cooldown
-    // (the memory rule): treat the later rate-limit as authoritative until it expires.
-    if (attemptAt < pool[index].lastRateLimitedAt) return undefined;
-    const next = [...pool];
-    next[index] = { ...pool[index], lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt), rateLimitedUntil: 0 };
-    return next;
-  });
-}
-
-export function findAvailableSubscription(providerId: ManagedProviderId, now = Date.now()): SubscriptionCredential | undefined {
-  return readSubscriptionPool(providerId).find((entry) => !entry.rateLimitedUntil || entry.rateLimitedUntil <= now);
-}
-
-export function parseRetryAfterHeader(value: string | undefined, now = Date.now()): number | undefined {
-  if (!value) return undefined;
-  const trimmed = value.trim();
-  if (!trimmed) return undefined;
-  const seconds = Number(trimmed);
-  if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1000));
-  const parsed = Date.parse(trimmed);
-  return Number.isFinite(parsed) ? Math.max(0, parsed - now) : undefined;
-}
-
-function thinkingLevelOfRef(ref: string): ThinkingLevel | undefined {
-  const match = ref.trim().match(/:(thinking|off|minimal|low|medium|high|xhigh|max)$/i);
-  if (!match) return undefined;
-  const level = match[1].toLowerCase();
-  return level === "off" || level === "thinking" ? undefined : (level as ThinkingLevel);
-}
-
-function normalizeModelRef(ref: string): string {
-  return ref
-    .trim()
-    .replace(/^[^/]+\//, "")
-    .replace(/:(?:thinking|off|minimal|low|medium|high|xhigh|max)$/i, "")
-    .toLowerCase();
-}
-
-function splitModelRef(ref: string): FallbackTarget {
-  const trimmed = ref.trim();
-  const slash = trimmed.indexOf("/");
-  const providerId = slash === -1 ? OPENAI_CODEX_PROVIDER_ID : trimmed.slice(0, slash).trim();
-  if (!isManagedProvider(providerId)) {
-    throw new Error(`Unsupported fallback provider: ${providerId}`);
-  }
-  const rawModelId = slash === -1 ? trimmed : trimmed.slice(slash + 1).trim();
-  const thinkingMatch = rawModelId.match(/^(.*?)(?::(thinking|off|minimal|low|medium|high|xhigh|max))$/i);
-  return {
-    providerId,
-    modelId: thinkingMatch ? thinkingMatch[1] : rawModelId,
-    label: `${providerId}/${thinkingMatch ? thinkingMatch[1] : rawModelId}${thinkingMatch?.[2] ? `:${thinkingMatch[2].toLowerCase()}` : ""}`,
-    strength: DEFAULT_FALLBACK_STRENGTH,
-    thinkingLevel: thinkingMatch?.[2] && thinkingMatch[2].toLowerCase() !== "off" && thinkingMatch[2].toLowerCase() !== "thinking"
-      ? (thinkingMatch[2].toLowerCase() as ThinkingLevel)
-      : undefined,
-  };
-}
-
-// Layers ~/.crouter/config.json's `modelLadders` (if any) OVER crouter's
-// builtin ladder (`defaultModelLaddersConfig()`, src/types.ts — imported
-// directly: this package's canonical home is the crouter tree, so the
-// relative import always resolves, to dist/types.js at runtime), per
-// provider/strength — mirroring crouter's own
-// `mergeModelLadders` (src/core/config.ts), which is what a node's launcher
-// actually resolves models from. Without this fallback, a config-less user
-// (the common case: fresh install, no ~/.crouter/config.json) saw an EMPTY
-// ladder here while crtr itself launched them on the builtin defaults —
-// rotation could then never resolve a strength tier or a cross-provider
-// fallback for a model it was already running. Always returns a fully
-// populated ladder for both providers; a config.json override only replaces
-// the specific strengths it sets.
-function readModelLadders(): ModelLaddersConfig {
-  const config = readJsonFile<{ modelLadders?: Partial<Record<LadderProviderId, Partial<ModelLadderConfig>>> }>(CROUTER_CONFIG_FILE);
-  const overrides = config?.modelLadders;
-  const builtin = defaultModelLaddersConfig();
-  const result: ModelLaddersConfig = {};
-  for (const provider of ["anthropic", "openai"] as const) {
-    const normalized: ModelLadderConfig = { ...builtin[provider] };
-    const override = overrides?.[provider];
-    if (override) {
-      for (const strength of ["ultra", "strong", "medium", "light"] as const) {
-        const value = typeof override[strength] === "string" ? override[strength]?.trim() : "";
-        if (value) normalized[strength] = value;
-      }
-    }
-    result[provider] = normalized;
-  }
-  return result;
-}
-
-function findStrengthForModelId(
-  providerId: ManagedProviderId,
-  modelId: string | undefined,
-  defaultStrength: ModelStrength,
-  ladders = readModelLadders(),
-  currentThinkingLevel?: string,
-): ModelStrength | undefined {
-  const source = ladders?.[PROVIDERS[providerId].ladderProviderId];
-  const bareId = modelId ? normalizeModelRef(modelId) : undefined;
-  if (!source || !bareId) return undefined;
-  const matches: ModelStrength[] = [];
-  for (const strength of ["ultra", "strong", "medium", "light"] as const) {
-    const ref = source[strength];
-    if (ref && normalizeModelRef(ref) === bareId) matches.push(strength);
-  }
-  if (matches.length === 0) return undefined;
-  // Rungs that share a bare model id (e.g. gpt-5.6-sol:max vs gpt-5.6-sol:high) are
-  // disambiguated by the live reasoning level so an ultra run doesn't collapse to strong.
-  if (matches.length > 1 && currentThinkingLevel) {
-    const exact = matches.find((strength) => thinkingLevelOfRef(source[strength]!) === currentThinkingLevel);
-    if (exact) return exact;
-  }
-  return matches.includes(defaultStrength) ? defaultStrength : matches[0];
-}
-
-export function readRotationConfig(): RotationConfig {
-  const raw = readJsonFile<RotationConfig>(ROTATION_CONFIG_FILE) ?? {};
-  const preferredModel =
-    raw.preferredModel && isManagedProvider(raw.preferredModel.providerId) && typeof raw.preferredModel.modelId === "string"
-      ? { providerId: raw.preferredModel.providerId, modelId: raw.preferredModel.modelId.trim() }
-      : undefined;
-  return {
-    defaultFallbackStrength: normalizeStrength(raw.defaultFallbackStrength) ?? DEFAULT_FALLBACK_STRENGTH,
-    revertWhenAvailable: raw.revertWhenAvailable ?? true,
-    preferredModel,
-  };
-}
-
-export function writeRotationConfig(next: RotationConfigUpdate): RotationConfig {
-  const current = readRotationConfig();
-  const merged: RotationConfig = {
-    defaultFallbackStrength: normalizeStrength(next.defaultFallbackStrength) ?? current.defaultFallbackStrength ?? DEFAULT_FALLBACK_STRENGTH,
-    revertWhenAvailable: next.revertWhenAvailable ?? current.revertWhenAvailable ?? true,
-    preferredModel: Object.prototype.hasOwnProperty.call(next, "preferredModel")
-      ? next.preferredModel || undefined
-      : current.preferredModel,
-  };
-  writeJsonFile(ROTATION_CONFIG_FILE, merged);
-  return merged;
-}
-
-export function clearPreferredModel(): RotationConfig {
-  return writeRotationConfig({ preferredModel: null });
-}
-
-export function rememberPreferredModel(model: ModelRef): RotationConfig {
-  return writeRotationConfig({ preferredModel: model });
-}
-
-// `readModelLadders()` always fills both providers from the builtin defaults, so this
-// only returns undefined (never throws) in the defensive case where a rung is still
-// genuinely missing; callers must treat that as a graceful "no fallback available" case
-// rather than a config error to surface mid-turn.
-export function resolveFallbackTarget(
-  currentProviderId: ManagedProviderId,
-  currentModelId?: string,
-  config = readRotationConfig(),
-  currentThinkingLevel?: string,
-): FallbackTarget | undefined {
-  const ladders = readModelLadders();
-  const defaultStrength = config.defaultFallbackStrength ?? DEFAULT_FALLBACK_STRENGTH;
-  const sourceStrength = findStrengthForModelId(currentProviderId, currentModelId, defaultStrength, ladders, currentThinkingLevel);
-  const strength = sourceStrength ?? defaultStrength;
-  const targetProvider = currentProviderId === ANTHROPIC_PROVIDER_ID ? OPENAI_CODEX_PROVIDER_ID : ANTHROPIC_PROVIDER_ID;
-  const targetLadder = ladders?.[PROVIDERS[targetProvider].ladderProviderId];
-  const candidates = strength === defaultStrength ? [strength] : [strength, defaultStrength];
-  const fallbackRef = candidates.map((candidate) => targetLadder?.[candidate]).find((ref): ref is string => typeof ref === "string" && ref.trim().length > 0);
-  if (!fallbackRef) {
-    return undefined;
-  }
-  const parsed = splitModelRef(fallbackRef);
-  const resolvedStrength = candidates.find((candidate) => targetLadder?.[candidate] === fallbackRef) ?? strength;
-  return { ...parsed, strength: resolvedStrength };
-}
-
-export function shouldRestorePreferredModel(config = readRotationConfig(), now = Date.now()): boolean {
-  if (!config.revertWhenAvailable || !config.preferredModel) return false;
-  return Boolean(findAvailableSubscription(config.preferredModel.providerId, now));
-}
-
-export async function restorePreferredModelIfPossible(
-  piApi: ExtensionAPI,
-  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
-): Promise<boolean> {
-  const config = readRotationConfig();
-  if (!shouldRestorePreferredModel(config, Date.now())) return false;
-  const preferred = config.preferredModel;
-  if (!preferred) return false;
-  const current = getCurrentModelRef(ctx.model);
-  if (current?.providerId === preferred.providerId && current.modelId === preferred.modelId) {
-    clearPreferredModel();
-    return true;
-  }
-  const model = ctx.modelRegistry.find(preferred.providerId, preferred.modelId);
-  if (!model) return false;
-  const switched = await piApi.setModel(model);
-  if (switched) clearPreferredModel();
-  return switched;
-}
-
-export async function switchToFallbackIfPossible(
-  piApi: ExtensionAPI,
-  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
-  preferredModel = getCurrentModelRef(ctx.model),
-): Promise<FallbackTarget | undefined> {
-  if (!preferredModel) return undefined;
-  rememberPreferredModel(preferredModel);
-  const currentThinkingLevel = piApi.getThinkingLevel?.();
-  const target = resolveFallbackTarget(preferredModel.providerId, preferredModel.modelId, readRotationConfig(), currentThinkingLevel);
-  if (!target) return undefined;
-  const current = getCurrentModelRef(ctx.model);
-  const model = ctx.modelRegistry.find(target.providerId, target.modelId);
-  if (!model) return undefined;
-  if (current?.providerId !== target.providerId || current.modelId !== target.modelId) {
-    const switched = await piApi.setModel(model);
-    if (!switched) return undefined;
-  }
-  if (target.thinkingLevel) piApi.setThinkingLevel(target.thinkingLevel);
-  return target;
-}
-
-export function formatStatusLine(providerId: ManagedProviderId, now = Date.now()): string {
-  const pool = readSubscriptionPool(providerId);
-  const ready = pool.filter((entry) => !entry.rateLimitedUntil || entry.rateLimitedUntil <= now);
-  const label = getProviderLabel(providerId);
-  if (ready.length === 0) {
-    const fallback = resolveFallbackTarget(providerId, undefined, readRotationConfig());
-    return fallback ? `${label} pool exhausted -> ${fallback.label}` : `${label} pool exhausted (no fallback configured)`;
-  }
-  return `${label} ${ready[0]?.label ?? providerId} (${ready.length}/${pool.length} ready)`;
-}
+// Provider pool state belongs to crouter core so every human surface and the rotation runtime share one invariant-preserving implementation.
+export * from "../../../core/subscription-state.js";