@crouton-kit/crouter 0.3.78 → 0.3.80

package/dist/core/subscription-state.js

@@ -0,0 +1,762 @@
+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 { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
+export const ANTHROPIC_PROVIDER_ID = "anthropic";
+export const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+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 = "strong";
+const PROVIDERS = {
+    [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(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        if (!raw)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeJsonFile(path, value, mode) {
+    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) {
+    return value === "ultra" || value === "strong" || value === "medium" || value === "light" ? value : undefined;
+}
+function normalizeTiming(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : 0;
+}
+function normalizeCredential(value) {
+    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) {
+    if (!Array.isArray(values))
+        return [];
+    return values.map((entry) => normalizeCredential(entry)).filter((entry) => Boolean(entry));
+}
+function getCurrentModelRef(model) {
+    return isManagedProvider(model?.provider) ? { providerId: model.provider, modelId: model.id } : undefined;
+}
+function readAuthCredential(providerId) {
+    return new FileAuthStorageBackend().withLock((current) => {
+        if (!current)
+            return { result: undefined };
+        const data = JSON.parse(current);
+        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, pool) {
+    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, pool) {
+    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) {
+    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) {
+    return PROVIDERS[providerId].ladderProviderId;
+}
+export function getProviderLabel(providerId) {
+    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, fn) {
+    const poolFile = PROVIDERS[providerId].poolFile;
+    const backend = new FileAuthStorageBackend(poolFile);
+    return backend.withLock((current) => {
+        let parsed;
+        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) {
+    const poolFile = PROVIDERS[providerId].poolFile;
+    const raw = normalizeCredentials(readJsonFile(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, next) {
+    return mutateSubscriptionPool(providerId, () => next);
+}
+function resolveCredentialIndex(pool, ref) {
+    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, incoming) {
+    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, next) {
+    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) {
+        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, accountId, exceptLabel) {
+    if (!accountId)
+        return undefined;
+    return pool.find((entry) => entry.label.toLowerCase() !== exceptLabel.toLowerCase() && entry.accountId === accountId);
+}
+function assertAccountAvailable(pool, providerId, accountId, exceptLabel) {
+    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, providerId) {
+    const defaultSlot = pool.find((entry) => entry.label === providerId);
+    return findAccountCollision(pool, defaultSlot?.accountId, providerId);
+}
+function assertDefaultAccountAvailable(pool, providerId) {
+    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, entry) {
+    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, next) {
+    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;
+    });
+}
+// 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, login) {
+    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) : {};
+        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, login) {
+    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 = 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 renameSubscription(providerId, ref, nextLabel) {
+    return mutateSubscriptionPool(providerId, (pool) => {
+        const index = resolveCredentialIndex(pool, ref);
+        if (index === -1)
+            throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
+        if (pool[index].label === providerId)
+            throw new Error(`The Default account label cannot be renamed`);
+        const label = nextLabel.trim();
+        if (!label)
+            throw new Error(`${getProviderLabel(providerId)} subscription label cannot be empty`);
+        if (pool.some((entry, entryIndex) => entryIndex !== index && entry.label.toLowerCase() === label.toLowerCase())) {
+            throw new DuplicateSubscriptionError(`${getProviderLabel(providerId)} subscription already exists: ${label}`);
+        }
+        const next = [...pool];
+        next[index] = { ...next[index], label };
+        return next;
+    });
+}
+// The default pool slot is only metadata, but its matching auth.json OAuth record is
+// live state. Remove both while holding the pool lock (then the auth lock), matching
+// commitDefaultIdentity's lock order so a deleted default cannot be immediately seeded back.
+export function removeManagedAccount(providerId, ref) {
+    return mutateSubscriptionPool(providerId, (pool) => {
+        const index = resolveCredentialIndex(pool, ref);
+        if (index === -1)
+            throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
+        if (pool[index].label === providerId) {
+            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) : {};
+                delete data[providerId];
+                return { result: undefined, next: `${JSON.stringify(data, null, 2)}\n` };
+            });
+        }
+        const next = [...pool];
+        next.splice(index, 1);
+        return next;
+    });
+}
+// Coordinated persistence for a freshly-acquired managed OAuth credential — the ONE place human
+// UI (the `crtr sys setup` Providers panel and `crtr surface attach`'s /login) turns a login into
+// stored state, so the coordinated-account invariants hold from every entrypoint. The default slot
+// (label === providerId) commits through commitDefaultIdentity (auth.json + pool metadata under one
+// lock, account-uniqueness enforced BEFORE any auth write); any explicit label add/upserts into the
+// pool with the same account-uniqueness gate. UI must NEVER persist a managed login via a raw
+// AuthStorage.login/set — that path skips uniqueness and leaves the pool identity unseeded.
+// `defaultLastRateLimitedAt` is the default slot's rate-limit timestamp observed BEFORE OAuth
+// began: commitDefaultIdentity's causal cooldown rule needs the pre-login snapshot so a strictly
+// newer concurrent 429 survives a same-account re-login (see DefaultSlotLogin).
+export function commitManagedLogin(providerId, label, credential) {
+    const accountId = credential.accountId?.trim() || undefined;
+    if (label === providerId) {
+        return commitDefaultIdentity(providerId, {
+            refresh: credential.refresh,
+            access: credential.access,
+            expires: credential.expires,
+            ...(accountId ? { accountId } : {}),
+            lastRateLimitedAt: credential.defaultLastRateLimitedAt,
+        });
+    }
+    const existing = readSubscriptionPool(providerId).find((entry) => entry.label.toLowerCase() === label.toLowerCase());
+    const next = {
+        label,
+        refresh: credential.refresh,
+        access: credential.access,
+        expires: credential.expires,
+        ...(accountId ? { accountId } : {}),
+        rateLimitedUntil: 0,
+        lastAttemptAt: Date.now(),
+        lastRateLimitedAt: existing?.lastRateLimitedAt ?? 0,
+    };
+    return existing ? upsertSubscriptionWithUniqueAccount(providerId, next) : addSubscription(providerId, next);
+}
+// Coordinated removal for the human UI. Removes a single account when `label` is given; the ENTIRE
+// provider (every pool account plus its auth.json default record) when `label` is omitted — always
+// through removeManagedAccount so pool and auth.json are torn down together. UI must NEVER reach for
+// a raw AuthStorage.logout() on a managed provider: that strips only auth.json and orphans the pool,
+// recreating the split-ownership bug this coordination exists to eliminate.
+export function removeManagedProvider(providerId, label) {
+    const refs = label !== undefined ? [label] : readSubscriptionPool(providerId).map((account) => account.label);
+    let pool = readSubscriptionPool(providerId);
+    for (const ref of refs)
+        pool = removeManagedAccount(providerId, ref);
+    return pool;
+}
+export function removeSubscription(providerId, ref) {
+    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, ref) {
+    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, ref, attemptAt = Date.now()) {
+    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, ref, retryAfterMs, attemptAt = Date.now(), rateLimitedAt = Date.now()) {
+    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, ref, attemptAt = Date.now()) {
+    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, now = Date.now()) {
+    return readSubscriptionPool(providerId).find((entry) => !entry.rateLimitedUntil || entry.rateLimitedUntil <= now);
+}
+export function parseRetryAfterHeader(value, now = Date.now()) {
+    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) {
+    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;
+}
+function normalizeModelRef(ref) {
+    return ref
+        .trim()
+        .replace(/^[^/]+\//, "")
+        .replace(/:(?:thinking|off|minimal|low|medium|high|xhigh|max)$/i, "")
+        .toLowerCase();
+}
+function splitModelRef(ref) {
+    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()
+            : 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() {
+    const config = readJsonFile(CROUTER_CONFIG_FILE);
+    const overrides = config?.modelLadders;
+    const builtin = defaultModelLaddersConfig();
+    const result = {};
+    for (const provider of ["anthropic", "openai"]) {
+        const normalized = { ...builtin[provider] };
+        const override = overrides?.[provider];
+        if (override) {
+            for (const strength of ["ultra", "strong", "medium", "light"]) {
+                const value = typeof override[strength] === "string" ? override[strength]?.trim() : "";
+                if (value)
+                    normalized[strength] = value;
+            }
+        }
+        result[provider] = normalized;
+    }
+    return result;
+}
+function findStrengthForModelId(providerId, modelId, defaultStrength, ladders = readModelLadders(), currentThinkingLevel) {
+    const source = ladders?.[PROVIDERS[providerId].ladderProviderId];
+    const bareId = modelId ? normalizeModelRef(modelId) : undefined;
+    if (!source || !bareId)
+        return undefined;
+    const matches = [];
+    for (const strength of ["ultra", "strong", "medium", "light"]) {
+        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() {
+    const raw = readJsonFile(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) {
+    const current = readRotationConfig();
+    const merged = {
+        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() {
+    return writeRotationConfig({ preferredModel: null });
+}
+export function rememberPreferredModel(model) {
+    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, currentModelId, config = readRotationConfig(), currentThinkingLevel) {
+    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) => 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()) {
+    if (!config.revertWhenAvailable || !config.preferredModel)
+        return false;
+    return Boolean(findAvailableSubscription(config.preferredModel.providerId, now));
+}
+export async function restorePreferredModelIfPossible(piApi, ctx) {
+    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, ctx, preferredModel = getCurrentModelRef(ctx.model)) {
+    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, now = Date.now()) {
+    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)`;
+}