Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(recovery): a short API_TIMEOUT_MS no longer silently disables auth-path recovery

Jack Rudenko453040bfc338
diff --git a/packages/cli/src/handlers/shared/refresh-deadline.test.ts b/packages/cli/src/handlers/shared/refresh-deadline.test.ts
new file mode 100644
index 00000000..5b3f8a20
--- /dev/null
+++ b/packages/cli/src/handlers/shared/refresh-deadline.test.ts
@@ -0,0 +1,198 @@
+/**
+ * Black-box tests for `refreshDeadlineAt`, written from the spec and the public
+ * contract only (the implementation was not read).
+ *
+ * Spec:
+ * tier-1 budget = max(15000, min(API_TIMEOUT_MS ?? 360000, 300000) - 30000)
+ * A token-refresh failure is recovered against refreshDeadlineAt(deadlineAt),
+ * which reserves part of that budget for the request that follows.
+ *
+ * REQ-1 (R1) default env: refreshDeadlineAt(270000) === 225000 (45 000 ms reserve)
+ * REQ-2 (R2) the reserve is never more than HALF the budget:
+ * 75000 -> D - 22500, 60000 -> D - 15000, 30000 (floor) -> D - 7500
+ * REQ-3 (R3) refreshDeadlineAt(D) > D - budget for every case above
+ * REQ-4 (R4) API_TIMEOUT_MS=120000 (budget 90000) -> reserve exactly 45000,
+ * and it stays 45000 above that
+ * REQ-5 (contract) PER_ATTEMPT_CONNECT_CAP_MS is 45000; refreshDeadlineAt is pure
+ * apart from reading process.env.API_TIMEOUT_MS at call time
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { PER_ATTEMPT_CONNECT_CAP_MS, refreshDeadlineAt } from "./transient-retry.js";
+
+const ORIGINAL_API_TIMEOUT_MS = process.env.API_TIMEOUT_MS;
+
+afterEach(() => {
+ if (ORIGINAL_API_TIMEOUT_MS === undefined) delete process.env.API_TIMEOUT_MS;
+ else process.env.API_TIMEOUT_MS = ORIGINAL_API_TIMEOUT_MS;
+});
+
+function setApiTimeout(value: number | undefined): void {
+ if (value === undefined) delete process.env.API_TIMEOUT_MS;
+ else process.env.API_TIMEOUT_MS = String(value);
+}
+
+/** The spec's budget formula, restated from the spec text — not from the implementation. */
+function specBudget(apiTimeoutMs: number | undefined): number {
+ return Math.max(15_000, Math.min(apiTimeoutMs ?? 360_000, 300_000) - 30_000);
+}
+
+/** Reserve = how far before the tier-1 deadline the refresh deadline lands. */
+function reservesAt(deadlines: readonly number[]): number[] {
+ return deadlines.map((d) => d - refreshDeadlineAt(d));
+}
+
+/** The spec's own 270000, zero, and absolute epoch-millisecond deadlines like a live request's. */
+const DEADLINES = [270_000, 0, 1_758_600_000_000, 1_758_600_045_000] as const;
+
+const label = (v: number | undefined): string => (v === undefined ? "unset" : String(v));
+
+describe("test-helper self-check: specBudget restates the spec's stated budgets", () => {
+ test("budget is 270000 unset, 45000 at 75000, 30000 at 60000, 15000 at 45000 and below", () => {
+ expect([undefined, 75_000, 60_000, 45_000, 30_000, 10_000].map(specBudget)).toEqual([
+ 270_000, 45_000, 30_000, 15_000, 15_000, 15_000,
+ ]);
+ });
+});
+
+describe("REQ-5 contract surface", () => {
+ test("REQ-5: PER_ATTEMPT_CONNECT_CAP_MS is 45000", () => {
+ expect(PER_ATTEMPT_CONNECT_CAP_MS).toBe(45_000);
+ });
+
+ test("REQ-5: refreshDeadlineAt returns the same value for the same deadline and environment", () => {
+ setApiTimeout(75_000);
+
+ const first = refreshDeadlineAt(1_758_600_000_000);
+ const second = refreshDeadlineAt(1_758_600_000_000);
+
+ expect(second).toBe(first);
+ });
+
+ test("REQ-5: refreshDeadlineAt reads API_TIMEOUT_MS at call time, not once at import", () => {
+ const D = 1_758_600_000_000;
+ const observed: number[] = [];
+
+ for (const value of [60_000, 120_000, undefined, 30_000]) {
+ setApiTimeout(value);
+ observed.push(D - refreshDeadlineAt(D));
+ }
+
+ expect(observed).toEqual([15_000, 45_000, 45_000, 7_500]);
+ });
+});
+
+describe("REQ-1 (R1): the default environment keeps the 45 000 ms reserve", () => {
+ test("REQ-1: with API_TIMEOUT_MS unset, refreshDeadlineAt(270000) returns 225000", () => {
+ setApiTimeout(undefined);
+
+ expect(refreshDeadlineAt(270_000)).toBe(225_000);
+ });
+
+ test("REQ-1: with API_TIMEOUT_MS unset, the reserve is 45000 for every deadline", () => {
+ setApiTimeout(undefined);
+
+ expect(reservesAt(DEADLINES)).toEqual(DEADLINES.map(() => 45_000));
+ });
+});
+
+describe("REQ-2 (R2): the reserve is capped at half the budget", () => {
+ const exactCases: ReadonlyArray<{ api: number; budget: number; reserve: number }> = [
+ { api: 75_000, budget: 45_000, reserve: 22_500 },
+ { api: 60_000, budget: 30_000, reserve: 15_000 },
+ { api: 30_000, budget: 15_000, reserve: 7_500 },
+ ];
+
+ for (const { api, budget, reserve } of exactCases) {
+ test(`REQ-2: at API_TIMEOUT_MS=${api} (budget ${budget}) refreshDeadlineAt(D) === D - ${reserve}`, () => {
+ setApiTimeout(api);
+
+ expect(reservesAt(DEADLINES)).toEqual(DEADLINES.map(() => reserve));
+ });
+ }
+
+ // Budget sits on the 15000 floor at 45000 "or below", so the floor reserve applies there too.
+ for (const api of [45_000, 10_000]) {
+ test(`REQ-2: at API_TIMEOUT_MS=${api} (budget on the 15000 floor) refreshDeadlineAt(D) === D - 7500`, () => {
+ setApiTimeout(api);
+
+ expect(reservesAt(DEADLINES)).toEqual(DEADLINES.map(() => 7_500));
+ });
+ }
+
+ const sweep: ReadonlyArray<number | undefined> = [
+ undefined,
+ 1_000,
+ 10_000,
+ 30_000,
+ 45_000,
+ 45_001,
+ 50_000,
+ 60_000,
+ 75_000,
+ 90_000,
+ 100_000,
+ 119_999,
+ 120_000,
+ 150_000,
+ 300_000,
+ 360_000,
+ 600_000,
+ ];
+
+ test("REQ-2: across API_TIMEOUT_MS values the reserve never exceeds half the budget", () => {
+ const rows = sweep.map((api) => {
+ setApiTimeout(api);
+ const D = 1_758_600_000_000;
+ const reserve = D - refreshDeadlineAt(D);
+ return { api: label(api), withinHalf: reserve <= specBudget(api) / 2, reserve };
+ });
+
+ expect(rows.filter((r) => !r.withinHalf)).toEqual([]);
+ });
+
+ test("REQ-2: across API_TIMEOUT_MS values the auth path always keeps a positive budget", () => {
+ const rows = sweep.map((api) => {
+ setApiTimeout(api);
+ const D = 1_758_600_000_000;
+ const authBudget = refreshDeadlineAt(D) - (D - specBudget(api));
+ return { api: label(api), positive: authBudget > 0, authBudget };
+ });
+
+ expect(rows.filter((r) => !r.positive)).toEqual([]);
+ });
+});
+
+describe("REQ-3 (R3): the auth path's own budget is positive for every listed case", () => {
+ const cases: ReadonlyArray<number | undefined> = [undefined, 75_000, 60_000, 30_000];
+
+ for (const api of cases) {
+ test(`REQ-3: at API_TIMEOUT_MS=${label(api)} refreshDeadlineAt(D) > D - budget(${specBudget(api)})`, () => {
+ setApiTimeout(api);
+ const budget = specBudget(api);
+
+ const failures = DEADLINES.filter((d) => !(refreshDeadlineAt(d) > d - budget)).map((d) => ({
+ D: d,
+ refreshDeadline: refreshDeadlineAt(d),
+ tierOneStart: d - budget,
+ }));
+
+ expect(failures).toEqual([]);
+ });
+ }
+});
+
+describe("REQ-4 (R4): the reserve saturates at 45000 from budget 90000 upward", () => {
+ test("REQ-4: at API_TIMEOUT_MS=120000 (budget 90000) the reserve is exactly 45000", () => {
+ setApiTimeout(120_000);
+
+ expect(reservesAt(DEADLINES)).toEqual(DEADLINES.map(() => 45_000));
+ });
+
+ for (const api of [150_000, 200_000, 300_000, 360_000, 600_000]) {
+ test(`REQ-4: at API_TIMEOUT_MS=${api} (budget ${specBudget(api)}) the reserve stays 45000`, () => {
+ setApiTimeout(api);
+
+ expect(reservesAt(DEADLINES)).toEqual(DEADLINES.map(() => 45_000));
+ });
+ }
+});
diff --git a/packages/cli/src/handlers/shared/transient-retry.ts b/packages/cli/src/handlers/shared/transient-retry.ts
index 5068100e..2632882a 100644
--- a/packages/cli/src/handlers/shared/transient-retry.ts
+++ b/packages/cli/src/handlers/shared/transient-retry.ts
@@ -81,15 +81,23 @@ export const MIN_ATTEMPT_SLOT_MS = 3_000;
* catch's.
*
* Both sit in the same request and share one `deadlineAt`. If auth recovery
- * consumes the whole of it and then SUCCEEDS, the flow proceeds to the primary
- * fetch — which is byte-identical to today's expression and therefore
- * unclamped — and a maximal connect hang lands the response write a full
- * connect timeout past the deadline. Reserving the unclamped attempt's own
- * worst case out of the auth path's budget restores the margin the derivation
- * assumed, and costs one function rather than an edit to the healthy path.
+ * spends all of it and then SUCCEEDS, the primary fetch that follows gets no
+ * real attempt, even with the network back. So part of the budget is reserved
+ * for it. (The reservation was first justified as stopping the primary fetch
+ * from outliving the deadline; the request ceiling — `deadlineClamp` — now does
+ * that on its own, and what is left is the fetch's right to a real attempt.)
+ *
+ * THE RESERVE IS CAPPED AT HALF THE BUDGET. A flat 45 s reserve against a
+ * budget derived from `API_TIMEOUT_MS` left the auth path nothing at all once
+ * the budget fell to 45 s (`API_TIMEOUT_MS` = 75 000) and a deadline in the
+ * PAST below that — so a token refresh against a stopped server skipped
+ * recovery as "no budget" and answered at once, silently. Capped at half, the
+ * default is unchanged (half of 270 s is well above 45 s) and a short budget is
+ * split between the two paths instead of given entirely to one.
*/
export function refreshDeadlineAt(deadlineAt: number): number {
- return deadlineAt - PER_ATTEMPT_CONNECT_CAP_MS;
+ const reserve = Math.min(PER_ATTEMPT_CONNECT_CAP_MS, resolveTier1DeadlineMs() / 2);
+ return deadlineAt - reserve;
}
/**