opencode-anthropic-fix 0.1.31 → 0.2.0

package/lib/mimicry/system-prompt.test.mjs

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildSystemPromptBlocks,
+  dedupeSystemBlocks,
+  getCacheControlForScope,
+  getCachedCCPrompt,
+  isTitleGeneratorSystemBlocks,
+  resetCachedCCPrompt,
+  sanitizeSystemText,
+  tailSystemBlock,
+} from "./system-prompt.mjs";
+
+describe("system prompt mimicry", () => {
+  it("sanitizes OpenCode branding with the existing case rules", () => {
+    expect(sanitizeSystemText("OpenCode opencode openCode opencode_helper")).toBe(
+      "Claude Code Claude Claude opencode_helper",
+    );
+  });
+
+  it("removes duplicate normalized text blocks", () => {
+    const first = { type: "text", text: "First line\nSecond line" };
+    const duplicate = { type: "text", text: " First line \r\n Second line " };
+    const unique = { type: "text", text: "Unique" };
+
+    expect(dedupeSystemBlocks([first, duplicate, unique])).toEqual([first, unique]);
+  });
+
+  it("tails a system block while retaining key constraints", () => {
+    expect(tailSystemBlock("Identity\n\ndiscard this\n# Keep\nMUST remain", 200, 3)).toBe(
+      "Identity\n\n# Keep\nMUST remain\n\n[Verbose instructions trimmed after turn 3. Key constraints preserved above.]",
+    );
+  });
+
+  it("detects title-generator system blocks", () => {
+    expect(isTitleGeneratorSystemBlocks([{ type: "text", text: "You are a title generator." }])).toBe(true);
+    expect(isTitleGeneratorSystemBlocks([{ type: "text", text: "You are a coding assistant." }])).toBe(false);
+  });
+
+  it("builds cache-control wire shapes for each scope", () => {
+    const policy = { ttl: "1h", ttl_supported: true };
+
+    expect(getCacheControlForScope("global", policy)).toEqual({ type: "ephemeral", ttl: "1h", scope: "global" });
+    expect(getCacheControlForScope("org", policy)).toEqual({ type: "ephemeral", ttl: "1h" });
+    expect(getCacheControlForScope(null, policy)).toBeNull();
+    expect(getCacheControlForScope("org", { ttl: "off", ttl_supported: true })).toEqual({ type: "ephemeral" });
+  });
+
+  it("builds system prompt blocks from a minimal prompt and signature", () => {
+    expect(
+      buildSystemPromptBlocks([{ type: "text", text: "OpenCode assistant" }], {
+        enabled: false,
+        claudeCliVersion: "2.1.0",
+        promptCompactionMode: "off",
+      }),
+    ).toEqual([{ type: "text", text: "Claude Code assistant" }]);
+  });
+
+  it("exposes cache reset and round-trip helpers", () => {
+    resetCachedCCPrompt();
+    expect(getCachedCCPrompt()).toBeNull();
+
+    buildSystemPromptBlocks([{ type: "text", text: "You are an interactive assistant." }], {
+      enabled: true,
+      claudeCliVersion: "2.1.0",
+      promptCompactionMode: "off",
+      cachePolicy: { ttl: "1h", ttl_supported: true },
+    });
+
+    expect(getCachedCCPrompt()).toBe("You are an interactive assistant.");
+    resetCachedCCPrompt();
+    expect(getCachedCCPrompt()).toBeNull();
+  });
+});

package/lib/oauth.mjs

@@ -58,7 +58,7 @@ function generatePKCE() {
 /**
  * Resolve whether the SDK-native-fetch token fingerprint should be used.
  * An explicit boolean override (used by callers/tests) wins; otherwise the
- * live `oauth.sdk_token_useragent` config flag is read (default false).
+ * live `oauth.sdk_token_useragent` config flag is read (default true).
  * @param {boolean | undefined} override
  * @returns {boolean}
  */

package/lib/oauth.test.mjs

@@ -13,7 +13,7 @@ describe("oauth headers", () => {
     vi.unstubAllGlobals();
   });
 
-  it("sends Claude Code user-agent on token exchange", async () => {
+  it("sends SDK native-fetch fingerprint by default on token exchange", async () => {
     mockFetch.mockResolvedValueOnce({
       ok: false,
       status: 400,
@@ -23,10 +23,12 @@ describe("oauth headers", () => {
     await exchange("code#state", "verifier");
 
     const [, init] = mockFetch.mock.calls[0];
-    expect(init.headers["User-Agent"]).toBe("axios/1.13.6");
+    expect(init.headers["User-Agent"]).toBe("anthropic-sdk-typescript/0.94.0 userOAuthProvider");
+    expect(init.headers["anthropic-beta"]).toBe("oauth-2025-04-20");
+    expect("Accept" in init.headers).toBe(false);
   });
 
-  it("sends Claude Code user-agent on token refresh", async () => {
+  it("sends SDK native-fetch fingerprint by default on token refresh", async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
       json: async () => ({ access_token: "a", refresh_token: "r", expires_in: 3600 }),
@@ -35,7 +37,9 @@ describe("oauth headers", () => {
     await refreshToken("refresh-token");
 
     const [, init] = mockFetch.mock.calls[0];
-    expect(init.headers["User-Agent"]).toBe("axios/1.13.6");
+    expect(init.headers["User-Agent"]).toBe("anthropic-sdk-typescript/0.94.0 userOAuthProvider");
+    expect(init.headers["anthropic-beta"]).toBe("oauth-2025-04-20");
+    expect("Accept" in init.headers).toBe(false);
   });
 
   it("sends Claude Code user-agent on token revoke", async () => {

package/lib/redact.mjs

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+
+const HASH_MASK_PATTERN = /^\[redacted sha256:[0-9a-f]{12}\]$/;
+const AUTH_HASH_MASK_PATTERN = /^[A-Za-z][A-Za-z0-9_-]* \[redacted sha256:[0-9a-f]{12}\]$/;
+const WHOLE_VALUE_KEYS = new Set(["cookie", "set-cookie", "x-api-key", "api-key"]);
+const SECRET_KEYS = new Set(["access", "refreshtoken", "refresh_token", "token", "client_secret", "code", "id_token"]);
+
+function safeString(value) {
+  try {
+    return String(value);
+  } catch {
+    return "[unprintable secret]";
+  }
+}
+
+function hashMask(value) {
+  const stringValue = safeString(value);
+  if (HASH_MASK_PATTERN.test(stringValue)) return stringValue;
+
+  try {
+    const hash = createHash("sha256").update(stringValue).digest("hex").slice(0, 12);
+    return `[redacted sha256:${hash}]`;
+  } catch {
+    return "[redacted]";
+  }
+}
+
+function redactAuthorization(value) {
+  const stringValue = safeString(value);
+  if (AUTH_HASH_MASK_PATTERN.test(stringValue) || HASH_MASK_PATTERN.test(stringValue)) return stringValue;
+
+  const scheme = stringValue.match(/^([A-Za-z][A-Za-z0-9_-]*)\s+/)?.[1];
+  const mask = hashMask(stringValue);
+  return scheme ? `${scheme} ${mask}` : mask;
+}
+
+function redactEmail(value) {
+  const stringValue = safeString(value);
+  if (/^a\*\*\*@[^@]+$/.test(stringValue)) return stringValue;
+
+  const separator = stringValue.lastIndexOf("@");
+  if (separator <= 0 || separator === stringValue.length - 1) return hashMask(stringValue);
+  return `a***${stringValue.slice(separator)}`;
+}
+
+function redactValueForKey(key, value) {
+  const normalizedKey = key.toLowerCase();
+  if (normalizedKey === "authorization" || normalizedKey === "proxy-authorization") {
+    return redactAuthorization(value);
+  }
+  if (WHOLE_VALUE_KEYS.has(normalizedKey) || SECRET_KEYS.has(normalizedKey)) return hashMask(value);
+  if (normalizedKey === "email") return redactEmail(value);
+  return undefined;
+}
+
+/**
+ * Return a deep-cloned, logging-safe copy of a value.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function redactSecrets(value) {
+  try {
+    const seen = new WeakMap();
+
+    const clone = (current) => {
+      if (typeof current === "string") return redactString(current);
+      if (current === null || typeof current !== "object") return current;
+      if (seen.has(current)) return seen.get(current);
+
+      let output;
+      try {
+        if (current instanceof Date) return new Date(current.getTime());
+        if (current instanceof RegExp) return new RegExp(current.source, current.flags);
+        output = Array.isArray(current) ? [] : {};
+      } catch {
+        return "[unavailable object]";
+      }
+
+      seen.set(current, output);
+
+      let keys;
+      try {
+        keys = Object.keys(current);
+      } catch {
+        return output;
+      }
+
+      for (const key of keys) {
+        let child;
+        try {
+          child = current[key];
+        } catch {
+          child = "[unavailable value]";
+        }
+
+        const redacted = redactValueForKey(key, child);
+        const clonedValue = redacted === undefined ? clone(child) : redacted;
+        try {
+          Object.defineProperty(output, key, {
+            value: clonedValue,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        } catch {
+          // A hostile object key must not prevent the remaining values from being redacted.
+        }
+      }
+
+      return output;
+    };
+
+    return clone(value);
+  } catch {
+    return "[redaction failed]";
+  }
+}
+
+/**
+ * Redact a plain request or response header map.
+ *
+ * @param {Record<string, unknown>} headersObj
+ * @returns {unknown}
+ */
+export function redactHeaders(headersObj) {
+  return redactSecrets(headersObj);
+}
+
+/**
+ * Scrub token-shaped values from a free-form diagnostic string.
+ *
+ * @param {unknown} str
+ * @returns {string}
+ */
+export function redactString(str) {
+  try {
+    return safeString(str)
+      .replace(/Bearer(\s+|%20)([A-Za-z0-9._-]+)/gi, (_match, separator, credential) => {
+        return `Bearer${separator}${hashMask(credential)}`;
+      })
+      .replace(/sk-ant-[A-Za-z0-9._-]+/gi, (token) => hashMask(token))
+      .replace(/\boat01[A-Za-z0-9._-]{8,}\b/gi, (token) => hashMask(token));
+  } catch {
+    return "[redaction failed]";
+  }
+}

package/lib/redact.test.mjs

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+import { redactHeaders, redactSecrets, redactString } from "./redact.mjs";
+
+describe("redactSecrets", () => {
+  it("masks authorization without retaining token content", () => {
+    const token = "sk-ant-oat01-XXXX";
+    const input = { Authorization: `Bearer ${token}` };
+    const result = redactHeaders(input);
+
+    expect(result.Authorization).toMatch(/^Bearer \[redacted sha256:[0-9a-f]{12}\]$/);
+    expect(result.Authorization).not.toContain(token);
+    expect(input.Authorization).toBe(`Bearer ${token}`);
+  });
+
+  it("masks cookie and API key header values", () => {
+    const result = redactHeaders({ "set-cookie": "session=secret", "x-api-key": "key-secret" });
+
+    expect(result["set-cookie"]).toMatch(/^\[redacted sha256:[0-9a-f]{12}\]$/);
+    expect(result["x-api-key"]).toMatch(/^\[redacted sha256:[0-9a-f]{12}\]$/);
+    expect(result["set-cookie"]).not.toContain("session=secret");
+    expect(result["x-api-key"]).not.toContain("key-secret");
+  });
+
+  it("masks nested account credentials", () => {
+    const input = { account: { refreshToken: "refresh-secret", access: "access-secret" } };
+    const result = redactSecrets(input);
+
+    expect(result.account.refreshToken).toMatch(/^\[redacted sha256:[0-9a-f]{12}\]$/);
+    expect(result.account.access).toMatch(/^\[redacted sha256:[0-9a-f]{12}\]$/);
+    expect(result).not.toBe(input);
+    expect(result.account).not.toBe(input.account);
+  });
+
+  it("leaves mimicry fingerprint headers byte-identical", () => {
+    const input = {
+      "anthropic-beta": "oauth-2025-04-20,prompt-caching-2024-07-31",
+      "user-agent": "claude-cli/2.1.0 (external, cli)",
+      "x-stainless-arch": "x64",
+      "anthropic-version": "2023-06-01",
+    };
+
+    expect(redactHeaders(input)).toEqual(input);
+  });
+
+  it("leaves generic non-secret fields intact", () => {
+    const input = {
+      model: "claude-sonnet-4-5",
+      temperature: 0.7,
+      user: "alice",
+      messages: [{ role: "user", content: "hi" }],
+    };
+
+    expect(redactSecrets(input)).toEqual(input);
+  });
+
+  it("masks an email local part and preserves its domain", () => {
+    expect(redactSecrets({ email: "marco@example.com" })).toEqual({ email: "a***@example.com" });
+  });
+
+  it("is idempotent", () => {
+    const input = {
+      authorization: "Bearer secret-token",
+      account: { refresh_token: "refresh-secret", email: "marco@example.com" },
+    };
+    const once = redactSecrets(input);
+
+    expect(redactSecrets(once)).toEqual(once);
+  });
+
+  it("handles null, undefined, circular, and large objects without throwing", () => {
+    const circular = { token: "secret" };
+    circular.self = circular;
+    const large = Object.fromEntries(Array.from({ length: 10_000 }, (_, index) => [`key${index}`, `value${index}`]));
+    const redactedCircular = redactSecrets(circular);
+    const redactedLarge = redactSecrets(large);
+
+    expect(() => redactSecrets(null)).not.toThrow();
+    expect(() => redactSecrets(undefined)).not.toThrow();
+    expect(() => redactSecrets(circular)).not.toThrow();
+    expect(() => redactSecrets(large)).not.toThrow();
+    expect(redactedCircular.self).toBe(redactedCircular);
+    expect(Object.keys(redactedLarge)).toHaveLength(10_000);
+  });
+
+  it("grep-proof: no known secret survives redactSecrets over a realistic header+body fixture", () => {
+    const fakeSecrets = {
+      bearer: "sk-ant-FAKEAUTH123.def-456",
+      cookie: "session=FAKECOOKIE123",
+      apiKey: "FAKEAPIKEY123",
+      refreshToken: "FAKEREFRESH123",
+      access: "FAKEACCESS123",
+      code: "FAKECODE123",
+      email: "fake.user@example.test",
+      oauthToken: "oat01FAKEOAUTH12345",
+    };
+    const fixture = {
+      headers: {
+        authorization: `Bearer ${fakeSecrets.bearer}`,
+        cookie: fakeSecrets.cookie,
+        "x-api-key": fakeSecrets.apiKey,
+        "x-stainless-lang": "js",
+      },
+      body: {
+        account: {
+          refreshToken: fakeSecrets.refreshToken,
+          access: fakeSecrets.access,
+          code: fakeSecrets.code,
+          email: fakeSecrets.email,
+        },
+        callbackUrl: `https://auth.example.test/callback?token=${fakeSecrets.oauthToken}`,
+      },
+    };
+
+    const serialized = JSON.stringify(redactSecrets(fixture));
+
+    expect(serialized).not.toMatch(/Bearer\s+[A-Za-z0-9._-]{6,}/);
+    expect(serialized).not.toMatch(/sk-ant-[A-Za-z0-9]{6,}/);
+    expect(serialized).not.toMatch(/\boat01[A-Za-z0-9]{8,}/);
+    for (const secret of Object.values(fakeSecrets)) {
+      expect(serialized).not.toContain(secret);
+    }
+    expect(serialized).toContain('"x-stainless-lang":"js"');
+  });
+});
+
+describe("redactString", () => {
+  it("removes bearer token markers from body dumps", () => {
+    const result = redactString("prefix Bearer sk-ant-oat01-abc.def suffix");
+
+    expect(result).not.toContain("sk-ant");
+    expect(result).not.toContain("oat01");
+    expect(result).toMatch(/Bearer \[redacted sha256:[0-9a-f]{12}\]/);
+  });
+
+  it("redacts a bearer/sk-ant/oat01 token embedded mid-string in a URL", () => {
+    const bearerCredential = "abc.def-123";
+    const skAntToken = "sk-ant-abc123.def-456";
+    const oauthToken = "oat01ABCDEFGH12345";
+    const bearerResult = redactString(`https://api.example.com/cb?x=1#Authorization=Bearer%20${bearerCredential}`);
+    const skAntResult = redactString(`prefix ${skAntToken} suffix`);
+    const oauthResult = redactString(`https://auth.example.com/cb#token=...${oauthToken}...`);
+
+    for (const [result, rawToken] of [
+      [bearerResult, bearerCredential],
+      [skAntResult, skAntToken],
+      [oauthResult, oauthToken],
+    ]) {
+      expect(result).not.toContain(rawToken);
+      expect(result).toMatch(/\[redacted sha256:[0-9a-f]{12}\]/);
+    }
+    expect(bearerResult).toContain("https://api.example.com/cb?x=1#Authorization=Bearer%20");
+    expect(oauthResult).toContain("https://auth.example.com/cb#token=...");
+  });
+});

package/lib/refresh-lock.test.mjs

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+const itPosix = process.platform === "win32" ? it.skip : it;
 const baseDir = join(tmpdir(), `opencode-refresh-lock-test-${process.pid}`);
 const storagePath = join(baseDir, "anthropic-accounts.json");
 
@@ -22,6 +23,57 @@ describe("refresh-lock", () => {
     await fs.rm(baseDir, { recursive: true, force: true });
   });
 
+  it("acquires the lock on the first attempt", async () => {
+    const lock = await acquireRefreshLock("acc-first-acquire");
+
+    expect(lock.acquired).toBe(true);
+    expect(lock.lockPath).toMatch(/[\\/]locks[\\/]refresh-[0-9a-f]{24}\.lock$/);
+    expect(lock.owner).toMatch(/^[0-9a-f]{24}$/);
+    expect(lock.lockInode).toEqual(expect.any(Number));
+
+    await releaseRefreshLock(lock);
+  });
+
+  it("allows exactly one concurrent caller to acquire the lock", async () => {
+    const attempts = await Promise.all([
+      acquireRefreshLock("acc-concurrent", { timeoutMs: 150, backoffMs: 5, staleMs: 60_000 }),
+      acquireRefreshLock("acc-concurrent", { timeoutMs: 150, backoffMs: 5, staleMs: 60_000 }),
+    ]);
+    const winners = attempts.filter((attempt) => attempt.acquired);
+    const losers = attempts.filter((attempt) => !attempt.acquired);
+
+    expect(winners).toHaveLength(1);
+    expect(losers).toEqual([{ acquired: false, lockPath: null, owner: null, lockInode: null }]);
+
+    await releaseRefreshLock(winners[0]);
+
+    const reacquired = await acquireRefreshLock("acc-concurrent", { timeoutMs: 50 });
+    expect(reacquired.acquired).toBe(true);
+    await releaseRefreshLock(reacquired);
+  });
+
+  it("rejects when opening the lock file fails with a non-contention error", async () => {
+    const error = Object.assign(new Error("permission denied"), { code: "EACCES" });
+    const openSpy = vi.spyOn(fs, "open").mockRejectedValueOnce(error);
+
+    try {
+      await expect(acquireRefreshLock("acc-io-failure")).rejects.toMatchObject({ code: "EACCES" });
+      expect(openSpy).toHaveBeenCalledWith(expect.stringMatching(/refresh-[0-9a-f]{24}\.lock$/), "wx", 0o600);
+    } finally {
+      openSpy.mockRestore();
+    }
+  });
+
+  itPosix("creates the lock file with owner-only POSIX permissions", async () => {
+    const lock = await acquireRefreshLock("acc-posix-permissions");
+
+    expect(lock.acquired).toBe(true);
+    const stat = await fs.stat(lock.lockPath);
+    expect(stat.mode & 0o777).toBe(0o600);
+
+    await releaseRefreshLock(lock);
+  });
+
   it("does not release lock with mismatched owner", async () => {
     const lock = await acquireRefreshLock("acc-1");
     expect(lock.acquired).toBe(true);

package/lib/retry/overload-loop.mjs

@@ -0,0 +1,83 @@
+/**
+ * Pure decision helpers for the service-wide retry / overload-recovery loop.
+ *
+ * The effectful retry loop itself (account switching, sleeping, toasts, body
+ * rewriting, response transformation) stays in index.mjs; this module holds the
+ * side-effect-free computations it depends on so they can be unit-tested
+ * directly. Tuning values come from lib/tuning.mjs (single source of truth).
+ *
+ * @module retry/overload-loop
+ */
+
+import {
+  SERVICE_RETRY_BASE_DELAY_SEC,
+  SERVICE_RETRY_BACKOFF_MULTIPLIER,
+  SERVICE_RETRY_MAX_DELAY_SEC,
+  SERVICE_RETRY_JITTER_FRACTION,
+} from "../tuning.mjs";
+
+/**
+ * Exponential backoff (capped) with downward jitter for service-wide 529/503
+ * retries. Verbatim-equivalent to the former inline formula in index.mjs.
+ *
+ * @param {number} serviceWideRetryCount - Number of service-wide retries already taken.
+ * @param {{baseDelaySec?: number, backoffMultiplier?: number, maxDelaySec?: number, jitterFraction?: number}} [opts]
+ * @param {() => number} [random] - Injectable RNG (defaults to Math.random) for deterministic tests.
+ * @returns {number} Sleep duration in milliseconds.
+ */
+export function computeServiceRetrySleepMs(serviceWideRetryCount, opts = {}, random = Math.random) {
+  const baseDelaySec = opts.baseDelaySec ?? SERVICE_RETRY_BASE_DELAY_SEC;
+  const multiplier = opts.backoffMultiplier ?? SERVICE_RETRY_BACKOFF_MULTIPLIER;
+  const maxDelaySec = opts.maxDelaySec ?? SERVICE_RETRY_MAX_DELAY_SEC;
+  const jitterFraction = opts.jitterFraction ?? SERVICE_RETRY_JITTER_FRACTION;
+  const baseDelay = Math.min(baseDelaySec * Math.pow(multiplier, serviceWideRetryCount), maxDelaySec);
+  const jitter = 1 - random() * jitterFraction;
+  return Math.round(baseDelay * jitter * 1000);
+}
+
+/**
+ * Model fallback chain for sustained overloads: opus -> sonnet -> haiku.
+ * Verbatim-equivalent to the former inline logic in index.mjs.
+ *
+ * @param {string} currentModel - The model id currently being requested.
+ * @returns {string|null} The next fallback model id, or null if none applies.
+ */
+export function selectFallbackModel(currentModel) {
+  const model = currentModel || "";
+  if (/opus-4-6|opus-4/i.test(model)) return model.replace(/opus/i, "sonnet");
+  if (/sonnet-4-6|sonnet-4/i.test(model)) return model.replace(/sonnet/i, "haiku");
+  return null;
+}
+
+/**
+ * Whether a 529 (overloaded) / 503 (unavailable) response is still eligible for
+ * a service-wide sleep-and-retry (as opposed to overload-recovery / return).
+ *
+ * @param {number} status
+ * @param {number} serviceWideRetryCount
+ * @param {number} maxServiceRetries
+ * @returns {boolean}
+ */
+export function shouldServiceRetry(status, serviceWideRetryCount, maxServiceRetries) {
+  return (status === 529 || status === 503) && serviceWideRetryCount < maxServiceRetries;
+}
+
+/**
+ * Whether a 429 is a transient burst-throttle (short retry-after) that should be
+ * retried on the SAME account rather than rotating the account pool.
+ *
+ * @param {number} status
+ * @param {string|null|undefined} reason - Parsed rate-limit reason.
+ * @param {number|null|undefined} retryAfterMs - Parsed retry-after in ms.
+ * @param {number} thresholdMs - Upper bound below which a 429 counts as transient.
+ * @returns {boolean}
+ */
+export function isTransientRateLimit(status, reason, retryAfterMs, thresholdMs) {
+  return (
+    status === 429 &&
+    reason === "RATE_LIMIT_EXCEEDED" &&
+    retryAfterMs != null &&
+    retryAfterMs > 0 &&
+    retryAfterMs <= thresholdMs
+  );
+}

package/lib/retry/overload-loop.test.mjs

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import {
+  computeServiceRetrySleepMs,
+  selectFallbackModel,
+  shouldServiceRetry,
+  isTransientRateLimit,
+} from "./overload-loop.mjs";
+import {
+  SERVICE_RETRY_BASE_DELAY_SEC,
+  SERVICE_RETRY_MAX_DELAY_SEC,
+  SERVICE_RETRY_JITTER_FRACTION,
+} from "../tuning.mjs";
+
+describe("overload-loop: computeServiceRetrySleepMs", () => {
+  const noJitter = () => 0; // jitter factor = 1 (no reduction)
+  const maxJitter = () => 1; // jitter factor = 1 - jitterFraction
+
+  it("applies capped exponential backoff with zero jitter", () => {
+    expect(computeServiceRetrySleepMs(0, {}, noJitter)).toBe(500);
+    expect(computeServiceRetrySleepMs(1, {}, noJitter)).toBe(1000);
+    expect(computeServiceRetrySleepMs(2, {}, noJitter)).toBe(2000);
+  });
+
+  it("caps the base delay at the configured maximum", () => {
+    // 0.5 * 2^3 = 4s, capped to SERVICE_RETRY_MAX_DELAY_SEC (3s) -> 3000ms
+    expect(SERVICE_RETRY_MAX_DELAY_SEC).toBe(3);
+    expect(computeServiceRetrySleepMs(3, {}, noJitter)).toBe(3000);
+    expect(computeServiceRetrySleepMs(10, {}, noJitter)).toBe(3000);
+  });
+
+  it("applies maximum downward jitter", () => {
+    // n=0: base 500ms * (1 - 0.25) = 375ms
+    expect(SERVICE_RETRY_JITTER_FRACTION).toBe(0.25);
+    expect(computeServiceRetrySleepMs(0, {}, maxJitter)).toBe(375);
+  });
+
+  it("honors option overrides", () => {
+    const ms = computeServiceRetrySleepMs(
+      1,
+      { baseDelaySec: 1, backoffMultiplier: 3, maxDelaySec: 100, jitterFraction: 0 },
+      maxJitter,
+    );
+    // 1 * 3^1 = 3s, jitter 1 - 1*0 = 1 -> 3000ms
+    expect(ms).toBe(3000);
+  });
+
+  it("defaults to the tuning base delay for the first attempt", () => {
+    expect(computeServiceRetrySleepMs(0, {}, noJitter)).toBe(SERVICE_RETRY_BASE_DELAY_SEC * 1000);
+  });
+});
+
+describe("overload-loop: selectFallbackModel", () => {
+  it("steps opus -> sonnet", () => {
+    expect(selectFallbackModel("claude-opus-4-6")).toBe("claude-sonnet-4-6");
+    expect(selectFallbackModel("claude-opus-4")).toBe("claude-sonnet-4");
+  });
+
+  it("steps sonnet -> haiku", () => {
+    expect(selectFallbackModel("claude-sonnet-4-6")).toBe("claude-haiku-4-6");
+    expect(selectFallbackModel("claude-sonnet-4-5")).toBe("claude-haiku-4-5");
+  });
+
+  it("returns null for haiku (bottom of the chain)", () => {
+    expect(selectFallbackModel("claude-haiku-4-5")).toBeNull();
+  });
+
+  it("returns null for empty or unknown models", () => {
+    expect(selectFallbackModel("")).toBeNull();
+    expect(selectFallbackModel(null)).toBeNull();
+    expect(selectFallbackModel(undefined)).toBeNull();
+    expect(selectFallbackModel("gpt-4o")).toBeNull();
+  });
+});
+
+describe("overload-loop: shouldServiceRetry", () => {
+  it("retries 529/503 while under the budget", () => {
+    expect(shouldServiceRetry(529, 0, 2)).toBe(true);
+    expect(shouldServiceRetry(503, 1, 2)).toBe(true);
+  });
+
+  it("stops at the budget", () => {
+    expect(shouldServiceRetry(529, 2, 2)).toBe(false);
+  });
+
+  it("ignores non-overload statuses", () => {
+    expect(shouldServiceRetry(500, 0, 2)).toBe(false);
+    expect(shouldServiceRetry(429, 0, 2)).toBe(false);
+    expect(shouldServiceRetry(200, 0, 2)).toBe(false);
+  });
+});
+
+describe("overload-loop: isTransientRateLimit", () => {
+  const T = 10000;
+  it("is true for a short-retry-after RATE_LIMIT_EXCEEDED 429", () => {
+    expect(isTransientRateLimit(429, "RATE_LIMIT_EXCEEDED", 5000, T)).toBe(true);
+    expect(isTransientRateLimit(429, "RATE_LIMIT_EXCEEDED", T, T)).toBe(true);
+  });
+
+  it("is false when any condition is not met", () => {
+    expect(isTransientRateLimit(529, "RATE_LIMIT_EXCEEDED", 5000, T)).toBe(false);
+    expect(isTransientRateLimit(429, "QUOTA_EXHAUSTED", 5000, T)).toBe(false);
+    expect(isTransientRateLimit(429, "RATE_LIMIT_EXCEEDED", null, T)).toBe(false);
+    expect(isTransientRateLimit(429, "RATE_LIMIT_EXCEEDED", undefined, T)).toBe(false);
+    expect(isTransientRateLimit(429, "RATE_LIMIT_EXCEEDED", 0, T)).toBe(false);
+    expect(isTransientRateLimit(429, "RATE_LIMIT_EXCEEDED", 15000, T)).toBe(false);
+  });
+});