@crouton-kit/crouter 0.3.39 → 0.3.41

package/dist/build-root.js

@@ -18,6 +18,7 @@ const SUBTREE_LOADERS = {
     push: async () => (await import('./commands/push.js')).registerPush(),
     canvas: async () => (await import('./commands/canvas.js')).registerCanvas(),
     surface: async () => (await import('./commands/surface.js')).registerSurface(),
+    worktree: async () => (await import('./commands/worktree.js')).registerWorktree(),
 };
 /** Every shipped subtree name. Cheap (no module loading) — the front-door
  *  recursion guard and the dispatcher's first-token routing need only names. */

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

@@ -503,7 +503,12 @@ test("falls back transparently and serves the turn on Anthropic when Codex is ex
   }
 });
 
-test("treats request timeouts as fallback-like and serves the turn on the fallback provider", async () => {
+// 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.
+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")]);
@@ -512,11 +517,121 @@ test("treats request timeouts as fallback-like and serves the turn on the fallba
   const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
   ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
   const streamedModels: any[] = [];
+  const sleepCalls: number[] = [];
+  let anthropicCalls = 0;
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+  });
   rotationModule.__setStreamForProviderForTest((model) => {
     streamedModels.push(model);
     return (async function* () {
       if (model.provider === "anthropic") {
-        yield { type: "error", error: Object.assign(new Error("Request timed out."), { errorMessage: "Request timed out." }) };
+        anthropicCalls += 1;
+        if (anthropicCalls === 1) {
+          yield { type: "error", error: Object.assign(new Error("Request timed out."), { errorMessage: "Request timed out." }) };
+          return;
+        }
+        yield { type: "text_delta", text: "hello from anthropic, second try" };
+        return;
+      }
+      yield { type: "text_delta", text: "hello from codex" };
+    })() 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);
+
+    // Never switched providers or models -- both attempts stayed on anthropic.
+    assert.deepEqual(setModelCalls, []);
+    assert.deepEqual(streamedModels.map((m) => m.provider), ["anthropic", "anthropic"]);
+    assert.deepEqual(sleepCalls, [250]);
+    assert.ok(emitted.some((e) => e.type === "text_delta"));
+    assert.ok(!emitted.some((e) => e.type === "error"));
+    // No cooldown -- a transient blip must never cool down a healthy subscription.
+    assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 0);
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+// Regression: when a transient blip never recovers, the turn must end with a clear,
+// actionable error instead of spinning forever or silently rotating a healthy credential
+// away to a fallback provider that was never the actual problem.
+test("ends the turn without rotating once the transient retry budget is exhausted", async () => {
+  resetRotationState();
+  writeLadderConfig();
+  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  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" };
+  const streamedModels: any[] = [];
+  const sleepCalls: number[] = [];
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+  });
+  rotationModule.__setStreamForProviderForTest((model) => {
+    streamedModels.push(model);
+    return (async function* () {
+      // 503 with no retry-after header is transient by STATUS, not just by message.
+      yield { type: "error", error: Object.assign(new Error("Service Unavailable"), { status: 503 }) };
+    })() 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(setModelCalls, []);
+    assert.deepEqual(streamedModels.map((m) => m.provider), ["anthropic", "anthropic", "anthropic"]);
+    assert.deepEqual(sleepCalls, [250, 750]);
+    assert.equal(emitted.length, 1);
+    assert.equal(emitted[0].type, "error");
+    assert.match(emitted[0].error.errorMessage, /transient error after 3 attempts/);
+    assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 0);
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+// Regression: a genuine rate limit (HTTP 429) must never get the transient in-place
+// retry treatment -- it cools the credential down and rotates on the FIRST failure. The
+// cooldown duration must reflect a real Retry-After header (5s here) rather than always
+// falling back to the 5-minute default, so a misclassification is obvious from the numbers.
+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("openai-codex", [credential("codex")]);
+
+  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
+  const streamedModels: any[] = [];
+  const sleepCalls: number[] = [];
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+  });
+  rotationModule.__setStreamForProviderForTest((model, _context, options) => {
+    streamedModels.push(model);
+    return (async function* () {
+      if (model.provider === "anthropic") {
+        await options?.onResponse?.({ status: 429, headers: { "retry-after": "5" } }, model);
+        yield { type: "error", error: Object.assign(new Error("Too Many Requests"), { status: 429 }) };
         return;
       }
       yield { type: "text_delta", text: "hello from codex" };
@@ -533,11 +648,70 @@ test("treats request timeouts as fallback-like and serves the turn on the fallba
     const emitted = [] as any[];
     for await (const event of stream) emitted.push(event);
 
+    assert.equal(streamedModels.filter((m) => m.provider === "anthropic").length, 1);
+    assert.deepEqual(sleepCalls, []); // a genuine rate limit rotates immediately, it never sleeps in place
     assert.deepEqual(setModelCalls.map((m) => m.provider), ["openai-codex"]);
-    assert.deepEqual(streamedModels.map((m) => m.provider), ["anthropic", "openai-codex"]);
     assert.ok(emitted.some((e) => e.type === "text_delta"));
     assert.ok(!emitted.some((e) => e.type === "error"));
-    assert.ok(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil > Date.now());
+    const [entry] = helpers.readSubscriptionPool("anthropic");
+    // Retry-After: 5 -> ~5s cooldown, not the 5-minute default backoff.
+    assert.ok(entry.rateLimitedUntil > Date.now() + 4_000 && entry.rateLimitedUntil <= Date.now() + 5_000);
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+test("does not cool down credentials or switch providers when the user aborts", async () => {
+  resetRotationState();
+  writeLadderConfig();
+  helpers.writeSubscriptionPool("anthropic", [credential("anthropic")]);
+  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" };
+  const streamedModels: any[] = [];
+  rotationModule.__setStreamForProviderForTest((model) => {
+    streamedModels.push(model);
+    return (async function* () {
+      yield {
+        type: "error",
+        reason: "aborted",
+        error: {
+          role: "assistant",
+          content: [],
+          api: model.api,
+          provider: model.provider,
+          model: model.id,
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+          stopReason: "aborted",
+          errorMessage: "Request was aborted",
+          timestamp: Date.now(),
+        },
+      };
+    })() as any;
+  });
+
+  try {
+    await providerRotationExtension(pi);
+    await events.session_start?.({}, ctx);
+    // No AbortSignal is threaded through options here on purpose: the abort must be recognized
+    // from the event's own `reason: "aborted"` marker alone. Requiring the signal is exactly the
+    // regression that let an ESC cool down every credential and drain both provider pools.
+    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(streamedModels.map((m) => m.provider), ["anthropic"]);
+    assert.equal(emitted.length, 1);
+    assert.equal(emitted[0].type, "error");
+    assert.equal(emitted[0].reason, "aborted");
+    assert.equal(helpers.readSubscriptionPool("anthropic")[0].rateLimitedUntil, 0);
+    assert.equal(helpers.readSubscriptionPool("openai-codex")[0].rateLimitedUntil, 0);
   } finally {
     rotationModule.__setStreamForProviderForTest(undefined);
   }
@@ -642,7 +816,12 @@ test("automatically reauthenticates invalid refresh tokens when UI is available"
   }
 });
 
-test("emits a single terminal error only when BOTH provider pools are exhausted", async () => {
+// 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.
+test("emits an actionable 'not authenticated' error without switching models when neither provider has ever logged in", async () => {
   resetRotationState();
   writeLadderConfig();
 
@@ -654,10 +833,294 @@ test("emits a single terminal error only when BOTH provider pools are exhausted"
   const emitted = [] as any[];
   for await (const event of stream) emitted.push(event);
 
-  // It still switches the session model toward the fallback before giving up.
-  assert.deepEqual(setModelCalls.map((m) => m.provider), ["anthropic"]);
-  // No ping-pong: a single terminal error naming both exhausted providers.
+  // Never switches to the unauthenticated fallback -- nothing to try it with.
+  assert.deepEqual(setModelCalls, []);
+  assert.equal(emitted.length, 1);
+  assert.equal(emitted[0].type, "error");
+  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.
+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 });
+
+  const ctx = {
+    model: { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" },
+    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" };
+        return undefined;
+      },
+    },
+  } as any;
+  const setModelCalls: any[] = [];
+  const providers: Record<string, { streamSimple: (...args: any[]) => AsyncIterable<any> }> = {};
+  const events: Record<string, (...args: any[]) => unknown> = {};
+  const pi = {
+    registerProvider(name: string, provider: { streamSimple: (...args: any[]) => AsyncIterable<any> }) {
+      providers[name] = provider;
+    },
+    registerCommand() {},
+    on(eventName: string, handler: (...args: any[]) => unknown) {
+      events[eventName] = handler;
+    },
+    async setModel(model: any) {
+      setModelCalls.push(model);
+      ctx.model = model;
+      return true;
+    },
+    setThinkingLevel() {},
+  } as any;
+
+  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
+  // 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.
+  const stream = providers["anthropic"].streamSimple(ctx.model, ctx);
+  const emitted = [] as any[];
+  for await (const event of stream) emitted.push(event);
+
+  assert.deepEqual(setModelCalls, []);
   assert.equal(emitted.length, 1);
   assert.equal(emitted[0].type, "error");
-  assert.equal(emitted[0].error.errorMessage, "All managed provider pools exhausted (tried openai-codex, anthropic)");
+  assert.match(emitted[0].error.errorMessage, /Claude not authenticated.*crtr sys setup/);
+  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.
+test("resolves the builtin anthropic ladder (medium = sonnet-5) 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");
+
+  assert.deepEqual(target, {
+    providerId: "openai-codex",
+    modelId: "gpt-5.5",
+    label: "openai-codex/gpt-5.5:medium",
+    strength: "medium",
+    thinkingLevel: "medium",
+  });
+});
+
+// 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.
+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);
+
+  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
+  const sleepCalls: number[] = [];
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+    // Simulate the cooldown having elapsed by the time the wait completes, rather than
+    // actually sleeping in the test.
+    const pool = helpers.readSubscriptionPool("anthropic");
+    helpers.writeSubscriptionPool("anthropic", pool.map((entry) => ({ ...entry, rateLimitedUntil: 0 })));
+  });
+  rotationModule.__setStreamForProviderForTest((model) => {
+    return (async function* () {
+      yield { type: "text_delta", text: `hello from ${model.provider} after waiting` };
+    })() 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);
+
+    // Never switched away from anthropic -- it waited, then retried the same provider.
+    assert.deepEqual(setModelCalls, []);
+    assert.equal(sleepCalls.length, 1);
+    assert.ok(sleepCalls[0] > 0 && sleepCalls[0] <= 30_000);
+    assert.ok(emitted.some((e) => e.type === "text_delta"));
+    assert.ok(!emitted.some((e) => e.type === "error"));
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+// 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.
+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);
+
+  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
+  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, /Claude cooling down for .*too long to wait automatically/);
+  } finally {
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+// 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.
+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")]);
+  // openai-codex pool stays empty -- no authenticated fallback to switch to.
+
+  const { ctx, setModelCalls, providers, events, pi } = makeRotationCtx();
+  ctx.model = { provider: "anthropic", id: "claude-opus-4-8", api: "anthropic-messages" };
+  const sleepCalls: number[] = [];
+  let anthropicCalls = 0;
+  rotationModule.__setSleepForTest(async (ms) => {
+    sleepCalls.push(ms);
+    // Simulate the 1s retry-after cooldown having elapsed by the time the wait completes.
+    const pool = helpers.readSubscriptionPool("anthropic");
+    helpers.writeSubscriptionPool("anthropic", pool.map((entry) => ({ ...entry, rateLimitedUntil: 0 })));
+  });
+  rotationModule.__setStreamForProviderForTest((model, _context, options) => {
+    return (async function* () {
+      anthropicCalls += 1;
+      if (anthropicCalls === 1) {
+        await options?.onResponse?.({ status: 429, headers: { "retry-after": "1" } }, model);
+        yield { type: "error", error: Object.assign(new Error("Too Many Requests"), { status: 429 }) };
+        return;
+      }
+      yield { type: "text_delta", text: "hello from anthropic after waiting out a same-turn 429" };
+    })() 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);
+
+    // Never switches providers -- there is nothing authenticated to switch to.
+    assert.deepEqual(setModelCalls, []);
+    // The bug: it used to skip straight to "exhausted" without ever sleeping.
+    assert.equal(sleepCalls.length, 1);
+    assert.ok(sleepCalls[0] > 0 && sleepCalls[0] <= 1000);
+    assert.equal(anthropicCalls, 2);
+    assert.ok(emitted.some((e) => e.type === "text_delta"));
+    assert.ok(!emitted.some((e) => e.type === "error"));
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+    rotationModule.__setSleepForTest(undefined);
+  }
+});
+
+// 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.
+test("treats a Codex usage-limit message on a non-429 status as a rate limit: cools down and falls back", async () => {
+  resetRotationState();
+  writeLadderConfig();
+  helpers.writeSubscriptionPool("openai-codex", [credential("codex")]);
+  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" };
+  const streamedModels: any[] = [];
+  rotationModule.__setStreamForProviderForTest((model) => {
+    streamedModels.push(model);
+    return (async function* () {
+      if (model.provider === "openai-codex") {
+        yield {
+          type: "error",
+          error: Object.assign(new Error("You have hit your ChatGPT usage limit. Please try again later."), {
+            status: 403,
+            errorMessage: "You have hit your ChatGPT usage limit. usage_limit_reached",
+          }),
+        };
+        return;
+      }
+      yield { type: "text_delta", text: "hello from anthropic fallback" };
+    })() as any;
+  });
+
+  try {
+    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" },
+      ctx,
+    );
+    const emitted = [] as any[];
+    for await (const event of stream) emitted.push(event);
+
+    // Cooled the Codex credential down instead of leaving it fatally dead.
+    assert.ok(helpers.readSubscriptionPool("openai-codex")[0].rateLimitedUntil > Date.now());
+    // Fell back to the authenticated Anthropic subscription and served the turn on it.
+    assert.deepEqual(setModelCalls.map((m) => m.provider), ["anthropic"]);
+    assert.equal(streamedModels.filter((m) => m.provider === "anthropic").length, 1);
+    assert.ok(emitted.some((e) => e.type === "text_delta"));
+    assert.ok(!emitted.some((e) => e.type === "error"));
+  } finally {
+    rotationModule.__setStreamForProviderForTest(undefined);
+  }
 });