@crouton-kit/crouter 0.3.55 → 0.3.57

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

@@ -1,6 +1,7 @@
 import { before, after, test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+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";
 
@@ -59,6 +60,29 @@ function resetRotationState() {
   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");
+    }
+  });
+}
+
 before(async () => {
   home = mkdtempSync(join(tmpdir(), "pi-provider-rotation-"));
   process.env.HOME = home;
@@ -100,7 +124,12 @@ test("normalizes provider subscription pool files", () => {
   ]);
 });
 
-test("empty provider pool reseeds from OAuth auth", () => {
+// 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 });
@@ -117,83 +146,337 @@ test("empty provider pool reseeds from OAuth auth", () => {
     "utf8",
   );
 
-  assert.deepEqual(helpers.readSubscriptionPool("openai-codex"), [
-    {
-      label: "openai-codex",
-      refresh: "refresh-codex-auth",
-      access: "access-codex-auth",
-      expires: 123456,
-      rateLimitedUntil: 0,
-      lastAttemptAt: 0,
-      lastRateLimitedAt: 0,
-    },
-  ]);
+  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,
+  });
 });
 
-test("default provider subscription syncs when OAuth auth is refreshed elsewhere", () => {
+// 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", () => {
   resetRotationState();
-  helpers.writeSubscriptionPool("anthropic", [
-    credential("anthropic", {
-      refresh: "refresh-same",
-      access: "access-stale",
-      expires: 1,
-      rateLimitedUntil: Date.now() + 60_000,
-    }),
-  ]);
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
     `${JSON.stringify({
-      anthropic: {
-        type: "oauth",
-        refresh: "refresh-same",
-        access: "access-fresh",
-        expires: 123456,
-      },
+      anthropic: { type: "oauth", refresh: "refresh-A", access: "access-A", expires: 123456 },
     })}\n`,
     "utf8",
   );
 
-  assert.deepEqual(helpers.readSubscriptionPool("anthropic"), [
-    {
-      label: "anthropic",
-      refresh: "refresh-same",
-      access: "access-fresh",
-      expires: 123456,
-      rateLimitedUntil: 0,
-      lastAttemptAt: 0,
-      lastRateLimitedAt: 0,
-    },
-  ]);
+  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`,
+    "utf8",
+  );
+
+  const second = helpers.readSubscriptionPool("anthropic");
+  assert.deepEqual(second, first);
+  assert.deepEqual(Object.keys(second[0]).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
 });
 
-// Regression: ambient /login auth sync used to append a brand-new pool entry whenever
-// the freshly authenticated tokens didn't match an existing entry by refresh/access
-// (e.g. a re-login that rotated both tokens), silently duplicating the default account
-// instead of updating it. It must update the selected/default slot (index 0) in place;
-// adding a genuinely additional account stays an explicit `/provider-sub add` action.
-test("/login with non-matching tokens replaces the default provider subscription slot", () => {
+// 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();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic", { refresh: "refresh-first", access: "access-first" })]);
   const authPath = join(home, ".pi", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   writeFileSync(
     authPath,
     `${JSON.stringify({
-      anthropic: {
-        type: "oauth",
-        refresh: "refresh-second",
-        access: "access-second",
-        expires: 123456,
-      },
+      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 });
+  });
 
-  assert.deepEqual(helpers.readSubscriptionPool("anthropic").map((entry) => ({ label: entry.label, refresh: entry.refresh, access: entry.access })), [
-    { label: "anthropic", refresh: "refresh-second", access: "access-second" },
-  ]);
+  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");
+
+    const stillMetadataOnly = helpers.readSubscriptionPool("anthropic")[0];
+    assert.deepEqual(Object.keys(stillMetadataOnly).sort(), ["label", "lastAttemptAt", "lastRateLimitedAt", "rateLimitedUntil"]);
+
+    const authRaw = JSON.parse(readFileSync(authPath, "utf8"));
+    assert.equal(authRaw.anthropic.access, "access-fresh");
+    assert.equal(authRaw.anthropic.refresh, "shared-refresh-rotated");
+  } finally {
+    rotationModule.__setRefreshForProviderForTest(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 () => {
+  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`,
+    "utf8",
+  );
+  // Seed the metadata-only pool entry for the default label.
+  helpers.readSubscriptionPool("anthropic");
+
+  const { ctx, setModelCalls, providers, events, 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;
+  });
+
+  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);
+  } 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 () => {
+  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`,
+    "utf8",
+  );
+  // Seed the metadata-only default pool entry for the default label.
+  helpers.readSubscriptionPool("anthropic");
+
+  const { ctx, setModelCalls, providers, events, 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");
+  });
+  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);
+  } 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 () => {
+  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`,
+    "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")]);
+
+  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", () => {
@@ -205,6 +488,238 @@ test("/provider-sub add still adds an explicit additional subscription alongside
   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);
+  }
+});
+
+// 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 () => {
+  resetRotationState();
+  const authPath = join(home, ".pi", "agent", "auth.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`,
+    "utf8",
+  );
+  helpers.readSubscriptionPool("anthropic");
+  helpers.markSubscriptionRateLimited("anthropic", "anthropic", 60_000, 100, 200);
+  const beforeCooldown = helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil;
+
+  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);
+  }
+});
+
+// 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", () => {
+  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",
+  );
+
+  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"]);
+});
+
+// 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", () => {
+  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`,
+    "utf8",
+  );
+
+  assert.deepEqual(helpers.readSubscriptionPool("anthropic"), []);
+});
+
+// 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 () => {
+  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 },
+    })}
+`,
+    "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);
+  });
+  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);
+  });
+  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;
+  });
+  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 }]);
+});
+
 test("resolves Anthropic to strength-matched OpenAI Codex fallback", () => {
   resetRotationState();
   writeLadderConfig();
@@ -230,9 +745,8 @@ test("resolves OpenAI Codex to strength-matched Anthropic fallback", () => {
   });
 });
 
-// Regression: ultra (gpt-5.5:xhigh) and strong (gpt-5.5:high) share the bare model id
-// `gpt-5.5`. The strength matcher used to collapse both to `strong`, so an ultra run fell
-// back to opus instead of the ultra Anthropic model. The live thinking level disambiguates.
+// 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", () => {
   resetRotationState();
   writeLadderConfig();
@@ -250,7 +764,7 @@ test("disambiguates colliding ladder rungs by the live thinking level", () => {
   // 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: preserves the legacy default-strength tie-break (strong -> opus).
+  // 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");
 });
 
@@ -445,11 +959,14 @@ function makeRotationCtx() {
   const setModelCalls: any[] = [];
   const providers: Record<string, { streamSimple: (...args: any[]) => AsyncIterable<any> }> = {};
   const events: Record<string, (...args: any[]) => unknown> = {};
+  const commands: Record<string, { handler: (args: string, ctx: any) => unknown }> = {};
   const pi = {
     registerProvider(name: string, provider: { streamSimple: (...args: any[]) => AsyncIterable<any> }) {
       providers[name] = provider;
     },
-    registerCommand() {},
+    registerCommand(name: string, command: { handler: (args: string, ctx: any) => unknown }) {
+      commands[name] = command;
+    },
     on(eventName: string, handler: (...args: any[]) => unknown) {
       events[eventName] = handler;
     },
@@ -460,12 +977,10 @@ function makeRotationCtx() {
     },
     setThinkingLevel() {},
   } as any;
-  return { ctx, setModelCalls, providers, events, pi };
+  return { ctx, setModelCalls, providers, events, commands, pi };
 }
 
-// Regression: Codex-exhausted fallback used to switch the model and then FAIL the turn
-// with a "retry on fallback" error, stranding autonomous nodes. It must now switch AND
-// transparently serve the same turn on the fallback provider.
+// Codex exhaustion switches the model and serves the same turn on the Anthropic fallback.
 test("falls back transparently and serves the turn on Anthropic when Codex is exhausted", async () => {
   resetRotationState();
   writeLadderConfig();
@@ -503,15 +1018,12 @@ test("falls back transparently and serves the turn on Anthropic when Codex is ex
   }
 });
 
-// Regression: request timeouts (and other transient network/5xx blips) used to be treated
-// exactly like a genuine rate limit -- cooling the credential down for 5 minutes and
-// rotating away from a perfectly healthy subscription over one blip (#122). They must
-// instead get a short in-place retry on the SAME credential/provider, no cooldown, no
-// rotation -- proven here by recovering on the second attempt without ever switching models.
+// Request timeouts and other transient network/5xx blips retry the same provider in place
+// without cooling the credential down or rotating away.
 test("treats a request timeout as transient: retries the SAME provider in place, no cooldown or rotation", async () => {
   resetRotationState();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
   helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
@@ -568,7 +1080,7 @@ test("treats a request timeout as transient: retries the SAME provider in place,
 test("ends the turn without rotating once the transient retry budget is exhausted", async () => {
   resetRotationState();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
   helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
@@ -616,7 +1128,7 @@ test("ends the turn without rotating once the transient retry budget is exhauste
 test("treats HTTP 429 as a genuine rate limit: rotates immediately using the Retry-After header, no in-place retry", async () => {
   resetRotationState();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
   helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
@@ -665,7 +1177,7 @@ test("treats HTTP 429 as a genuine rate limit: rotates immediately using the Ret
 test("does not cool down credentials or switch providers when the user aborts", async () => {
   resetRotationState();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
   helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
@@ -726,9 +1238,11 @@ test("skips invalid refresh tokens and serves the turn on the fallback provider"
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
   ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
   const streamedModels: any[] = [];
+  // Plain Error, no typed .status: the default-slot path still recognizes invalid_grant
+  // from the message text.
   rotationModule.__setRefreshForProviderForTest(async (providerId) => {
     if (providerId === "anthropic") {
-      throw Object.assign(new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}'), { status: 400 });
+      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");
   });
@@ -773,9 +1287,11 @@ test("automatically reauthenticates invalid refresh tokens when UI is available"
   ctx.ui.notify = () => {};
   const loginCalls: string[] = [];
   const streamedOptions: any[] = [];
+  // Plain Error, no typed .status: the default-slot path still recognizes invalid_grant
+  // from the message text.
   rotationModule.__setRefreshForProviderForTest(async (providerId) => {
     if (providerId === "anthropic") {
-      throw Object.assign(new Error('HTTP request failed. status=400; body={"error":"invalid_grant","error_description":"Refresh token not found or invalid"}'), { status: 400 });
+      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");
   });
@@ -816,11 +1332,8 @@ test("automatically reauthenticates invalid refresh tokens when UI is available"
   }
 });
 
-// Regression (#123): a resolved-but-unauthenticated fallback used to still get switched
-// to blindly (the session model would flip to a provider nobody logged into) before
-// finally giving up. Neither provider has ever been authenticated here at all, so there
-// is nothing viable to switch to -- it must NOT touch the session model, and the terminal
-// message must be actionable ("not authenticated") rather than a generic exhaustion notice.
+// 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 () => {
   resetRotationState();
   writeLadderConfig();
@@ -840,16 +1353,8 @@ test("emits an actionable 'not authenticated' error without switching models whe
   assert.match(emitted[0].error.errorMessage, /OpenAI Codex not authenticated.*crtr sys setup/);
 });
 
-// Regression: a config-less user (fresh install, no ~/.crouter/config.json at all —
-// the common case) used to have `readModelLadders()` return nothing, so the moment
-// the (empty) Anthropic pool needed a fallback hop, resolution failed with "Unable to
-// resolve fallback model for strength strong; configure a openai ladder in
-// ~/.crouter/config.json". `readModelLadders()` now always falls back to crouter's
-// builtin anthropic/openai ladder (mirroring what crtr itself launches nodes with), so
-// the hop resolves to a real target -- but this user genuinely has no working OpenAI
-// credentials either, so (#123) it must degrade to an actionable "not authenticated"
-// terminal error WITHOUT ever switching the session model to that unauthed target, never
-// the raw config error.
+// The builtin ladder is available even with no ~/.crouter/config.json, so a config-less
+// user can still resolve cross-provider fallbacks.
 test("degrades gracefully via the builtin ladder when a config-less user has no cross-provider credentials", async () => {
   resetRotationState();
   rmSync(join(home, ".crouter", "config.json"), { force: true });
@@ -889,7 +1394,7 @@ test("degrades gracefully via the builtin ladder when a config-less user has no
   // 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
   // never authenticated either (#123 gates fallback on the target actually being authed),
-  // so it must NOT switch the session model to it -- straight to an actionable message.
+  // so the session model stays unchanged and the turn returns an actionable message.
   const stream = providers["anthropic"].streamSimple(ctx.model, ctx);
   const emitted = [] as any[];
   for await (const event of stream) emitted.push(event);
@@ -901,14 +1406,7 @@ test("degrades gracefully via the builtin ladder when a config-less user has no
   assert.ok(!emitted[0].error.errorMessage.includes("configure a openai ladder"));
 });
 
-// Regression: this is the actual root-cause fix — `readModelLadders()` used to read
-// ONLY the literal ~/.crouter/config.json with no builtin default, so a config-less
-// user (fresh install, only logged into Anthropic) saw an EMPTY ladder even though
-// crtr itself launches nodes on the builtin anthropic/openai defaults
-// (`defaultModelLaddersConfig()` in src/types.ts). Prove the builtin ladder resolves
-// on its own, with no config.json present at all: the current model's own strength tier
-// (medium = claude-sonnet-5) must match, and a same-strength cross-provider target
-// must resolve without throwing.
+// 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", () => {
   resetRotationState();
   rmSync(join(home, ".crouter", "config.json"), { force: true });
@@ -924,16 +1422,13 @@ test("resolves the builtin anthropic ladder (medium = sonnet-5) with no ~/.crout
   });
 });
 
-// Regression (#123a): a SOLE authenticated provider that is merely cooling down (its one
-// credential is rate-limited, but not permanently broken) used to jump straight to a
-// fallback/terminal failure the instant its pool went empty, instead of waiting out the
-// (short) remaining cooldown. With no OpenAI credentials at all to fall back to, it must
-// sleep out the shortest rateLimitedUntil and retry the SAME provider -- and succeed.
+// A sole provider that is merely cooling down waits out the cooldown when no authenticated
+// fallback exists.
 test("waits out a sole provider's cooldown and retries it when no authenticated fallback exists", async () => {
   resetRotationState();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
-  helpers.markSubscriptionRateLimited("anthropic", "anthropic", 30_000);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
+  helpers.markSubscriptionRateLimited("anthropic", "primary", 30_000);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
   ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
@@ -973,15 +1468,13 @@ test("waits out a sole provider's cooldown and retries it when no authenticated
   }
 });
 
-// Regression (#123b): a cooldown long enough that it isn't worth an automatic wait (e.g.
-// the 30-day invalid-refresh-token backoff also lands in `rateLimitedUntil`) must NOT be
-// slept out -- it needs reauth, not patience. It must fall through to an actionable
-// terminal error instead, and must never call the sleep seam at all.
+// Cooldowns longer than the sole-provider wait cap return an actionable error instead of
+// sleeping.
 test("does not wait out a cooldown longer than the sole-provider wait cap; surfaces an actionable error instead", async () => {
   resetRotationState();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
-  helpers.markSubscriptionRateLimited("anthropic", "anthropic", 30 * 24 * 60 * 60 * 1000);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
+  helpers.markSubscriptionRateLimited("anthropic", "primary", 30 * 24 * 60 * 60 * 1000);
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
   ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
@@ -1010,19 +1503,11 @@ test("does not wait out a cooldown longer than the sole-provider wait cap; surfa
   }
 });
 
-// Regression (review of 10c72d4, Bug 1): the wait-out decision used to be computed from
-// the `rawPool` snapshot taken BEFORE the credential loop ran, not from the pool the loop
-// just mutated via `markSubscriptionRateLimited`. So when the SOLE credential gets rate-
-// limited in THIS SAME call (as opposed to having been pre-marked before the turn even
-// started, like the #123a test above), the stale snapshot still shows `rateLimitedUntil: 0`
-// for every entry, `Math.min(...)` comes out to 0, `waitMs` goes negative, and the code
-// falls straight through to "All managed provider pools exhausted" instead of sleeping out
-// the (short) real cooldown. Proves the fix: a fresh 429 with Retry-After: 1s on the only
-// credential, no authenticated fallback, must sleep and retry -- never emit exhaustion.
+// 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();
   writeLadderConfig();
-  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  helpers.writeSubscriptionPool("anthropic", [credential("primary")]);
   // openai-codex pool stays empty -- no authenticated fallback to switch to.
 
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
@@ -1057,9 +1542,9 @@ test("waits out a sole credential's cooldown observed in THIS turn, not a stale
     const emitted = [] as any[];
     for await (const event of stream) emitted.push(event);
 
-    // Never switches providers -- there is nothing authenticated to switch to.
+    // No authenticated fallback exists, so the provider stays put and the turn waits once.
     assert.deepEqual(setModelCalls, []);
-    // The bug: it used to skip straight to "exhausted" without ever sleeping.
+    // The current-turn cooldown path sleeps before retrying.
     assert.equal(sleepCalls.length, 1);
     assert.ok(sleepCalls[0] > 0 && sleepCalls[0] <= 1000);
     assert.equal(anthropicCalls, 2);
@@ -1071,12 +1556,9 @@ test("waits out a sole credential's cooldown observed in THIS turn, not a stale
   }
 });
 
-// Regression (review of 10c72d4, Bug 2): pi-ai's Codex adapter can surface a genuine
-// usage-limit exhaustion (`usage_limit_reached` / "You have hit your ChatGPT usage
-// limit...") on a NON-429 status. The classifier used to only recognize 429/503-with-
-// retry-after or `rate.?limit|too many requests` text, so this landed in the `fatal`
-// bucket -- it neither cooled the credential down nor rotated to the authenticated
-// fallback. Prove it now cools down AND falls back transparently, serving the same turn.
+// pi-ai's Codex adapter can surface a genuine usage-limit exhaustion on a non-429
+// status, and the classifier treats it as a rate limit so the credential cools down and
+// the authenticated fallback serves the same turn.
 test("treats a Codex usage-limit message on a non-429 status as a rate limit: cools down and falls back", async () => {
   resetRotationState();
   writeLadderConfig();