@north-light/crouter 0.3.154

package/dist/core/subscription-state.js

@@ -0,0 +1,918 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { defaultModelLaddersConfig } from "../types.js";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { LockedJsonFile } from "./locked-file.js";
+export const ANTHROPIC_PROVIDER_ID = "anthropic";
+export const OPENAI_CODEX_PROVIDER_ID = "openai-codex";
+export const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Select the first viable model from an explicitly ordered set. Callers own ordering
+ * (requested model first, then their configured fallback order) and side effects;
+ * this policy owns the shared viability rules so launch and rotation cannot diverge.
+ *
+ * `pinnedToFirst` marks the FIRST candidate as an explicit provider pin: the caller
+ * demanded that exact provider, so an unregistered or unauthenticated first candidate
+ * forbids cross-provider fallback (selection stops, reporting only that one rejection).
+ * A merely COOLING pin is transient, so fallback to a viable alternative is still
+ * allowed. When false, every candidate is considered in order.
+ */
+export function resolveProviderCandidates(candidates, now = Date.now(), options = {}) {
+    const viable = [];
+    const rejected = [];
+    const pinnedToFirst = options.pinnedToFirst === true;
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        let reason;
+        if (!candidate.registered)
+            reason = "unregistered";
+        else if (candidate.automaticFallback === false)
+            reason = "non-managed-fallback";
+        else if (!candidate.authenticated)
+            reason = "unauthenticated";
+        else if ((candidate.coolingUntil ?? 0) > now)
+            reason = "cooling";
+        if (reason === undefined) {
+            viable.push(candidate);
+            continue;
+        }
+        rejected.push({ candidate, reason });
+        // A hard provider pin on the requested (first) candidate forbids alternatives
+        // — unless the pin is merely cooling, a transient managed cooldown that still
+        // prefers a viable fallback over stalling.
+        if (pinnedToFirst && i === 0 && reason !== "cooling")
+            break;
+    }
+    return { candidates: viable, rejected };
+}
+// pi's agent dir, resolved PER ACCESS. Deliberately mirrors pi's own `getAgentDir()`
+// (PI_CODING_AGENT_DIR, tilde-expanded, else ~/.pi/agent) rather than importing it: a
+// value import from @earendil-works/pi-coding-agent would drag the whole pi SDK into
+// every CLI leaf that touches subscriptions. Resolving per access (never once at module
+// load) is what makes PI_CODING_AGENT_DIR and a per-process HOME actually take effect.
+function agentDir() {
+    const configured = process.env["PI_CODING_AGENT_DIR"];
+    if (configured) {
+        return configured === "~" || configured.startsWith("~/") ? join(homedir(), configured.slice(1)) : configured;
+    }
+    return join(homedir(), ".pi", "agent");
+}
+function rotationConfigFile() {
+    return join(agentDir(), "provider-rotation.json");
+}
+function crouterConfigFile() {
+    return join(homedir(), ".crouter", "config.json");
+}
+const DEFAULT_FALLBACK_STRENGTH = "strong";
+const PROVIDERS = {
+    [ANTHROPIC_PROVIDER_ID]: {
+        label: "Claude",
+        ladderProviderId: "anthropic",
+        poolFileName: "anthropic-subscriptions.json",
+    },
+    [OPENAI_CODEX_PROVIDER_ID]: {
+        label: "OpenAI Codex",
+        ladderProviderId: "openai",
+        poolFileName: "openai-codex-subscriptions.json",
+    },
+};
+/** The pool file backing one managed provider's accounts, in the CURRENT agent dir. */
+function poolFileFor(providerId) {
+    return join(agentDir(), PROVIDERS[providerId].poolFileName);
+}
+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;
+    }
+}
+/**
+ * The pool file is read strictly: an absent or empty file represents no accounts, while a
+ * present file that cannot be read or parsed is an operational error. Treating the latter as
+ * an empty pool would incorrectly report an authenticated provider as unconfigured.
+ */
+function readPoolFile(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        if (!raw)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Subscription pool ${path} is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * The pool contents a locked transaction is about to act on. An empty file is genuinely no
+ * accounts; a non-empty file that will not parse is CORRUPT, and treating it as an empty pool
+ * is what let `modifyElectedSubscription` answer pi's refresh with `undefined` -- the exact
+ * shape pi reports as `Provider is not configured: <id>`, a fatal fault no agent can clear
+ * from inside its own turn. Raise instead, so the failure names itself.
+ */
+function parsePoolUnderLock(path, current) {
+    if (!current || current.trim() === "")
+        return undefined;
+    try {
+        return JSON.parse(current);
+    }
+    catch (error) {
+        throw new Error(`Subscription pool ${path} is corrupt: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+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;
+}
+// A pool row IS a credential: an account whose OAuth token pair is missing cannot service a
+// turn and cannot be refreshed, so it is not a lesser row, it is not a row at all. Normalization
+// drops it here, which is what lets every consumer treat pool occupancy as authentication.
+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() : "";
+    if (!refresh || !access)
+        return undefined;
+    const accountId = typeof value.accountId === "string" ? value.accountId.trim() : "";
+    const expires = Number(value.expires);
+    const rateLimitedUntil = Number(value.rateLimitedUntil);
+    return {
+        label,
+        refresh,
+        access,
+        expires: Number.isFinite(expires) ? expires : 0,
+        ...(accountId ? { accountId } : {}),
+        rateLimitedUntil: Number.isFinite(rateLimitedUntil) ? rateLimitedUntil : 0,
+        ...(value.authFailure === "invalid_grant" ? { authFailure: "invalid_grant" } : {}),
+        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));
+}
+// Announced only where the drop is about to be PERSISTED. Normalization also runs on the
+// lock-free read path, which discards nothing from storage, so tracing inside it reports a
+// loss that has not happened and repeats on every read. The account-set log compares
+// normalized state on both sides and so can never see this row; say it here instead.
+function traceDroppedRows(providerId, stored, normalized) {
+    if (!Array.isArray(stored) || stored.length === normalized.length)
+        return;
+    process.stderr.write(`[subscription-pool] ${getProviderLabel(providerId)}: dropping ${stored.length - normalized.length} stored row(s) with no label or no token pair\n`);
+}
+function getCurrentModelRef(model) {
+    return isManagedProvider(model?.provider) ? { providerId: model.provider, modelId: model.id } : undefined;
+}
+// A refreshed/modified token set is only storable when it carries BOTH halves and a usable
+// expiry. Persisting a partial one is silently destructive: `JSON.stringify` drops the missing
+// key, and `normalizeCredential` (which requires refresh AND access together) then discards the
+// whole row on the very next read — silently logging that account out until the user logs in
+// again, at which point the next refresh repeats it. Providers do not all validate their own refresh response
+// (pi's Anthropic flow forwards `data.refresh_token` verbatim, absent or not), so the storage
+// layer refuses the write instead: the previous credential stays intact and the caller sees a
+// real error it can classify (cooldown -> reauth -> fallback).
+function assertStorableTokens(providerId, label, value) {
+    const refresh = typeof value.refresh === "string" ? value.refresh.trim() : "";
+    const access = typeof value.access === "string" ? value.access.trim() : "";
+    const expires = Number(value.expires);
+    if (!refresh || !access || !Number.isFinite(expires)) {
+        const missing = [!refresh ? "refresh token" : undefined, !access ? "access token" : undefined, Number.isFinite(expires) ? undefined : "expiry"]
+            .filter((part) => part !== undefined)
+            .join(", ");
+        throw new Error(`${getProviderLabel(providerId)} subscription "${label}" returned an incomplete credential (missing ${missing}); the stored credential was left unchanged.`);
+    }
+    return { refresh, access, expires };
+}
+// Every candidate row must survive normalization before it can reach disk. Existing on-disk
+// rows remain tolerant of malformed historical data during reads, but a new transform cannot
+// acknowledge a row that persistence would silently discard.
+function assertCandidateRowsStorable(providerId, candidate) {
+    for (const entry of candidate) {
+        if (normalizeCredential(entry) !== undefined)
+            continue;
+        const label = typeof entry.label === "string" && entry.label.trim() ? ` "${entry.label.trim()}"` : "";
+        throw new Error(`Refusing to persist incomplete ${getProviderLabel(providerId)} subscription${label}; pool rows require a label and both OAuth tokens.`);
+    }
+}
+// The ONE door every write to a pool file goes through. Both pool invariants -- one account
+// identity per pool, and every candidate row carrying a storable credential -- are properties
+// of the FILE, not of whichever code path happens to be writing, so they are asserted here
+// against the state this write replaces, under the caller's already-held lock. `writeJsonFile`
+// is reached for the pool NOWHERE ELSE: that makes the invariants unbypassable.
+function persistPool(providerId, poolFile, base, candidate) {
+    assertCandidateRowsStorable(providerId, candidate);
+    const next = normalizeCredentials(candidate);
+    logCredentialSetChange(providerId, base, next);
+    writeJsonFile(poolFile, next, 0o600);
+    return next;
+}
+// Accounts vanishing from a pool is the failure users actually feel ("I keep having to log in
+// again"), and a shrinking file says nothing about which process shrank it. Every write that
+// CHANGES the set of accounts announces itself on stderr -- which lands in the broker log next to the rotation lines -- with the pid
+// and argv of whoever did it. Unchanged sets (the constant cooldown/timestamp bookkeeping) stay
+// silent, so this is a rare, high-signal line, not a log firehose.
+function logCredentialSetChange(providerId, base, next) {
+    const labels = (pool) => pool.map((entry) => entry.label).sort();
+    const before = labels(base);
+    const after = labels(next);
+    if (before.length === after.length && before.every((label, index) => label === after[index]))
+        return;
+    const who = `pid ${process.pid} ${process.argv.slice(1).join(" ")}`;
+    process.stderr.write(`[subscription-pool] ${getProviderLabel(providerId)} accounts changed: [${before.join(", ")}] -> [${after.join(", ")}] (${who})\n`);
+}
+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. It acquires a
+// cross-process lock on the pool file, re-reads + normalizes the pool under that lock, awaits
+// the caller's transform, and persists atomically through `persistPool` before releasing.
+// Every pool mutation goes through this door, so causal cooldown guards compare against
+// fresh-under-lock state and all pool invariants share one write path.
+//
+// `fn` returning `undefined` means "no change, skip the write" (used by timestamp guards and
+// refreshes that find a fresh credential). `withLockAsync` seeds a missing file with `{}`;
+// `normalizeCredentials` coerces that first-lock seed to an empty pool. Pool writes happen via
+// the callback's atomic tmp+rename and return no backend `next`, so lock-free readers always see
+// a whole snapshot. Throws (rather than proceeding unlocked) if lock acquisition is exhausted.
+export async function mutateSubscriptionPool(providerId, fn) {
+    const poolFile = poolFileFor(providerId);
+    return new LockedJsonFile(poolFile).withLockAsync(async (current, assertLockHeld) => {
+        const parsed = parsePoolUnderLock(poolFile, current);
+        const base = normalizeCredentials(parsed);
+        const transformed = await fn(base, assertLockHeld);
+        if (transformed !== undefined)
+            traceDroppedRows(providerId, parsed, base);
+        if (transformed === undefined)
+            return { result: base };
+        return { result: persistPool(providerId, poolFile, base, transformed) };
+    });
+}
+// The token exchange for ONE account, serialized across processes on the pool file's own lock.
+// A refresh token is single-use: without this, two brokers holding the same expired credential
+// both call the provider, and the loser gets a genuine `invalid_grant` that bricks its turn. The
+// whole read -> check-expiry -> exchange -> write transaction therefore happens under the lock,
+// so a second refresher that arrives after a winner observes the rotated value and never makes
+// its own (now doomed) call. Every account stores its value in this shared pool.
+//
+// The exchange is awaited while the shared pool transaction holds the lock.
+export async function refreshSubscriptionCredential(providerId, label, exchange) {
+    const committed = await mutateSubscriptionPool(providerId, async (pool, assertLockHeld) => {
+        const index = pool.findIndex((entry) => entry.label === label);
+        if (index === -1)
+            throw new Error(`${getProviderLabel(providerId)} subscription "${label}" no longer exists`);
+        const entry = pool[index];
+        if (entry.expires > Date.now())
+            return undefined;
+        const refreshed = assertStorableTokens(providerId, label, await exchange(entry.refresh));
+        const next = [...pool];
+        next[index] = { ...entry, refresh: refreshed.refresh, access: refreshed.access, expires: refreshed.expires };
+        assertLockHeld();
+        return next;
+    });
+    const result = committed.find((entry) => entry.label === label);
+    if (result === undefined)
+        throw new Error(`${getProviderLabel(providerId)} subscription "${label}" did not survive the write`);
+    return result;
+}
+// The serialized read-modify-write pi's `CredentialStore.modify` contract demands. Pi's OAuth
+// refresh runs inside `apply`, and refresh tokens are single-use, so election, exchange, and
+// persistence remain under one pool lock. A credential whose provider rejects its refresh token
+// is marked auth-failed before the next eligible pool account is tried; this lets pi's eager
+// credential resolution recover through the same account pool as turn-time rotation. If every
+// candidate fails, those auth-failure marks are persisted before the final error is rethrown.
+//
+// `apply` returning `undefined` means "no token change". Only the token triple is replaced on a
+// successful refresh; account identity and rotation bookkeeping remain attached to their row.
+export function isInvalidRefreshTokenError(error) {
+    const value = error;
+    const typedStatus = typeof value?.status === "number" ? value.status : undefined;
+    const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : ""]
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join(" ");
+    const messageStatusMatch = message.match(/\bstatus[=:]\s*(\d+)/i);
+    const status = typedStatus ?? (messageStatusMatch ? Number(messageStatusMatch[1]) : Number.NaN);
+    return status === 400 && /invalid_grant|refresh token .*invalid|refresh token .*not found/i.test(message);
+}
+export async function modifyElectedSubscription(providerId, elect, apply) {
+    let label;
+    let pendingError;
+    const committed = await mutateSubscriptionPool(providerId, async (pool, assertLockHeld) => {
+        const next = [...pool];
+        const attempted = new Set();
+        let changed = false;
+        while (attempted.size < next.length) {
+            const elected = elect(next.filter((entry) => !attempted.has(entry.label)));
+            if (elected === undefined)
+                break;
+            const index = next.findIndex((entry) => entry.label === elected.label);
+            if (index === -1)
+                break;
+            attempted.add(next[index].label);
+            let applied;
+            try {
+                applied = await apply(next[index]);
+            }
+            catch (error) {
+                if (!isInvalidRefreshTokenError(error)) {
+                    pendingError = error;
+                    break;
+                }
+                const attemptAt = Date.now();
+                next[index] = {
+                    ...next[index],
+                    authFailure: "invalid_grant",
+                    lastAttemptAt: Math.max(next[index].lastAttemptAt, attemptAt),
+                    rateLimitedUntil: Math.max(next[index].rateLimitedUntil, attemptAt + INVALID_REFRESH_TOKEN_BACKOFF_MS),
+                };
+                changed = true;
+                pendingError = error;
+                continue;
+            }
+            label = next[index].label;
+            pendingError = undefined;
+            if (applied !== undefined) {
+                const stored = assertStorableTokens(providerId, next[index].label, applied);
+                next[index] = { ...next[index], refresh: stored.refresh, access: stored.access, expires: stored.expires };
+                changed = true;
+            }
+            break;
+        }
+        if (!changed)
+            return undefined;
+        assertLockHeld();
+        return next;
+    });
+    if (pendingError !== undefined)
+        throw pendingError;
+    return label === undefined ? undefined : committed.find((entry) => entry.label === label);
+}
+export function readSubscriptionPool(providerId) {
+    // Reads are lock-free: whole-file tmp+rename persistence means a reader always sees a complete
+    // snapshot.
+    return normalizeCredentials(readPoolFile(poolFileFor(providerId)));
+}
+// 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 async 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 async 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 identity an account dedupes on. Codex logins carry the provider's own account claim, which
+// is a true account identity. Anthropic's OAuth token carries none, so the CREDENTIAL stands in
+// for one -- a one-way digest of the refresh token, never logged and never persisted (derived on
+// demand, compared in memory). That catches the same stored credential landing under a second
+// label; it does NOT catch two independent logins to one Anthropic account, which mint different
+// refresh tokens. Tightening that needs an account claim Anthropic does not currently supply.
+function accountIdentity(entry) {
+    const accountId = entry.accountId?.trim();
+    if (accountId)
+        return accountId;
+    const refresh = entry.refresh?.trim();
+    return refresh ? `refresh:${createHash("sha256").update(refresh).digest("hex")}` : undefined;
+}
+// The one account-uniqueness gate, shared by every identity write. 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.
+// An undefined `identity` makes no dedupe claim, so it is a no-op. Throws the typed error the
+// handler surfaces to the user.
+function findAccountCollision(pool, identity, exceptLabel) {
+    if (!identity)
+        return undefined;
+    return pool.find((entry) => entry.label.toLowerCase() !== exceptLabel.toLowerCase() && accountIdentity(entry) === identity);
+}
+function assertAccountAvailable(pool, providerId, identity, exceptLabel) {
+    const collision = findAccountCollision(pool, identity, 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.`);
+    }
+}
+// Atomically append a new subscription, enforcing label and account uniqueness inside the pool
+// lock. 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 add two labels.
+export async 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, accountIdentity(entry), label);
+        return [...pool, { ...entry, label }];
+    });
+}
+// Identity-checked upsert for reauthentication. Same merge semantics as `upsertSubscription`
+// (append-or-`mergeUpsert`, preserving cooldown causality), but gated by `assertAccountAvailable`
+// first: reauthenticating a row into an account held by another row throws instead of creating a
+// duplicate quota entry. `next.label` is excluded so reauth into its own row passes.
+export async function upsertSubscriptionWithUniqueAccount(providerId, next) {
+    return mutateSubscriptionPool(providerId, (pool) => {
+        assertAccountAvailable(pool, providerId, accountIdentity(next), next.label);
+        const index = pool.findIndex((entry) => entry.label.toLowerCase() === next.label.toLowerCase());
+        if (index === -1)
+            return [...pool, next];
+        const merged = [...pool];
+        const value = mergeUpsert(pool[index], next);
+        // A reauthentication without a stable identity must not attach the old account's identity to
+        // newly issued tokens. Refreshes use `modifyElectedSubscription`, which preserves identity.
+        if (next.accountId === undefined) {
+            const { accountId: _accountId, ...withoutAccountId } = value;
+            merged[index] = withoutAccountId;
+        }
+        else {
+            merged[index] = value;
+        }
+        return merged;
+    });
+}
+export async 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}`);
+        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;
+    });
+}
+// Remove one account under the pool lock. The pool is the only home a managed credential has.
+export async function removeManagedAccount(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;
+    });
+}
+/** Fetch Anthropic's stable OAuth account identity without making login depend on it. */
+export async function enrichManagedLoginIdentity(providerId, credential) {
+    const supplied = credential.accountId?.trim();
+    if (providerId !== ANTHROPIC_PROVIDER_ID)
+        return supplied ? { accountId: supplied } : {};
+    try {
+        const response = await fetch("https://api.anthropic.com/api/oauth/profile", {
+            headers: { Authorization: `Bearer ${credential.access}`, Accept: "application/json" },
+            signal: AbortSignal.timeout(3_000),
+        });
+        if (!response.ok)
+            return supplied ? { accountId: supplied } : {};
+        const body = await response.json();
+        const accountId = typeof body.account?.uuid === "string" && body.account.uuid.trim() ? body.account.uuid.trim() : undefined;
+        const email = typeof body.account?.email === "string" && body.account.email.trim() ? body.account.email.trim() : undefined;
+        return { ...(accountId ? { accountId } : {}), ...(email ? { email } : {}) };
+    }
+    catch {
+        return supplied ? { accountId: supplied } : {};
+    }
+}
+function nextAutomaticLabel(pool, email, fallback) {
+    const base = email || fallback?.trim() || `Account ${pool.length + 1}`;
+    const used = new Set(pool.map((entry) => entry.label.toLowerCase()));
+    if (!used.has(base.toLowerCase()))
+        return base;
+    for (let index = 2;; index++) {
+        const candidate = `${base} (${index})`;
+        if (!used.has(candidate.toLowerCase()))
+            return candidate;
+    }
+}
+// Coordinated persistence for a freshly acquired managed OAuth credential. Every row follows one
+// account-identity path: a matching identity updates its row; a new identity receives either the
+// requested label or an automatic email-derived label. UI must never persist managed OAuth into
+// auth.json because the pool owns refresh and account uniqueness.
+export async function commitManagedLogin(providerId, label, credential) {
+    const identity = await enrichManagedLoginIdentity(providerId, credential);
+    return mutateSubscriptionPool(providerId, (pool) => {
+        const accountId = identity.accountId;
+        const existing = pool.find((entry) => accountIdentity(entry) === accountIdentity({ accountId, refresh: credential.refresh }));
+        const resolvedLabel = existing?.label ?? (credential.autoLabel ? nextAutomaticLabel(pool, identity.email, label) : label?.trim());
+        if (!resolvedLabel)
+            throw new Error(`${getProviderLabel(providerId)} subscription label cannot be empty`);
+        if (!existing && pool.some((entry) => entry.label.toLowerCase() === resolvedLabel.toLowerCase())) {
+            throw new DuplicateSubscriptionError(`${getProviderLabel(providerId)} subscription already exists: ${resolvedLabel}`);
+        }
+        assertAccountAvailable(pool, providerId, accountIdentity({ accountId, refresh: credential.refresh }), resolvedLabel);
+        const next = {
+            label: resolvedLabel,
+            refresh: credential.refresh,
+            access: credential.access,
+            expires: credential.expires,
+            ...(accountId ? { accountId } : {}),
+            rateLimitedUntil: 0,
+            lastAttemptAt: Date.now(),
+            lastRateLimitedAt: credential.lastRateLimitedAt,
+        };
+        if (!existing)
+            return [...pool, next];
+        const index = pool.indexOf(existing);
+        const merged = [...pool];
+        merged[index] = mergeUpsert(existing, next);
+        return merged;
+    });
+}
+// Coordinated removal for the human UI. Removes a single account when `label` is given; the ENTIRE
+// provider (every pool account) when `label` is omitted — always through removeManagedAccount. UI
+// must NEVER reach for a raw auth.json delete on a managed provider: that strips a file pi no
+// longer reads for managed providers and orphans the whole pool.
+export async function removeManagedProvider(providerId, label) {
+    return mutateSubscriptionPool(providerId, (pool) => {
+        if (label === undefined)
+            return [];
+        const index = resolveCredentialIndex(pool, label);
+        if (index === -1)
+            throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${label}`);
+        const next = [...pool];
+        next.splice(index, 1);
+        return next;
+    });
+}
+export async 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 async 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 async 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 async function markSubscriptionAuthenticationFailed(providerId, ref, retryAfterMs, 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],
+            authFailure: "invalid_grant",
+            lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt),
+            // This is only an exclusion backoff, never a rate-limit observation.
+            rateLimitedUntil: Math.max(pool[index].rateLimitedUntil, attemptAt + Math.max(0, retryAfterMs)),
+        };
+        return next;
+    });
+}
+export async 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 async 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];
+        const { authFailure: _authFailure, ...healthy } = pool[index];
+        next[index] = { ...healthy, lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt), rateLimitedUntil: 0 };
+        return next;
+    });
+}
+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(crouterConfigFile());
+    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(rotationConfigFile()) ?? {};
+    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(rotationConfigFile(), 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) {
+            // `setModel` returns false when its target lacks configured auth and leaves
+            // the live model unchanged. A concurrent transition can still independently
+            // make THIS exact target current while this call is in flight, so re-read
+            // the live model and accept only when it now equals the target on both provider and
+            // model id; any other current model is a genuine failed switch.
+            const afterSwitch = getCurrentModelRef(ctx.model);
+            if (afterSwitch?.providerId !== target.providerId || afterSwitch.modelId !== target.modelId)
+                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)`;
+}