@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/__tests__/provider-rotation.test.ts

@@ -1,838 +1,545 @@
-import { before, after, test } from "node:test";
-import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
-import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { tmpdir } from "node:os";
-
-let home: string;
-let helpers: typeof import("../../lib/subscription-state.ts");
-let rotationModule: typeof import("../provider-rotation.ts");
-let providerRotationExtension: typeof import("../provider-rotation.ts").default;
-const previousHome = process.env.HOME;
-
-function writeLadderConfig() {
-  const configPath = join(home, ".crouter", "config.json");
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(
-    configPath,
-    `${JSON.stringify(
-      {
-        modelLadders: {
-          anthropic: {
-            ultra: "anthropic/claude-fable-5:high",
-            strong: "anthropic/claude-opus-4-8:high",
-            medium: "anthropic/claude-sonnet-4-6:high",
-            light: "anthropic/custom-light-x",
-          },
-          openai: {
-            ultra: "openai-codex/gpt-5.5:xhigh",
-            strong: "openai-codex/gpt-5.5:high",
-            medium: "openai-codex/gpt-5.4-mini:medium",
-            light: "openai-codex/gpt-5.3-codex-spark",
-          },
-        },
-      },
-      null,
-      2,
-    )}\n`,
-    "utf8",
-  );
-}
-
-function credential(label: string, overrides: Partial<helpers.SubscriptionCredential> = {}): helpers.SubscriptionCredential {
-  return {
-    label,
-    refresh: `refresh-${label}`,
-    access: `access-${label}`,
-    expires: Date.now() + 60_000,
-    rateLimitedUntil: 0,
-    lastAttemptAt: 0,
-    lastRateLimitedAt: 0,
-    ...overrides,
-  };
-}
-
-function resetRotationState() {
-  rmSync(join(home, ".pi", "agent", "auth.json"), { force: true });
-  helpers.writeSubscriptionPool("anthropic", []);
-  helpers.writeSubscriptionPool("openai-codex", []);
-  helpers.clearPreferredModel();
-}
-
-function makeAuthFileReadOnly(authPath: string): void {
-  chmodSync(authPath, 0o444);
-}
-
-function makeAuthFileWritable(authPath: string): void {
-  chmodSync(authPath, 0o600);
-}
-
-function observeLines(stream: NodeJS.ReadableStream, onLine: (line: string) => void): void {
-  let buffer = "";
-  stream.setEncoding("utf8");
-  stream.on("data", (chunk: string) => {
-    buffer += chunk;
-    let newlineIndex = buffer.indexOf("\n");
-    while (newlineIndex !== -1) {
-      const line = buffer.slice(0, newlineIndex);
-      buffer = buffer.slice(newlineIndex + 1);
-      onLine(line);
-      newlineIndex = buffer.indexOf("\n");
+    // Wait for clean exit first: code 0 proves the async unlock completed. A wedged child gets
+    // bounded SIGTERM/SIGKILL cleanup, and its test-owned lock is removed only on that fallback.
+    const closedWithin = (ms: number) =>
+      Promise.race([
+        childClosed,
+        new Promise<null>((resolve) => setTimeout(() => resolve(null), ms)),
+      ]);
+    let closed = await closedWithin(2000);
+    let forced = false;
+    if (!closed || closed.code !== 0) {
+      forced = true;
+      lockHolder.kill("SIGTERM");
+      closed = await closedWithin(2000);
+      if (!closed) {
+        lockHolder.kill("SIGKILL");
+        closed = await closedWithin(2000);
+      }
+      if (!closed) throw new Error("lock-holder child did not exit after SIGKILL");
     }
-  });
-}
-
-before(async () => {
-  home = mkdtempSync(join(tmpdir(), "pi-provider-rotation-"));
-  process.env.HOME = home;
-  helpers = await import("../../lib/subscription-state.ts");
-  rotationModule = await import("../provider-rotation.ts");
-  providerRotationExtension = rotationModule.default;
-});
+    if (forced) {
+      rmSync(`${poolFile}.lock`, { recursive: true, force: true });
+      throw new Error(`lock-holder exited without clean unlock (code=${closed.code}, signal=${closed.signal})`);
+    }
+  }
 
-after(() => {
-  if (previousHome === undefined) delete process.env.HOME;
-  else process.env.HOME = previousHome;
-  rmSync(home, { recursive: true, force: true });
+  const pool = helpers.markSubscriptionAttempt("openai-codex", "work", 456);
+  assert.equal(pool[0].lastAttemptAt, 456);
 });
 
-test("normalizes provider subscription pool files", () => {
+// Codex captures the login `accountId` and rejects the same account re-added under a different
+// label (a sticky browser session otherwise fakes redundancy on one quota); a distinct account
+// is stored with its own accountId.
+test("rejects a duplicate Codex account under a new label and stores accountId for a distinct one", async () => {
   resetRotationState();
-  helpers.writeSubscriptionPool("anthropic", [
-    {
-      label: " personal ",
-      refresh: " refresh-token ",
-      access: " access-token ",
-      expires: 123,
-      rateLimitedUntil: Number.NaN,
-      lastAttemptAt: Number.NaN,
-      lastRateLimitedAt: Number.NaN,
-    },
-  ]);
-
-  assert.deepEqual(helpers.readSubscriptionPool("anthropic"), [
-    {
-      label: "personal",
-      refresh: "refresh-token",
-      access: "access-token",
-      expires: 123,
-      rateLimitedUntil: 0,
-      lastAttemptAt: 0,
-      lastRateLimitedAt: 0,
-    },
-  ]);
-});
+  const { ctx, commands, pi } = makeRotationCtx();
+  ctx.hasUI = true;
+  const notes: Array<{ message: string; type?: string }> = [];
+  ctx.ui.notify = (message: string, type?: string) => notes.push({ message, type });
+  ctx.ui.input = async () => "";
+  let nextAccountId = "acct-1";
+  rotationModule.__setLoginForProviderForTest(async () => ({ refresh: "r", access: "a", expires: Date.now() + 60_000, accountId: nextAccountId }));
 
-// The default label's pool entry is metadata-only -- seeding it from auth.json must never
-// copy a token into the pool, only bootstrap the zeroed cooldown bookkeeping that has
-// nowhere else to live. Assert via the literal key set (not just "the value fields are
-// undefined") so a regression that starts writing `refresh: undefined` etc. -- which would
-// still satisfy an `undefined`-only check -- is caught.
-test("fresh-node seeding of the default slot is metadata-only (no value keys present at all)", () => {
-  resetRotationState();
-  const authPath = join(home, ".pi", "agent", "auth.json");
-  mkdirSync(dirname(authPath), { recursive: true });
-  writeFileSync(
-    authPath,
-    `${JSON.stringify({
-      "openai-codex": {
-        type: "oauth",
-        refresh: "refresh-codex-auth",
-        access: "access-codex-auth",
-        expires: 123456,
-      },
-    })}\n`,
-    "utf8",
-  );
+  try {
+    await providerRotationExtension(pi);
 
-  const pool = helpers.readSubscriptionPool("openai-codex");
-  assert.equal(pool.length, 1);
-  assert.deepEqual(Object.keys(pool[0]).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-  assert.deepEqual(pool[0], {
-    label: "openai-codex",
-    rateLimitedUntil: 0,
-    lastAttemptAt: 0,
-    lastRateLimitedAt: 0,
-  });
+    await commands["provider-sub"].handler("openai-codex add codex-alt", ctx);
+    let pool = helpers.readSubscriptionPool("openai-codex");
+    assert.deepEqual(pool.map((e) => e.label), ["codex-alt"]);
+    assert.equal(pool[0].accountId, "acct-1");
+
+    // Same account, different label -> rejected, pool unchanged.
+    notes.length = 0;
+    await commands["provider-sub"].handler("openai-codex add codex-dup", ctx);
+    assert.ok(notes.some((n) => n.type === "error" && /already added/i.test(n.message)), "duplicate account is rejected with an error");
+    pool = helpers.readSubscriptionPool("openai-codex");
+    assert.deepEqual(pool.map((e) => e.label), ["codex-alt"]);
+
+    // Distinct account -> stored with its own accountId.
+    nextAccountId = "acct-2";
+    await commands["provider-sub"].handler("openai-codex add codex-other", ctx);
+    pool = helpers.readSubscriptionPool("openai-codex");
+    assert.deepEqual(pool.map((e) => e.label).sort(), ["codex-alt", "codex-other"]);
+    assert.equal(pool.find((e) => e.label === "codex-other")?.accountId, "acct-2");
+  } finally {
+    rotationModule.__setLoginForProviderForTest(undefined);
+  }
 });
 
-// There is exactly one place the default slot's value is ever stored -- auth.json -- so
-// there is no second copy in the pool to ever diverge from it. Prove this directly: seed
-// the pool from auth.json holding credential A, then overwrite auth.json with a DIFFERENT
-// credential B (simulating an external refresh/re-login the pool never sees), and read the
-// pool again. It must still be the SAME metadata-only entry, unchanged by B -- because
-// there was never a value in the pool to go stale in the first place.
-test("no divergence is possible: overwriting auth.json elsewhere never changes the metadata-only pool entry", () => {
+// Review finding 1: the DEFAULT Codex slot must carry its account identity too, so the account
+// already backing the default login cannot be re-added under a second label, and list shows it.
+test("the default Codex slot carries its account identity: blocks re-adding the same account and renders it in list", async () => {
   resetRotationState();
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "refresh-A", access: "access-A", expires: 123456 },
-    })}\n`,
-    "utf8",
-  );
-
-  const first = helpers.readSubscriptionPool("anthropic");
-  assert.deepEqual(first, [{ label: "anthropic", rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 }]);
-
-  writeFileSync(
-    authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "refresh-B", access: "access-B", expires: 999999 },
-    })}\n`,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-def", access: "a-def", expires: Date.now() + 60_000, accountId: "acct-default" } })}\n`,
     "utf8",
   );
 
-  const second = helpers.readSubscriptionPool("anthropic");
-  assert.deepEqual(second, first);
-  assert.deepEqual(Object.keys(second[0]).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-});
-
-// The default label's pool entry is metadata-only on disk: reading it strips any stored
-// refresh, access, and expires fields and persists the cleaned pool immediately.
-test("scrubbing the default-slot value on read persists the metadata-only pool to disk", () => {
-  resetRotationState();
-  const poolFile = join(home, ".pi", "agent", "anthropic-subscriptions.json");
-  mkdirSync(dirname(poolFile), { recursive: true });
-  writeFileSync(
-    poolFile,
-    `${JSON.stringify([
-      { label: "anthropic", refresh: "stale-refresh", access: "stale-access", expires: 123, rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 },
-    ])}\n`,
-    "utf8",
-  );
-
-  const pool = helpers.readSubscriptionPool("anthropic");
-  assert.deepEqual(Object.keys(pool[0]).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-
-  // The raw FILE on disk must ALSO be scrubbed -- not just the in-memory return value.
-  const raw = JSON.parse(readFileSync(poolFile, "utf8"));
-  assert.deepEqual(Object.keys(raw[0]).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-});
-
-// The brick-repro (root cause of the original bug): two concurrent turns both see the
-// SAME expired default-slot credential and both try to refresh it. Without a real lock
-// serializing read -> decide -> refresh -> write, both call the (single-use) refresh token
-// and the loser gets a genuine invalid_grant from the provider -- bricking that turn. Prove
-// the fix: the injected refresh fn is called EXACTLY ONCE across two concurrent callers;
-// the second caller re-reads the winner's fresh value under the lock and skips its own
-// network call entirely; both callers resolve without throwing; auth.json ends up holding
-// exactly the one refreshed value; the pool entry stays metadata-only throughout.
-//
-// This test is proven to fail without the fix, not just asserted to pass with it -- see
-// the fail-then-pass evidence recorded in the implementation report.
-test("brick-repro: concurrent refreshes of the same expired default-slot token serialize through the lock (exactly one network refresh)", async () => {
-  resetRotationState();
-  const authPath = join(home, ".pi", "agent", "auth.json");
-  mkdirSync(dirname(authPath), { recursive: true });
-  writeFileSync(
-    authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "shared-refresh", access: "access-stale", expires: 1 },
-    })}\n`,
-    "utf8",
-  );
-  const poolEntry = helpers.readSubscriptionPool("anthropic")[0];
-  assert.equal(poolEntry.label, "anthropic");
-
-  let refreshCalls = 0;
-  rotationModule.__setRefreshForProviderForTest(async (_providerId, refreshToken) => {
-    refreshCalls += 1;
-    if (refreshCalls === 1) {
-      return { refresh: "shared-refresh-rotated", access: "access-fresh", expires: Date.now() + 60_000 };
-    }
-    // Any refresh call after the first is simulating "this refresh token was already
-    // consumed by the winner" -- a genuine invalid_grant from the provider.
-    throw Object.assign(new Error(`HTTP request failed. status=400; body={"error":"invalid_grant"} for token ${refreshToken}`), { status: 400 });
-  });
+  // Reading the pool seeds a metadata-only default entry that carries the account identity --
+  // no token value copied into the pool.
+  let pool = helpers.readSubscriptionPool("openai-codex");
+  assert.deepEqual(pool.map((e) => e.label), ["openai-codex"]);
+  assert.equal(pool[0].accountId, "acct-default");
+  assert.equal(pool[0].refresh, undefined);
 
+  const { ctx, commands, pi } = makeRotationCtx();
+  ctx.hasUI = true;
+  const notes: Array<{ message: string; type?: string }> = [];
+  ctx.ui.notify = (message: string, type?: string) => notes.push({ message, type });
+  ctx.ui.input = async () => "";
+  // A sticky browser re-login yields the SAME ChatGPT account already backing the default slot.
+  rotationModule.__setLoginForProviderForTest(async () => ({ refresh: "r2", access: "a2", expires: Date.now() + 60_000, accountId: "acct-default" }));
   try {
-    const [a, b] = await Promise.all([
-      rotationModule.__refreshCredentialIfNeededForTest("anthropic", poolEntry),
-      rotationModule.__refreshCredentialIfNeededForTest("anthropic", poolEntry),
-    ]);
-
-    assert.equal(refreshCalls, 1);
-    assert.equal(a.access, "access-fresh");
-    assert.equal(b.access, "access-fresh");
+    await providerRotationExtension(pi);
 
-    const stillMetadataOnly = helpers.readSubscriptionPool("anthropic")[0];
-    assert.deepEqual(Object.keys(stillMetadataOnly).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
+    await commands["provider-sub"].handler("openai-codex add codex-dup", ctx);
+    assert.ok(notes.some((n) => n.type === "error" && /already added/i.test(n.message)), "re-adding the default account under a new label is rejected");
+    pool = helpers.readSubscriptionPool("openai-codex");
+    assert.deepEqual(pool.map((e) => e.label), ["openai-codex"]);
 
-    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
-    assert.equal(authRaw.anthropic.access, "access-fresh");
-    assert.equal(authRaw.anthropic.refresh, "shared-refresh-rotated");
+    notes.length = 0;
+    await commands["provider-sub"].handler("openai-codex list", ctx);
+    assert.match(notes.map((n) => n.message).join("\n"), /account=/);
   } finally {
-    rotationModule.__setRefreshForProviderForTest(undefined);
+    rotationModule.__setLoginForProviderForTest(undefined);
   }
 });
 
-// A GENUINE invalid_grant (the refresh token is actually dead, not merely raced) must
-// still reach the real cooldown -> reauth path through the new lock-delegated seam --
-// the fix must not accidentally swallow or misclassify a real failure. Drives it through
-// the actual provider stream (not the raw helper) so `isInvalidRefreshTokenError` +
-// reauthentication + the AuthStorage persist all fire for real.
-test("a genuine invalid_grant through the default-slot lock still reauthenticates and persists to auth.json", async () => {
+// Drive the REAL default-login handler path: a collision with an explicit account must reject
+// before commitDefaultIdentity writes auth.json, so the failed OAuth result never partially
+// switches the default credential or creates a default pool entry with the duplicate identity.
+test("default-login handler rejects a colliding Codex account before switching auth.json", async () => {
   resetRotationState();
-  writeLadderConfig();
+  helpers.addSubscription("openai-codex", credential("work", { accountId: "acct-X" }));
   const authPath = join(home, ".pi", "agent", "auth.json");
-  mkdirSync(dirname(authPath), { recursive: true });
-  writeFileSync(
-    authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "dead-refresh", access: "access-stale", expires: 1 },
-    })}\n`,
-    "utf8",
-  );
-  // Seed the metadata-only pool entry for the default label.
-  helpers.readSubscriptionPool("anthropic");
-
-  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  const { ctx, commands, pi } = makeRotationCtx();
   ctx.hasUI = true;
-  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
-  ctx.ui.notify = () => {};
-  const loginCalls: string[] = [];
-  // Plain Error, no typed .status: real pi-ai refresh failures carry the HTTP status
-  // in the message text, so the refresh path still recognizes an invalid_grant from this
-  // shape.
-  rotationModule.__setRefreshForProviderForTest(async (providerId) => {
-    if (providerId === "anthropic") {
-      throw new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}');
-    }
-    throw new Error("unexpected refresh");
-  });
-  rotationModule.__setLoginForProviderForTest(async (providerId) => {
-    loginCalls.push(providerId);
-    return { refresh: "refresh-reauthed", access: "access-reauthed", expires: Date.now() + 60_000 };
-  });
-  rotationModule.__setStreamForProviderForTest((_model, _context, options) => {
-    return (async function* () {
-      yield { type: "text_delta", text: `hello with ${options?.apiKey}` };
-    })() as any;
-  });
-
+  const notes: Array<{ message: string; type?: string }> = [];
+  ctx.ui.notify = (message: string, type?: string) => notes.push({ message, type });
+  ctx.ui.input = async () => "";
+  rotationModule.__setLoginForProviderForTest(async () => ({ refresh: "r-X", access: "a-X", expires: Date.now() + 60_000, accountId: "acct-X" }));
   try {
     await providerRotationExtension(pi);
-    await events.session_start?.({}, ctx);
-    const stream = providers["anthropic"].streamSimple({ provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" }, ctx);
-    const emitted = [] as any[];
-    for await (const event of stream) emitted.push(event);
-
-    assert.deepEqual(loginCalls, ["anthropic"]);
-    assert.deepEqual(setModelCalls, []);
-    assert.ok(emitted.some((e) => e.type === "text_delta"));
-    assert.ok(!emitted.some((e) => e.type === "error"));
-
-    // Reauth persisted to auth.json (the single owner), not the pool.
-    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
-    assert.equal(authRaw.anthropic.refresh, "refresh-reauthed");
-    assert.equal(authRaw.anthropic.access, "access-reauthed");
-
-    // Pool stays metadata-only after reauth too, with the cooldown cleared.
-    const [entry] = helpers.readSubscriptionPool("anthropic");
-    assert.deepEqual(Object.keys(entry).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-    assert.equal(entry.rateLimitedUntil, 0);
+    await commands["provider-sub"].handler("openai-codex add openai-codex", ctx);
+    assert.ok(notes.some((note) => note.type === "error" && /already added/i.test(note.message)));
+    assert.equal(JSON.parse(readFileSync(authPath, "utf8"))["openai-codex"], undefined, "rejected default login must not switch auth.json");
+    const pool = helpers.readSubscriptionPool("openai-codex");
+    assert.equal(pool.filter((entry) => entry.accountId === "acct-X").length, 1);
+    assert.equal(pool.some((entry) => entry.label === "openai-codex"), false);
   } finally {
-    rotationModule.__setRefreshForProviderForTest(undefined);
     rotationModule.__setLoginForProviderForTest(undefined);
-    rotationModule.__setStreamForProviderForTest(undefined);
   }
 });
 
-// A locked auth.json write failure must not let default-slot reauth look successful or
-// clear the pool's cooldown bookkeeping.
-test("a locked default-slot reauth write failure leaves the pool cooled down and surfaces an error", async () => {
+// The handler snapshots the default slot before OAuth. A 429 recorded while OAuth is open is
+// causally newer, so completing a same-account login must not reopen that quota.
+test("default-login handler preserves a newer same-account cooldown recorded during OAuth", async () => {
   resetRotationState();
-  writeLadderConfig();
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "dead-refresh", access: "access-stale", expires: 1 },
-    })}\n`,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-old", access: "a-old", expires: Date.now() + 60_000, accountId: "acct-default" } })}\n`,
     "utf8",
   );
-  // Seed the metadata-only default pool entry for the default label.
-  helpers.readSubscriptionPool("anthropic");
+  helpers.readSubscriptionPool("openai-codex");
 
-  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  const { ctx, commands, pi } = makeRotationCtx();
   ctx.hasUI = true;
-  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
   ctx.ui.notify = () => {};
-  rotationModule.__setRefreshForProviderForTest(async (providerId) => {
-    if (providerId === "anthropic") {
-      throw new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}');
-    }
-    throw new Error("unexpected refresh");
+  ctx.ui.input = async () => "";
+  let rateLimitedAt = 0;
+  rotationModule.__setLoginForProviderForTest(async () => {
+    rateLimitedAt = Date.now();
+    helpers.markSubscriptionRateLimited("openai-codex", "openai-codex", 60_000, rateLimitedAt, rateLimitedAt);
+    return { refresh: "r-new", access: "a-new", expires: Date.now() + 60_000, accountId: "acct-default" };
   });
-  rotationModule.__setLoginForProviderForTest(async () => ({ refresh: "refresh-reauthed", access: "access-reauthed", expires: Date.now() + 60_000 }));
-  rotationModule.__setStreamForProviderForTest((_model, _context, options) => {
-    return (async function* () {
-      yield { type: "text_delta", text: `hello with ${options?.apiKey}` };
-    })() as any;
-  });
-
   try {
-    makeAuthFileReadOnly(authPath);
     await providerRotationExtension(pi);
-    await events.session_start?.({}, ctx);
-    const stream = providers["anthropic"].streamSimple(
-      { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" },
-      ctx,
-    );
-    const emitted = [] as any[];
-    for await (const event of stream) emitted.push(event);
-
-    assert.deepEqual(setModelCalls, []);
-    assert.ok(emitted.some((e) => e.type === "error"));
-    assert.ok(!emitted.some((e) => e.type === "text_delta"));
-
-    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
-    assert.equal(authRaw.anthropic.refresh, "dead-refresh");
-
-    const [entry] = helpers.readSubscriptionPool("anthropic");
-    assert.equal(entry.label, "anthropic");
-    assert.ok(entry.rateLimitedUntil > Date.now() + 29 * 24 * 60 * 60 * 1000);
+    await commands["provider-sub"].handler("openai-codex add openai-codex", ctx);
+    const [entry] = helpers.readSubscriptionPool("openai-codex");
+    assert.equal(entry.accountId, "acct-default");
+    assert.equal(entry.lastRateLimitedAt, rateLimitedAt);
+    assert.equal(entry.rateLimitedUntil, rateLimitedAt + 60_000);
+    assert.equal(JSON.parse(readFileSync(authPath, "utf8"))["openai-codex"].access, "a-new");
   } finally {
-    makeAuthFileWritable(authPath);
-    rotationModule.__setRefreshForProviderForTest(undefined);
     rotationModule.__setLoginForProviderForTest(undefined);
-    rotationModule.__setStreamForProviderForTest(undefined);
   }
 });
 
-// A genuine invalid_grant through the default-slot lock seam cools the credential down
-// and falls back cross-provider when UI is unavailable: expired OAuth in auth.json, a
-// metadata-only default pool entry, an authenticated Codex fallback, and the real
-// streamSimple path all participate.
-test("a genuine invalid_grant through the default-slot lock with no UI reaches cooldown and falls back cross-provider", async () => {
+// auth.json is the default slot's identity source of truth: every read reconciles the existing
+// metadata entry rather than only seeding it once. The pool never receives its token fields.
+test("the default slot re-syncs its identity from auth.json on every pool read", () => {
   resetRotationState();
-  writeLadderConfig();
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "dead-refresh", access: "access-stale", expires: 1 },
-    })}\n`,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-old", access: "a-old", expires: Date.now() + 60_000, accountId: "acct-old" } })}\n`,
     "utf8",
   );
-  // Seed the metadata-only default pool entry for anthropic -- the seam under test.
-  helpers.readSubscriptionPool("anthropic");
-  // Authenticated Codex fallback already sitting in its own pool.
-  helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
+  let [entry] = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(entry.accountId, "acct-old");
+  assert.equal(entry.refresh, undefined);
+  assert.equal(entry.access, undefined);
+  assert.equal(entry.expires, undefined);
 
-  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
-  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
-  // ctx.hasUI is deliberately left falsy: reauth must be impossible, so the only path
-  // forward is cooldown + cross-provider fallback.
-  const streamedModels: any[] = [];
-  rotationModule.__setRefreshForProviderForTest(async (providerId) => {
-    if (providerId === "anthropic") {
-      // Plain Error, no typed .status: the refresh path reads the invalid_grant shape from
-      // the message text, matching production failures.
-      throw new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}');
-    }
-    throw new Error("unexpected refresh");
-  });
-  rotationModule.__setStreamForProviderForTest((model) => {
-    streamedModels.push(model);
-    return (async function* () {
-      yield { type: "text_delta", text: "hello from codex fallback" };
-    })() as any;
-  });
-
-  try {
-    await providerRotationExtension(pi);
-    await events.session_start?.({}, ctx);
-    const stream = providers["anthropic"].streamSimple(
-      { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" },
-      ctx,
-    );
-    const emitted = [] as any[];
-    for await (const event of stream) emitted.push(event);
-
-    // Fell back cross-provider and actually served the turn on Codex.
-    assert.deepEqual(setModelCalls.map((m) => m.provider), ["openai-codex"]);
-    assert.equal(streamedModels.length, 1);
-    assert.equal(streamedModels[0].provider, "openai-codex");
-    assert.ok(emitted.some((e) => e.type === "text_delta"));
-    assert.ok(!emitted.some((e) => e.type === "error"));
-
-    // The default slot's metadata entry got the ~30-day invalid-refresh-token cooldown,
-    // through the real `withLockAsync` seam -- not a bypass.
-    const [entry] = helpers.readSubscriptionPool("anthropic");
-    assert.equal(entry.label, "anthropic");
-    assert.ok(entry.rateLimitedUntil > Date.now() + 29 * 24 * 60 * 60 * 1000);
-    assert.deepEqual(Object.keys(entry).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-
-    // No UI -- no reauth happened; auth.json still holds the dead credential unchanged.
-    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
-    assert.equal(authRaw.anthropic.refresh, "dead-refresh");
-  } finally {
-    rotationModule.__setRefreshForProviderForTest(undefined);
-    rotationModule.__setStreamForProviderForTest(undefined);
-  }
-});
-
-test("/provider-sub add still adds an explicit additional subscription alongside the default slot", () => {
-  resetRotationState();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic", { refresh: "refresh-first", access: "access-first" })]);
-
-  helpers.upsertSubscription("anthropic", credential("work", { refresh: "refresh-work", access: "access-work" }));
-
-  assert.deepEqual(helpers.readSubscriptionPool("anthropic").map((entry) => entry.label), ["anthropic", "work"]);
-});
-
-// /provider-sub <provider> add accepts the default label as the login-backed slot.
-// The pool stays metadata-only for that label, and the registered command handler writes
-// the credential to auth.json.
-
-test("/provider-sub add with the default label persists the login credential to auth.json instead of discarding it", async () => {
-  resetRotationState();
-  const authPath = join(home, ".pi", "agent", "auth.json");
-
-  const { ctx, commands, pi } = makeRotationCtx();
-  ctx.hasUI = true;
-  ctx.ui.notify = () => {};
-  ctx.ui.input = async (_message: string, placeholder: string) => placeholder; // accept the prompt's own default
-  rotationModule.__setLoginForProviderForTest(async () => ({ refresh: "refresh-default-login", access: "access-default-login", expires: Date.now() + 60_000 }));
-
-  try {
-    await providerRotationExtension(pi);
-    await commands["provider-sub"].handler("anthropic add", ctx);
-
-    // The credential must be persisted to auth.json (the single owner), NOT discarded.
-    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
-    assert.equal(authRaw.anthropic.refresh, "refresh-default-login");
-    assert.equal(authRaw.anthropic.access, "access-default-login");
-
-    // The pool gets a metadata-only default entry (no value written into it) with the
-    // cooldown cleared -- not a broken "authenticated but valueless" slot.
-    const [entry] = helpers.readSubscriptionPool("anthropic");
-    assert.equal(entry.label, "anthropic");
-    assert.deepEqual(Object.keys(entry).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
-    assert.equal(entry.rateLimitedUntil, 0);
-  } finally {
-    rotationModule.__setLoginForProviderForTest(undefined);
-  }
+  writeFileSync(
+    authPath,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-new", access: "a-new", expires: Date.now() + 60_000, accountId: "acct-new" } })}\n`,
+    "utf8",
+  );
+  [entry] = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(entry.accountId, "acct-new");
+  assert.equal(entry.refresh, undefined);
+  assert.equal(entry.access, undefined);
+  assert.equal(entry.expires, undefined);
 });
 
-// A locked auth.json write failure must not let the default-label add path clear the
-// pool cooldown bookkeeping or pretend the add succeeded.
-test("/provider-sub add with the default label keeps the pool cooldown when auth.json write fails", async () => {
+// An auth writer outside provider rotation can change the default identity without the pool
+// lock. Reconciliation validates under that lock and refuses to return or persist two slots for
+// one account; removing the explicit duplicate remains a valid repair operation.
+test("auth-driven default reconciliation refuses a colliding explicit identity", async () => {
   resetRotationState();
   const authPath = join(home, ".pi", "agent", "auth.json");
+  const poolPath = join(home, ".pi", "agent", "openai-codex-subscriptions.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "refresh-existing", access: "access-existing", expires: Date.now() + 60_000 },
-    })}\n`,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-old", access: "a-old", expires: 100, accountId: "acct-old" } })}\n`,
     "utf8",
   );
-  helpers.readSubscriptionPool("anthropic");
-  helpers.markSubscriptionRateLimited("anthropic", "anthropic", 60_000, 100, 200);
-  const beforeCooldown = helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil;
+  helpers.readSubscriptionPool("openai-codex");
+  helpers.addSubscription("openai-codex", credential("work", { accountId: "acct-new" }));
+
+  writeFileSync(
+    authPath,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-new", access: "a-new", expires: 200, accountId: "acct-new" } })}\n`,
+    "utf8",
+  );
+  assert.throws(
+    () => helpers.readSubscriptionPool("openai-codex"),
+    (err: unknown) => err instanceof helpers.DuplicateSubscriptionError && /already added/i.test((err as Error).message),
+  );
+  const rawAfterRejection = JSON.parse(readFileSync(poolPath, "utf8"));
+  assert.equal(rawAfterRejection.find((entry: { label: string }) => entry.label === "openai-codex").accountId, "acct-old");
 
   const { ctx, commands, pi } = makeRotationCtx();
-  ctx.hasUI = true;
   ctx.ui.notify = () => {};
-  ctx.ui.input = async (_message: string, placeholder: string) => placeholder;
-  rotationModule.__setLoginForProviderForTest(async () => ({ refresh: "refresh-default-login", access: "access-default-login", expires: Date.now() + 60_000 }));
-
-  try {
-    makeAuthFileReadOnly(authPath);
-    await providerRotationExtension(pi);
-    await commands["provider-sub"].handler("anthropic add", ctx);
-
-    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
-    assert.equal(authRaw.anthropic.refresh, "refresh-existing");
-    const [entry] = helpers.readSubscriptionPool("anthropic");
-    assert.equal(entry.label, "anthropic");
-    assert.equal(entry.rateLimitedUntil, beforeCooldown);
-  } finally {
-    makeAuthFileWritable(authPath);
-    rotationModule.__setLoginForProviderForTest(undefined);
-  }
+  await providerRotationExtension(pi);
+  await commands["provider-sub"].handler("openai-codex rm work", ctx);
+  assert.deepEqual(
+    helpers.readSubscriptionPool("openai-codex").map((entry) => ({ label: entry.label, accountId: entry.accountId })),
+    [{ label: "openai-codex", accountId: "acct-new" }],
+  );
 });
 
-// The default metadata slot is seeded whenever auth.json holds an OAuth credential for
-// the provider, even when the pool already contains explicit non-default accounts.
-test("seeds the default metadata slot even when the pool already has an explicit non-default account", () => {
+// Explicit reauth uses the identity-checked upsert: it can refresh its OWN stored identity, but
+// cannot reauth into an account held by another slot.
+test("the uniqueness-aware reauth upsert refreshes its slot but rejects another slot's account", () => {
   resetRotationState();
-  helpers.writeSubscriptionPool("anthropic", [credential("work", { refresh: "refresh-work", access: "access-work" })]);
-
-  const authPath = join(home, ".pi", "agent", "auth.json");
-  mkdirSync(dirname(authPath), { recursive: true });
-  writeFileSync(
-    authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "refresh-native-login", access: "access-native-login", expires: Date.now() + 60_000 },
-    })}\n`,
-    "utf8",
+  helpers.writeSubscriptionPool("openai-codex", [credential("work", { accountId: "acct-old" }), credential("other", { accountId: "acct-held" })]);
+  helpers.upsertSubscriptionWithUniqueAccount("openai-codex", credential("work", { accountId: "acct-new", refresh: "r-new", access: "a-new" }));
+  let pool = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(pool.find((entry) => entry.label === "work")?.accountId, "acct-new");
+  assert.throws(
+    () => helpers.upsertSubscriptionWithUniqueAccount("openai-codex", credential("work", { accountId: "acct-held", refresh: "r-collision", access: "a-collision" })),
+    (err: unknown) => err instanceof helpers.DuplicateSubscriptionError && /already added/i.test((err as Error).message),
   );
-
-  const pool = helpers.readSubscriptionPool("anthropic");
-  assert.deepEqual(pool.map((entry) => entry.label).sort(), ["anthropic", "work"]);
-  const defaultEntry = pool.find((entry) => entry.label === "anthropic");
-  assert.deepEqual(Object.keys(defaultEntry!).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
+  pool = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(pool.find((entry) => entry.label === "work")?.accountId, "acct-new");
+  assert.equal(pool.filter((entry) => entry.accountId === "acct-held").length, 1);
 });
 
-// An api_key auth.json record does not seed the default metadata slot.
-test("does not seed a default metadata slot for an api_key auth.json record", () => {
+// A rejected default identity move must leave BOTH stores untouched: account uniqueness happens
+// inside the pool lock before commitDefaultIdentity writes auth.json under the nested auth lock.
+test("commitDefaultIdentity rejects an explicit account without partially switching auth.json or the pool", () => {
   resetRotationState();
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
-    `${JSON.stringify({
-      anthropic: { type: "api_key", key: "sk-not-oauth" },
-    })}\n`,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-old", access: "a-old", expires: 100, accountId: "acct-old" } })}\n`,
     "utf8",
   );
-
-  assert.deepEqual(helpers.readSubscriptionPool("anthropic"), []);
+  helpers.writeSubscriptionPool("openai-codex", [
+    { label: "openai-codex", accountId: "acct-old", rateLimitedUntil: 0, lastAttemptAt: 10, lastRateLimitedAt: 0 },
+    credential("work", { accountId: "acct-new" }),
+  ]);
+  const authBefore = readFileSync(authPath, "utf8");
+  const poolBefore = helpers.readSubscriptionPool("openai-codex");
+  assert.throws(
+    () =>
+      helpers.commitDefaultIdentity("openai-codex", {
+        refresh: "r-new",
+        access: "a-new",
+        expires: 200,
+        accountId: "acct-new",
+        lastRateLimitedAt: 0,
+      }),
+    (err: unknown) => err instanceof helpers.DuplicateSubscriptionError && /already added/i.test((err as Error).message),
+  );
+  assert.equal(readFileSync(authPath, "utf8"), authBefore);
+  assert.deepEqual(helpers.readSubscriptionPool("openai-codex"), poolBefore);
 });
 
-// Hold the real auth.json lock in a separate process and prove the seed read fails
-// visibly instead of silently returning an empty default slot while the file is locked.
-test("locked auth.json seeding fails visibly instead of treating an existing default as absent", async () => {
+// A same-account login uses its pre-OAuth rate-limit timestamp as a causal basis. A newer 429
+// survives, an equal-basis login may clear it, and a genuine account switch starts new quota clean.
+test("commitDefaultIdentity preserves newer same-account cooldowns and resets old-account cooldowns", () => {
   resetRotationState();
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
-    `${JSON.stringify({
-      anthropic: { type: "oauth", refresh: "refresh-locked", access: "access-locked", expires: Date.now() + 60_000 },
-    })}
-`,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-old", access: "a-old", expires: 100, accountId: "acct-old" } })}\n`,
     "utf8",
   );
-
-  const subscriptionStateUrl = new URL("../../lib/subscription-state.ts", import.meta.url).href;
-  const readProbe = spawn(
-    process.execPath,
-    [
-      "--import",
-      "tsx/esm",
-      "--input-type=module",
-      "-e",
-      String.raw`const { readSubscriptionPool } = await import(${JSON.stringify(subscriptionStateUrl)});
-process.stdout.write("ready\n");
-await new Promise((resolve) => {
-  process.stdin.setEncoding("utf8");
-  process.stdin.once("data", resolve);
-});
-process.stdout.write("about-to-read\n");
-const pool = readSubscriptionPool("anthropic");
-process.stdout.write("result:" + JSON.stringify(pool) + "\n");`,
-    ],
-    { env: { ...process.env, HOME: home }, stdio: ["pipe", "pipe", "pipe"] },
-  );
-  let sawReady = false;
-  let sawResult = false;
-  let readStderr = "";
-  readProbe.stderr!.setEncoding("utf8");
-  readProbe.stderr!.on("data", (chunk: string) => {
-    readStderr += chunk;
-  });
-  const readReady = new Promise<void>((resolve, reject) => {
-    readProbe.once("error", reject);
-    readProbe.once("close", (code) => {
-      if (!sawReady) reject(new Error(`read-probe exited with ${code} before signalling readiness: ${readStderr.trim()}`));
-    });
-    observeLines(readProbe.stdout!, (line) => {
-      if (line === "ready") {
-        sawReady = true;
-        resolve();
-        return;
-      }
-      if (line.startsWith("result:")) sawResult = true;
-    });
-  });
-  const readDone = new Promise<number | null>((resolve, reject) => {
-    readProbe.once("error", reject);
-    readProbe.once("close", resolve);
+  helpers.readSubscriptionPool("openai-codex");
+  helpers.markSubscriptionRateLimited("openai-codex", "openai-codex", 60_000, 100, 100);
+
+  helpers.commitDefaultIdentity("openai-codex", {
+    refresh: "r-stale",
+    access: "a-stale",
+    expires: 200,
+    accountId: "acct-old",
+    lastRateLimitedAt: 0,
   });
-  await readReady;
-
-  const lockHolder = spawn(
-    process.execPath,
-    [
-      "--import",
-      "tsx/esm",
-      "--input-type=module",
-      "-e",
-      String.raw`import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
-const backend = new FileAuthStorageBackend();
-await backend.withLockAsync(async () => {
-  process.stdout.write("locked\n");
-  await new Promise((resolve) => {
-    process.stdin.setEncoding("utf8");
-    process.stdin.once("data", resolve);
+  let [entry] = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(entry.lastRateLimitedAt, 100);
+  assert.equal(entry.rateLimitedUntil, 60_100, "a newer same-account 429 survives the stale login");
+
+  helpers.commitDefaultIdentity("openai-codex", {
+    refresh: "r-current",
+    access: "a-current",
+    expires: 300,
+    accountId: "acct-old",
+    lastRateLimitedAt: 100,
   });
-  return { result: undefined };
-});`,
-    ],
-    { env: { ...process.env, HOME: home }, stdio: ["pipe", "pipe", "pipe"] },
-  );
-  let lockStderr = "";
-  lockHolder.stderr!.setEncoding("utf8");
-  lockHolder.stderr!.on("data", (chunk: string) => {
-    lockStderr += chunk;
+  [entry] = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(entry.rateLimitedUntil, 0, "an equal-basis same-account login may clear the cooldown");
+
+  helpers.markSubscriptionRateLimited("openai-codex", "openai-codex", 60_000, 200, 200);
+  helpers.commitDefaultIdentity("openai-codex", {
+    refresh: "r-other",
+    access: "a-other",
+    expires: 400,
+    accountId: "acct-other",
+    lastRateLimitedAt: 100,
   });
-  let sawLocked = false;
-  const lockReady = new Promise<void>((resolve, reject) => {
-    lockHolder.once("error", reject);
-    lockHolder.once("close", (code) => {
-      if (!sawLocked) reject(new Error(`lock-holder exited with ${code} before signalling readiness: ${lockStderr.trim()}`));
-    });
-    observeLines(lockHolder.stdout!, (line) => {
-      if (line === "locked") {
-        sawLocked = true;
-        resolve();
-      }
-    });
-  });
-  const lockDone = new Promise<void>((resolve, reject) => {
-    lockHolder.once("error", reject);
-    lockHolder.once("close", (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`lock-holder exited with ${code}: ${lockStderr.trim()}`));
-    });
-  });
-  await lockReady;
-  readProbe.stdin!.write("go\n");
-  readProbe.stdin!.end();
-  const readExitCode = await readDone;
-  lockHolder.stdin!.write("release\n");
-  lockHolder.stdin!.end();
-
-  assert.equal(sawResult, false);
-  assert.notEqual(readExitCode, 0);
-  assert.match(readStderr, /ELOCKED|Lock file is already being held/);
-  await lockDone;
-  assert.deepEqual(helpers.readSubscriptionPool("anthropic"), [{ label: "anthropic", rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0 }]);
+  [entry] = helpers.readSubscriptionPool("openai-codex");
+  assert.equal(entry.accountId, "acct-other");
+  assert.equal(entry.lastRateLimitedAt, 200);
+  assert.equal(entry.rateLimitedUntil, 0, "a different account does not inherit the old account's quota cooldown");
 });
 
-test("resolves Anthropic to strength-matched OpenAI Codex fallback", () => {
+// Label AND account uniqueness are enforced INSIDE the locked add transform
+// (throwing a typed error), so the check-then-append is atomic rather than a lock-free race.
+test("addSubscription normalizes labels and enforces Codex account uniqueness inside the locked transform", () => {
   resetRotationState();
-  writeLadderConfig();
-
-  assert.deepEqual(helpers.resolveFallbackTarget("anthropic", "anthropic/claude-opus-4-8:high"), {
-    providerId: "openai-codex",
-    modelId: "gpt-5.5",
-    label: "openai-codex/gpt-5.5:high",
-    strength: "strong",
-    thinkingLevel: "high",
-  });
-});
-
-test("resolves OpenAI Codex to strength-matched Anthropic fallback", () => {
-  writeLadderConfig();
-
-  assert.deepEqual(helpers.resolveFallbackTarget("openai-codex", "openai-codex/gpt-5.4-mini:medium"), {
-    providerId: "anthropic",
-    modelId: "claude-sonnet-4-6",
-    label: "anthropic/claude-sonnet-4-6:high",
-    strength: "medium",
-    thinkingLevel: "high",
-  });
+  helpers.addSubscription("openai-codex", credential("work", { accountId: "acct-1" }));
+  assert.throws(
+    () => helpers.addSubscription("openai-codex", credential(" work ", { accountId: "acct-2" })),
+    (err: unknown) => err instanceof helpers.DuplicateSubscriptionError && /already exists/i.test((err as Error).message),
+  );
+  assert.throws(
+    () => helpers.addSubscription("openai-codex", credential("   ", { accountId: "acct-3" })),
+    (err: unknown) => !(err instanceof helpers.DuplicateSubscriptionError) && /cannot be empty/i.test((err as Error).message),
+  );
+  assert.throws(
+    () => helpers.addSubscription("openai-codex", credential("work-2", { accountId: "acct-1" })),
+    (err: unknown) => err instanceof helpers.DuplicateSubscriptionError && /already added/i.test((err as Error).message),
+  );
+  helpers.addSubscription("openai-codex", credential("work-3", { accountId: "acct-3" }));
+  assert.deepEqual(helpers.readSubscriptionPool("openai-codex").map((entry) => entry.label).sort(), ["work", "work-3"]);
 });
 
-// Ultra and strong share the bare model id gpt-5.5; the live thinking level selects
-// the matching ladder rung.
-test("disambiguates colliding ladder rungs by the live thinking level", () => {
+// The first contender holds the real pool lock inside addSubscription's transform. The second
+// contender cannot reach its own transform until it has first attempted that same real lock.
+// This makes an outside-lock uniqueness check deterministic: both checks run while the pool is
+// empty, then both appends succeed after the holder releases.
+test("cross-process explicit adds admit exactly one duplicate Codex account", async () => {
   resetRotationState();
-  writeLadderConfig();
-  const config = helpers.readRotationConfig();
-
-  // xhigh -> ultra rung -> Anthropic ultra (claude-fable-5)
-  assert.deepEqual(helpers.resolveFallbackTarget("openai-codex", "gpt-5.5", config, "xhigh"), {
-    providerId: "anthropic",
-    modelId: "claude-fable-5",
-    label: "anthropic/claude-fable-5:high",
-    strength: "ultra",
-    thinkingLevel: "high",
+  const poolPath = join(home, ".pi", "agent", "openai-codex-subscriptions.json");
+  const releasePath = join(home, "release-cross-process-add-race");
+  const subscriptionStateUrl = new URL("../../lib/subscription-state.ts", import.meta.url).href;
+  const spawnContender = (label: string, role: "holder" | "waiter") => {
+    const child = spawn(
+      process.execPath,
+      [
+        "--import",
+        "tsx/esm",
+        "--input-type=module",
+        "-e",
+        String.raw`import { existsSync, writeSync } from "node:fs";
+import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
+const { addSubscription, DuplicateSubscriptionError } = await import(${JSON.stringify(subscriptionStateUrl)});
+const poolPath = ${JSON.stringify(poolPath)};
+const releasePath = ${JSON.stringify(releasePath)};
+const role = ${JSON.stringify(role)};
+const originalWithLock = FileAuthStorageBackend.prototype.withLock;
+FileAuthStorageBackend.prototype.withLock = function (fn) {
+  if (this.authPath !== poolPath) return originalWithLock.call(this, fn);
+  writeSync(1, "attempt\n");
+  if (role === "waiter") {
+    // This is a real acquisition attempt against the holder's real lock. It happens after any
+    // hypothetical outside-lock validation but before the transform can run.
+    try {
+      originalWithLock.call(new FileAuthStorageBackend(poolPath), () => ({ result: undefined }));
+      throw new Error("waiter acquired the pool lock while the holder was still inside it");
+    } catch (error) {
+      if ((error).code !== "ELOCKED") throw error;
+    }
+    writeSync(1, "acquiring\n");
+    while (!existsSync(releasePath)) {}
+  }
+  return originalWithLock.call(this, (current) => {
+    if (role === "holder") {
+      writeSync(1, "inside\n");
+      while (!existsSync(releasePath)) {}
+    }
+    return fn(current);
   });
-
-  // high -> strong rung -> Anthropic strong (claude-opus-4-8)
-  assert.equal(helpers.resolveFallbackTarget("openai-codex", "gpt-5.5", config, "high").modelId, "claude-opus-4-8");
-
-  // No thinking level falls back to the default-strength tie-break (strong -> opus).
-  assert.equal(helpers.resolveFallbackTarget("openai-codex", "gpt-5.5", config).modelId, "claude-opus-4-8");
-});
-
-test("parses Retry-After seconds and HTTP dates", () => {
-  const now = Date.UTC(2026, 5, 16, 18, 30, 0);
-  assert.equal(helpers.parseRetryAfterHeader("1.5", now), 1500);
-
-  const retryAt = new Date(now + 15_000).toUTCString();
-  const parsed = helpers.parseRetryAfterHeader(retryAt, now);
-  assert.ok(parsed !== undefined && parsed >= 14_000 && parsed <= 15_000);
-  assert.equal(helpers.parseRetryAfterHeader("", now), undefined);
-  assert.equal(helpers.parseRetryAfterHeader("not-a-delay", now), undefined);
-});
-
-test("restores preferred model when its provider pool frees up", async () => {
-  resetRotationState();
-  writeLadderConfig();
-  helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
-  helpers.writeRotationConfig({ preferredModel: { providerId: "openai-codex", modelId: "gpt-5.5" } });
-
-  const setModelCalls: any[] = [];
-  const ctx = {
-    model: { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" },
-    modelRegistry: {
-      find(provider: string, id: string) {
-        return { provider, id, api: provider === "openai-codex" ? "openai-codex-responses" : "anthropic-messages" };
-      },
-    },
-  } as any;
-  const pi = {
-    async setModel(model: any) {
-      setModelCalls.push(model);
-      ctx.model = model;
-      return true;
-    },
-  } as any;
-
-  const restored = await helpers.restorePreferredModelIfPossible(pi, ctx);
-
-  assert.equal(restored, true);
-  assert.deepEqual(setModelCalls[0], {
-    provider: "openai-codex",
-    id: "gpt-5.5",
-    api: "openai-codex-responses",
+};
+try {
+  addSubscription("openai-codex", {
+    label: ${JSON.stringify(label)}, refresh: "refresh-${label}", access: "access-${label}", expires: Date.now() + 60_000,
+    accountId: "acct-cross-process-race", rateLimitedUntil: 0, lastAttemptAt: 0, lastRateLimitedAt: 0,
   });
-  assert.equal(helpers.readRotationConfig().preferredModel, undefined);
+  writeSync(1, "outcome:success\n");
+} catch (error) {
+  const outcome = error instanceof DuplicateSubscriptionError ? "duplicate" : "error";
+  writeSync(1, "outcome:" + outcome + "\n");
+  if (outcome === "error") process.stderr.write(String(error));
+}`,
+      ],
+      { env: { ...process.env, HOME: home }, stdio: ["pipe", "pipe", "pipe"] },
+    );
+    const signals = new Set<string>();
+    let outcome: string | undefined;
+    let stderr = "";
+    let stdout = "";
+    child.stdout!.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr!.setEncoding("utf8");
+    child.stderr!.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    const signal = (expected: string) =>
+      new Promise<void>((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code) => {
+          if (!signals.has(expected)) reject(new Error(`${label} exited with ${code} before ${expected}: ${stderr.trim()}`));
+        });
+        observeLines(child.stdout!, (line) => {
+          signals.add(line);
+          if (line === expected) resolve();
+          if (line.startsWith("outcome:")) outcome = line.slice("outcome:".length);
+        });
+      });
+    const closed = new Promise<number | null>((resolve) => child.once("close", resolve));
+    const stdoutEnded = new Promise<void>((resolve) => child.stdout!.once("end", resolve));
+    return { child, closed, label, outcome: () => outcome, signal, stderr: () => stderr, stdout: () => stdout, stdoutEnded };
+  };
+
+  const holder = spawnContender("race-left", "holder");
+  const contenders = [holder];
+  try {
+    await within(Promise.all([holder.signal("attempt"), holder.signal("inside")]), 10_000, "holder did not reach the locked transform within 10s");
+    const waiter = spawnContender("race-right", "waiter");
+    contenders.push(waiter);
+    await within(Promise.all([waiter.signal("attempt"), waiter.signal("acquiring")]), 10_000, "waiter did not attempt the held pool lock within 10s");
+    writeFileSync(releasePath, "release\n", "utf8");
+    const exitCodes = await within(Promise.all(contenders.map((contender) => contender.closed)), 3000, "cross-process contenders did not exit within 3s");
+    await within(Promise.all(contenders.map((contender) => contender.stdoutEnded)), 1000, "cross-process contender output did not close within 1s");
+    assert.deepEqual(exitCodes, [0, 0], contenders.map((contender) => contender.stderr()).join("\n"));
+    assert.deepEqual(contenders.map((contender) => contender.outcome()).sort(), ["duplicate", "success"], contenders.map((contender) => contender.stdout()).join("\n"));
+    const pool = helpers.readSubscriptionPool("openai-codex");
+    assert.equal(pool.length, 1);
+    assert.ok(["race-left", "race-right"].includes(pool[0].label));
+  } finally {
+    const errors: unknown[] = [];
+    try {
+      writeFileSync(releasePath, "release\n", "utf8");
+    } catch (error) {
+      errors.push(error);
+    }
+    const teardown = async (contender: ReturnType<typeof spawnContender>) => {
+      if (contender.child.exitCode !== null || contender.child.signalCode !== null) return;
+      try {
+        contender.child.stdin!.end();
+      } catch {
+        // The child may already have closed its input.
+      }
+      if (await within(contender.closed.then(() => true), 1000, `${contender.label} did not exit gracefully within 1s`).catch(() => false)) return;
+      contender.child.kill("SIGTERM");
+      if (await within(contender.closed.then(() => true), 1000, `${contender.label} did not exit after SIGTERM`).catch(() => false)) return;
+      contender.child.kill("SIGKILL");
+      await within(contender.closed, 1000, `${contender.label} did not exit after SIGKILL`);
+    };
+    const results = await Promise.allSettled(contenders.map(teardown));
+    errors.push(...results.flatMap((result) => (result.status === "rejected" ? [result.reason] : [])));
+    try {
+      assert.equal(existsSync(`${poolPath}.lock`), false, "cross-process add race must release the pool lock directory");
+    } catch (error) {
+      errors.push(error);
+    }
+    if (errors.length) throw new AggregateError(errors, "cross-process contender teardown failed");
+  }
 });
 
-test("keeps newest Retry-After cooldown across overlapping attempts", () => {
+// Corruption can arrive after commitDefaultIdentity projects auth.json for its pool-lock
+// callback but before it obtains the nested auth lock to persist. That persistence parse must
+// fail loudly and leave both stores precisely as they were at the corruption point.
+test("malformed auth during nested default persistence preserves malformed bytes and the pool cooldown", () => {
   resetRotationState();
-  helpers.writeSubscriptionPool("anthropic", [credential("personal")]);
-
-  helpers.markSubscriptionAttempt("anthropic", "personal", 100);
-  helpers.markSubscriptionAttempt("anthropic", "personal", 200);
-  helpers.markSubscriptionRateLimited("anthropic", "personal", 60_000, 100, 150);
-  helpers.markSubscriptionRateLimited("anthropic", "personal", 5_000, 200, 205);
-  helpers.markSubscriptionRateLimited("anthropic", "personal", 10_000, 100, 300);
-
-  const [entry] = helpers.readSubscriptionPool("anthropic");
+  const authPath = join(home, ".pi", "agent", "auth.json");
+  const poolPath = join(home, ".pi", "agent", "openai-codex-subscriptions.json");
+  mkdirSync(dirname(authPath), { recursive: true });
+  writeFileSync(
+    authPath,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "r-old", access: "a-old", expires: 100, accountId: "acct-old" } })}\n`,
+    "utf8",
+  );
+  helpers.readSubscriptionPool("openai-codex");
+  helpers.markSubscriptionRateLimited("openai-codex", "openai-codex", 60_000, 500, 500);
+  const poolBefore = readFileSync(poolPath, "utf8");
+  const malformed = '{"openai-codex":';
+  const originalWithLock = FileAuthStorageBackend.prototype.withLock;
+  let authLockCalls = 0;
+  FileAuthStorageBackend.prototype.withLock = function (fn) {
+    const isAuthLock = (this as unknown as { authPath: string }).authPath === authPath;
+    if (isAuthLock) authLockCalls += 1;
+    const result = originalWithLock.call(this, fn);
+    if (isAuthLock && authLockCalls === 1) writeFileSync(authPath, malformed, "utf8");
+    return result;
+  };
+  try {
+    assert.throws(
+      () =>
+        helpers.commitDefaultIdentity("openai-codex", {
+          refresh: "r-new",
+          access: "a-new",
+          expires: 200,
+          accountId: "acct-old",
+          lastRateLimitedAt: 500,
+        }),
+      SyntaxError,
+    );
+  } finally {
+    FileAuthStorageBackend.prototype.withLock = originalWithLock;
+  }
+  assert.equal(authLockCalls, 2, "the second auth lock is the nested persistence parse");
+  assert.equal(readFileSync(authPath, "utf8"), malformed);
+  assert.equal(readFileSync(poolPath, "utf8"), poolBefore);
+  const [entry] = JSON.parse(poolBefore) as helpers.SubscriptionCredential[];
   assert.deepEqual(
-    { lastAttemptAt: entry.lastAttemptAt, lastRateLimitedAt: entry.lastRateLimitedAt, rateLimitedUntil: entry.rateLimitedUntil },
-    { lastAttemptAt: 200, lastRateLimitedAt: 300, rateLimitedUntil: 10300 },
+    { lastRateLimitedAt: entry.lastRateLimitedAt, rateLimitedUntil: entry.rateLimitedUntil },
+    { lastRateLimitedAt: 500, rateLimitedUntil: 60_500 },
   );
-
-  helpers.markSubscriptionSuccess("anthropic", "personal", 250);
-  assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 10300);
-  helpers.markSubscriptionSuccess("anthropic", "personal", 400);
-  assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 0);
 });
 
 test("treats numeric subscription refs as 1-based indexes", () => {
@@ -860,7 +567,7 @@ test("switches exhausted Anthropic sessions to OpenAI Codex fallback", async ()
     model: { provider: "anthropic", id: "claude-sonnet-4-6", api: "anthropic-messages" },
     modelRegistry: {
       find(provider: string, id: string) {
-        return provider === "openai-codex" && id === "gpt-5.4-mini" ? { provider, id, api: "openai-codex-responses" } : undefined;
+        return provider === "openai-codex" && id === "gpt-5.6-terra" ? { provider, id, api: "openai-codex-responses" } : undefined;
       },
     },
   } as any;
@@ -881,14 +588,14 @@ test("switches exhausted Anthropic sessions to OpenAI Codex fallback", async ()
 
   assert.deepEqual(target, {
     providerId: "openai-codex",
-    modelId: "gpt-5.4-mini",
-    label: "openai-codex/gpt-5.4-mini:medium",
+    modelId: "gpt-5.6-terra",
+    label: "openai-codex/gpt-5.6-terra:medium",
     strength: "medium",
     thinkingLevel: "medium",
   });
   assert.deepEqual(switchedTo, {
     provider: "openai-codex",
-    id: "gpt-5.4-mini",
+    id: "gpt-5.6-terra",
     api: "openai-codex-responses",
   });
   assert.equal(thinkingLevel, "medium");
@@ -903,7 +610,7 @@ test("switches exhausted OpenAI Codex sessions to Anthropic fallback", async ()
   writeLadderConfig();
 
   const ctx = {
-    model: { provider: "openai-codex", id: "gpt-5.5", api: "openai-codex-responses" },
+    model: { provider: "openai-codex", id: "gpt-5.6-sol", api: "openai-codex-responses" },
     modelRegistry: {
       find(provider: string, id: string) {
         return provider === "anthropic" && id === "claude-opus-4-8" ? { provider, id, api: "anthropic-messages" } : undefined;
@@ -940,18 +647,18 @@ test("switches exhausted OpenAI Codex sessions to Anthropic fallback", async ()
   assert.equal(thinkingLevel, "high");
   assert.deepEqual(helpers.readRotationConfig().preferredModel, {
     providerId: "openai-codex",
-    modelId: "gpt-5.5",
+    modelId: "gpt-5.6-sol",
   });
 });
 
 function makeRotationCtx() {
   const ctx = {
-    model: { provider: "openai-codex", id: "gpt-5.5", api: "openai-codex-responses" },
+    model: { provider: "openai-codex", id: "gpt-5.6-sol", api: "openai-codex-responses" },
     ui: { setStatus() {} },
     modelRegistry: {
       find(provider: string, id: string) {
         if (provider === "anthropic" && id === "claude-opus-4-8") return { provider, id, api: "anthropic-messages" };
-        if (provider === "openai-codex" && id === "gpt-5.5") return { provider, id, api: "openai-codex-responses" };
+        if (provider === "openai-codex" && id === "gpt-5.6-sol") return { provider, id, api: "openai-codex-responses" };
         return undefined;
       },
     },
@@ -999,7 +706,7 @@ test("falls back transparently and serves the turn on Anthropic when Codex is ex
     await providerRotationExtension(pi);
     await events.session_start?.({}, ctx);
     const stream = providers["openai-codex"].streamSimple(
-      { provider: "openai-codex", id: "gpt-5.5", api: "openai-codex-responses" },
+      { provider: "openai-codex", id: "gpt-5.6-sol", api: "openai-codex-responses" },
       ctx,
     );
     const emitted = [] as any[];
@@ -1344,6 +1051,106 @@ test("automatically reauthenticates invalid refresh tokens when UI is available"
   }
 });
 
+// The real invalid-refresh path must route an explicit Codex reauth through the locked identity
+// gate. A colliding OAuth result is rejected, the old credential remains intact, and the slot is
+// cooled instead of being duplicated or streamed with another slot's quota.
+test("real explicit Codex reauth rejects an account held by another slot", async () => {
+  resetRotationState();
+  writeLadderConfig();
+  helpers.writeSubscriptionPool("openai-codex", [
+    credential("stale", { expires: 1, accountId: "acct-old" }),
+    credential("held", { accountId: "acct-held", rateLimitedUntil: Date.now() + 10 * 60_000 }),
+  ]);
+
+  const { ctx, providers, events, pi } = makeRotationCtx();
+  ctx.hasUI = true;
+  const notes: Array<{ message: string; type?: string }> = [];
+  ctx.ui.notify = (message: string, type?: string) => notes.push({ message, type });
+  rotationModule.__setRefreshForProviderForTest(async (providerId) => {
+    if (providerId === "openai-codex") {
+      throw new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}');
+    }
+    throw new Error("unexpected refresh");
+  });
+  rotationModule.__setLoginForProviderForTest(async () => ({
+    refresh: "r-collision",
+    access: "a-collision",
+    expires: Date.now() + 60_000,
+    accountId: "acct-held",
+  }));
+  try {
+    await providerRotationExtension(pi);
+    await events.session_start?.({}, ctx);
+    const stream = providers["openai-codex"].streamSimple(ctx.model, ctx);
+    for await (const _event of stream) {
+      // Drain the real managed-provider stream to completion.
+    }
+
+    const pool = helpers.readSubscriptionPool("openai-codex");
+    const stale = pool.find((entry) => entry.label === "stale");
+    assert.equal(stale?.accountId, "acct-old");
+    assert.equal(stale?.refresh, "refresh-stale");
+    assert.ok((stale?.rateLimitedUntil ?? 0) > Date.now() + 29 * 24 * 60 * 60 * 1000);
+    assert.equal(pool.filter((entry) => entry.accountId === "acct-held").length, 1);
+    assert.ok(notes.some((note) => note.type === "error" && /re-authentication failed.*already added/i.test(note.message)));
+  } finally {
+    rotationModule.__setRefreshForProviderForTest(undefined);
+    rotationModule.__setLoginForProviderForTest(undefined);
+  }
+});
+
+// The default Codex reauth branch uses the same gate before auth persistence. A colliding login
+// leaves auth.json on the original account and keeps both pool identities unique.
+test("real default Codex reauth rejects an explicit slot's account before switching auth.json", async () => {
+  resetRotationState();
+  writeLadderConfig();
+  const authPath = join(home, ".pi", "agent", "auth.json");
+  mkdirSync(dirname(authPath), { recursive: true });
+  writeFileSync(
+    authPath,
+    `${JSON.stringify({ "openai-codex": { type: "oauth", refresh: "dead-refresh", access: "stale-access", expires: 1, accountId: "acct-old" } })}\n`,
+    "utf8",
+  );
+  helpers.readSubscriptionPool("openai-codex");
+  helpers.addSubscription("openai-codex", credential("held", { accountId: "acct-held", rateLimitedUntil: Date.now() + 10 * 60_000 }));
+
+  const { ctx, providers, events, pi } = makeRotationCtx();
+  ctx.hasUI = true;
+  const notes: Array<{ message: string; type?: string }> = [];
+  ctx.ui.notify = (message: string, type?: string) => notes.push({ message, type });
+  rotationModule.__setRefreshForProviderForTest(async (providerId) => {
+    if (providerId === "openai-codex") {
+      throw new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}');
+    }
+    throw new Error("unexpected refresh");
+  });
+  rotationModule.__setLoginForProviderForTest(async () => ({
+    refresh: "r-collision",
+    access: "a-collision",
+    expires: Date.now() + 60_000,
+    accountId: "acct-held",
+  }));
+  try {
+    await providerRotationExtension(pi);
+    await events.session_start?.({}, ctx);
+    const stream = providers["openai-codex"].streamSimple(ctx.model, ctx);
+    for await (const _event of stream) {
+      // Drain the real managed-provider stream to completion.
+    }
+
+    const auth = JSON.parse(readFileSync(authPath, "utf8"))["openai-codex"];
+    assert.equal(auth.accountId, "acct-old");
+    assert.equal(auth.refresh, "dead-refresh");
+    const pool = helpers.readSubscriptionPool("openai-codex");
+    assert.equal(pool.find((entry) => entry.label === "openai-codex")?.accountId, "acct-old");
+    assert.equal(pool.filter((entry) => entry.accountId === "acct-held").length, 1);
+    assert.ok(notes.some((note) => note.type === "error" && /re-authentication failed.*already added/i.test(note.message)));
+  } finally {
+    rotationModule.__setRefreshForProviderForTest(undefined);
+    rotationModule.__setLoginForProviderForTest(undefined);
+  }
+});
+
 // A resolved-but-unauthenticated fallback stays on the current model and returns an
 // actionable "not authenticated" error when no provider is logged in.
 test("emits an actionable 'not authenticated' error without switching models when neither provider has ever logged in", async () => {
@@ -1377,7 +1184,7 @@ test("degrades gracefully via the builtin ladder when a config-less user has no
     modelRegistry: {
       find(provider: string, id: string) {
         if (provider === "anthropic" && id === "claude-opus-4-8") return { provider, id, api: "anthropic-messages" };
-        if (provider === "openai-codex" && id === "gpt-5.5") return { provider, id, api: "openai-codex-responses" };
+        if (provider === "openai-codex" && id === "gpt-5.6-sol") return { provider, id, api: "openai-codex-responses" };
         return undefined;
       },
     },
@@ -1404,7 +1211,7 @@ test("degrades gracefully via the builtin ladder when a config-less user has no
   await providerRotationExtension(pi);
   await events.session_start?.({}, ctx);
   // Anthropic pool is empty (reset above), so the credential loop never runs. The builtin
-  // ladder resolves a cross-provider target (openai-codex/gpt-5.5), but that provider was
+  // ladder resolves a cross-provider target (openai-codex/gpt-5.6-sol), but that provider was
   // never authenticated either (#123 gates fallback on the target actually being authed),
   // so the session model stays unchanged and the turn returns an actionable message.
   const stream = providers["anthropic"].streamSimple(ctx.model, ctx);
@@ -1419,16 +1226,16 @@ test("degrades gracefully via the builtin ladder when a config-less user has no
 });
 
 // readModelLadders() reads the builtin anthropic/openai ladder when config.json is absent.
-test("resolves the builtin anthropic ladder (medium = sonnet-5) with no ~/.crouter/config.json present", () => {
+test("resolves the builtin anthropic ladder (medium = opus-4-8) with no ~/.crouter/config.json present", () => {
   resetRotationState();
   rmSync(join(home, ".crouter", "config.json"), { force: true });
 
-  const target = helpers.resolveFallbackTarget("anthropic", "anthropic/claude-sonnet-5:high");
+  const target = helpers.resolveFallbackTarget("anthropic", "anthropic/claude-opus-4-8:high");
 
   assert.deepEqual(target, {
     providerId: "openai-codex",
-    modelId: "gpt-5.5",
-    label: "openai-codex/gpt-5.5:medium",
+    modelId: "gpt-5.6-terra",
+    label: "openai-codex/gpt-5.6-terra:medium",
     strength: "medium",
     thinkingLevel: "medium",
   });
@@ -1515,6 +1322,97 @@ test("does not wait out a cooldown longer than the sole-provider wait cap; surfa
   }
 });
 
+// Live-incident regression (Hearth: a home's config.json had `gpt-5.6-*` ladder rungs baked
+// in while the installed guest's model registry only had `gpt-5.5`): when the ONLY viable
+// fallback target is authenticated (its pool has a credential) but its resolved model isn't
+// in this build's registry, the terminal error must name that specific reason -- not the old
+// generic "authenticate a fallback provider" text, which is actively wrong when the real
+// blocker is a stale/out-of-sync ladder, not a missing login.
+test("surfaces a specific 'not in model registry' reason instead of misleadingly telling the user to authenticate", async () => {
+  resetRotationState();
+  writeLadderConfig();
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
+  helpers.markSubscriptionRateLimited("anthropic", "primary", 30 * 24 * 60 * 60 * 1000);
+  // OpenAI Codex IS authenticated -- the fallback rejection must NOT be "no credentials".
+  helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
+
+  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
+  // Registry recognizes anthropic's own model but NOT the configured openai-codex fallback
+  // rung (`gpt-5.6-sol`, from writeLadderConfig) -- simulating an installed guest whose
+  // catalog hasn't caught up with the configured ladder.
+  ctx.modelRegistry = {
+    find(provider: string, id: string) {
+      return provider === "anthropic" && id === "claude-opus-4-8" ? { provider, id, api: "anthropic-messages" } : undefined;
+    },
+  };
+  const sleepCalls: number[] = [];
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+  });
+
+  try {
+    await providerRotationExtension(pi);
+    await events.session_start?.({}, ctx);
+    const stream = providers["anthropic"].streamSimple(
+      { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" },
+      ctx,
+    );
+    const emitted = [] as any[];
+    for await (const event of stream) emitted.push(event);
+
+    assert.deepEqual(setModelCalls, []);
+    assert.deepEqual(sleepCalls, []);
+    assert.equal(emitted.length, 1);
+    assert.equal(emitted[0].type, "error");
+    assert.match(emitted[0].error.errorMessage, /openai-codex\/gpt-5\.6-sol:high is not in this build's model registry/);
+    assert.match(emitted[0].error.errorMessage, /modelLadders config is out of sync with the installed model catalog/);
+    assert.doesNotMatch(emitted[0].error.errorMessage, /authenticate a fallback provider/);
+    // The repair command must be EXECUTABLE as printed: `--value`, the CONFIG ladder
+    // provider key (`openai`, not the runtime `openai-codex`), and the target's strength.
+    assert.match(
+      emitted[0].error.errorMessage,
+      /crtr sys config set modelLadders\.openai\.strong --value <installed-model-id>/,
+    );
+  } finally {
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+// Every fallback-rejection discriminant maps to advice that can actually resolve IT.
+// Only `no_credentials` may say "authenticate" -- telling the user to authenticate when both
+// providers are exhausted, when no ladder rung exists, or when the model is unregistered is
+// actively wrong and was the original bug.
+test("fallback rejection hints: only no_credentials advises authentication; every other discriminant gets accurate advice", () => {
+  const codex = {
+    providerId: "openai-codex",
+    modelId: "gpt-5.6-sol",
+    label: "openai-codex/gpt-5.6-sol:high",
+    strength: "strong",
+  } as helpers.FallbackTarget;
+
+  const noCreds = rotationModule.__fallbackRejectionHintForTest("no_credentials", codex);
+  assert.match(noCreds, /authenticate a fallback provider/);
+  assert.match(noCreds, /OpenAI Codex/);
+  assert.match(noCreds, /\/provider-sub openai-codex add/);
+
+  const unregistered = rotationModule.__fallbackRejectionHintForTest("model_unregistered", codex);
+  assert.doesNotMatch(unregistered, /authenticate a fallback provider/);
+  assert.match(unregistered, /not in this build's model registry/);
+  // Executable repair command: --value, CONFIG ladder key (openai), target strength.
+  assert.match(unregistered, /crtr sys config set modelLadders\.openai\.strong --value <installed-model-id>/);
+
+  const alreadyTried = rotationModule.__fallbackRejectionHintForTest("already_attempted", codex);
+  assert.doesNotMatch(alreadyTried, /authenticate a fallback provider/);
+  assert.match(alreadyTried, /already tried this turn/);
+  assert.match(alreadyTried, /try again later/);
+
+  const noLadder = rotationModule.__fallbackRejectionHintForTest("no_ladder_entry");
+  assert.doesNotMatch(noLadder, /authenticate a fallback provider/);
+  assert.match(noLadder, /no cross-provider fallback is configured/);
+  assert.match(noLadder, /modelLadders/);
+});
+
 // The wait-out decision uses the pool state from the current turn, not a stale snapshot.
 test("waits out a sole credential's cooldown observed in THIS turn, not a stale pre-attempt pool snapshot", async () => {
   resetRotationState();
@@ -1578,7 +1476,7 @@ test("treats a Codex usage-limit message on a non-429 status as a rate limit: co
   helpers.writeSubscriptionPool("anthropic", [credential("personal")]);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
-  ctx.model = { provider: "openai-codex", id: "gpt-5.5", api: "openai-codex-responses" };
+  ctx.model = { provider: "openai-codex", id: "gpt-5.6-sol", api: "openai-codex-responses" };
   const streamedModels: any[] = [];
   rotationModule.__setStreamForProviderForTest((model) => {
     streamedModels.push(model);
@@ -1601,7 +1499,7 @@ test("treats a Codex usage-limit message on a non-429 status as a rate limit: co
     await providerRotationExtension(pi);
     await events.session_start?.({}, ctx);
     const stream = providers["openai-codex"].streamSimple(
-      { provider: "openai-codex", id: "gpt-5.5", api: "openai-codex-responses" },
+      { provider: "openai-codex", id: "gpt-5.6-sol", api: "openai-codex-responses" },
       ctx,
     );
     const emitted = [] as any[];