@crouton-kit/crouter 0.3.68 → 0.3.78

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

@@ -1,4 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+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";
@@ -25,6 +26,11 @@ export type SubscriptionCredential = {
   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 = {
@@ -90,10 +96,11 @@ function readJsonFile<T>(path: string): T | undefined {
   }
 }
 
-function writeJsonFile(path: string, value: unknown): void {
+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`, "utf8");
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, mode === undefined ? "utf8" : { encoding: "utf8", mode });
+  if (mode !== undefined) chmodSync(tmp, mode);
   renameSync(tmp, path);
 }
 
@@ -111,11 +118,13 @@ function normalizeCredential(value: Partial<SubscriptionCredential> & { label?:
   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),
@@ -131,32 +140,60 @@ function getCurrentModelRef(model?: { provider: string; id: string }): ModelRef
   return isManagedProvider(model?.provider) ? { providerId: model.provider, modelId: model.id } : undefined;
 }
 
-type AuthFileData = Record<string, { type?: string }>;
+type AuthFileData = Record<string, { type?: string; accountId?: unknown }>;
 
-function readAuthCredential(providerId: ManagedProviderId): { type?: string } | undefined {
+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;
-    return { result: data[providerId] };
+    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 } };
   });
 }
 
-// Seeds a METADATA-ONLY pool entry for the default label (`label === providerId`)
-// whenever an OAuth-login-linked credential exists for it in auth.json, regardless of
-// whether the pool already holds OTHER explicit accounts. The auth.json seed read goes
-// 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. No token is ever copied into the pool: the value lives
-// exclusively in auth.json.
+// 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[] {
-  if (pool.some((entry) => entry.label === providerId)) return pool;
   const authCred = readAuthCredential(providerId);
   if (authCred?.type !== "oauth") return pool;
-  const seeded = normalizeCredential({ label: providerId, rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 });
-  return seeded ? [...pool, seeded] : 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
@@ -180,23 +217,98 @@ export function isManagedProvider(providerId: string | undefined): providerId is
   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);
-  if (wasScrubbed || withDefaultSlot !== scrubbed) return writeSubscriptionPool(providerId, withDefaultSlot);
+  // 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[] {
-  const normalized = scrubDefaultValue(providerId, normalizeCredentials(next)).pool;
-  writeJsonFile(PROVIDERS[providerId].poolFile, normalized);
-  return normalized;
+  return mutateSubscriptionPool(providerId, () => next);
 }
 
 function resolveCredentialIndex(pool: SubscriptionCredential[], ref: string): number {
@@ -208,39 +320,210 @@ function resolveCredentialIndex(pool: SubscriptionCredential[], ref: string): nu
   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[] {
-  const pool = readSubscriptionPool(providerId);
-  const index = pool.findIndex((entry) => entry.label.toLowerCase() === next.label.toLowerCase());
-  if (index === -1) pool.push(next);
-  else pool[index] = next;
-  return writeSubscriptionPool(providerId, pool);
+  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[] {
-  const pool = readSubscriptionPool(providerId);
-  const index = resolveCredentialIndex(pool, ref);
-  if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-  pool.splice(index, 1);
-  return writeSubscriptionPool(providerId, pool);
+  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[] {
-  const pool = readSubscriptionPool(providerId);
-  const index = resolveCredentialIndex(pool, ref);
-  if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-  if (index > 0) pool.unshift(pool.splice(index, 1)[0]);
-  return writeSubscriptionPool(providerId, pool);
+  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[] {
-  const pool = readSubscriptionPool(providerId);
-  const index = resolveCredentialIndex(pool, ref);
-  if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-  pool[index] = {
-    ...pool[index],
-    lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt),
-  };
-  return writeSubscriptionPool(providerId, pool);
+  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(
@@ -250,30 +533,34 @@ export function markSubscriptionRateLimited(
   attemptAt = Date.now(),
   rateLimitedAt = Date.now(),
 ): SubscriptionCredential[] {
-  const pool = readSubscriptionPool(providerId);
-  const index = resolveCredentialIndex(pool, ref);
-  if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-  if (rateLimitedAt < pool[index].lastRateLimitedAt) return pool;
-  pool[index] = {
-    ...pool[index],
-    lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt),
-    lastRateLimitedAt: Math.max(pool[index].lastRateLimitedAt, rateLimitedAt),
-    rateLimitedUntil: rateLimitedAt + Math.max(0, retryAfterMs),
-  };
-  return writeSubscriptionPool(providerId, pool);
+  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[] {
-  const pool = readSubscriptionPool(providerId);
-  const index = resolveCredentialIndex(pool, ref);
-  if (index === -1) throw new Error(`Unknown ${getProviderLabel(providerId)} subscription: ${ref}`);
-  if (attemptAt < pool[index].lastRateLimitedAt) return pool;
-  pool[index] = {
-    ...pool[index],
-    lastAttemptAt: Math.max(pool[index].lastAttemptAt, attemptAt),
-    rateLimitedUntil: 0,
-  };
-  return writeSubscriptionPool(providerId, pool);
+  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 {
@@ -291,7 +578,7 @@ export function parseRetryAfterHeader(value: string | undefined, now = Date.now(
 }
 
 function thinkingLevelOfRef(ref: string): ThinkingLevel | undefined {
-  const match = ref.trim().match(/:(thinking|off|minimal|low|medium|high|xhigh)$/i);
+  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);
@@ -301,7 +588,7 @@ function normalizeModelRef(ref: string): string {
   return ref
     .trim()
     .replace(/^[^/]+\//, "")
-    .replace(/:(?:thinking|off|minimal|low|medium|high|xhigh)$/i, "")
+    .replace(/:(?:thinking|off|minimal|low|medium|high|xhigh|max)$/i, "")
     .toLowerCase();
 }
 
@@ -313,7 +600,7 @@ function splitModelRef(ref: string): FallbackTarget {
     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))$/i);
+  const thinkingMatch = rawModelId.match(/^(.*?)(?::(thinking|off|minimal|low|medium|high|xhigh|max))$/i);
   return {
     providerId,
     modelId: thinkingMatch ? thinkingMatch[1] : rawModelId,
@@ -325,28 +612,11 @@ function splitModelRef(ref: string): FallbackTarget {
   };
 }
 
-// Vendored copy of crouter's `defaultModelLaddersConfig()` (src/types.ts).
-// This package is synced from a standalone repo (pi-personal-extensions) and
-// has no runtime import path into crouter's compiled internals, so the
-// builtin rungs are duplicated here rather than imported; keep the two in
-// sync by hand if either changes.
-const BUILTIN_MODEL_LADDERS: Record<LadderProviderId, ModelLadderConfig> = {
-  anthropic: {
-    ultra: "anthropic/claude-fable-5:high",
-    strong: "anthropic/claude-opus-4-8:high",
-    medium: "anthropic/claude-sonnet-5:high",
-    light: "anthropic/claude-haiku-4-5:high",
-  },
-  openai: {
-    ultra: "openai-codex/gpt-5.5:xhigh",
-    strong: "openai-codex/gpt-5.5:high",
-    medium: "openai-codex/gpt-5.5:medium",
-    light: "openai-codex/gpt-5.3-codex-spark",
-  },
-};
-
-// Layers ~/.crouter/config.json's `modelLadders` (if any) OVER the builtin
-// defaults above, per provider/strength — mirroring crouter's own
+// 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
@@ -358,9 +628,10 @@ const BUILTIN_MODEL_LADDERS: Record<LadderProviderId, ModelLadderConfig> = {
 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_MODEL_LADDERS[provider] };
+    const normalized: ModelLadderConfig = { ...builtin[provider] };
     const override = overrides?.[provider];
     if (override) {
       for (const strength of ["ultra", "strong", "medium", "light"] as const) {
@@ -389,7 +660,7 @@ function findStrengthForModelId(
     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.5:xhigh vs gpt-5.5:high) are
+  // 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);

package/dist/builtin-pi-packages/pi-crtr-extensions/package-lock.json

@@ -1,11 +1,11 @@
 {
-  "name": "pi-personal-extensions",
+  "name": "pi-crtr-extensions",
   "version": "0.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "pi-personal-extensions",
+      "name": "pi-crtr-extensions",
       "version": "0.1.0",
       "license": "MIT",
       "dependencies": {