Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
fix(runtime): address review feedback on pinned 503 (#486)
- Extract `buildPinnedUnavailableErrorBody` helper so the null-reason
  state-desync branch can be unit-tested directly without standing up a
  full proxy. The helper is exported alongside a typed
  `PinnedUnavailableErrorBody` interface so external consumers can rely
  on a stable shape.
- Tighten the end-to-end cooling-down assertion from a regex prefix to
  an exact equality check against `cooling-down:auth-failure`, the
  string set by `markAccountCoolingDown` in the test setup. Prevents
  silent contract drift on the cooldown reason format.
- Add chooseAccount unit cases for the remaining pinned skip reasons
  flagged by review: `workspace-disabled` (all workspaces disabled) and
  `circuit-open` (failure threshold tripped via `recordFailure`). The
  suite now mirrors the full enumeration in
  `AccountManager.getAccountRuntimeSkipReason`.
- Add direct unit coverage for `buildPinnedUnavailableErrorBody` over
  four shapes: empty map yields `reason: null` with no parenthetical in
  the message, populated map yields the reason plus the parenthetical,
  null `pinnedIndex` resolves to `pinnedAccountIndex: null` without
  throwing, and the full `account_skip_reasons` map is mirrored even
  when the pinned index has no entry of its own.

Closes #486 partial: review feedback addressed; underlying state desync
still needs reporter logs to root-cause.
  • Loading branch information
ndycode committed May 27, 2026
commit 0bf756b48266ba50973e672ebef4b18ef1cf978b
69 changes: 47 additions & 22 deletions lib/runtime-rotation-proxy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1044,6 +1044,47 @@ function writePoolExhausted(params: {
});
}

/**
* Build the JSON `error` body for a pinned-account 503 response. Extracted so
* the null-reason desync path (`reason: null`, no parenthetical in `message`)
* can be unit-tested without standing up a full proxy. The shape mirrors
* `writePoolExhausted` so consumers can handle both 503 codes uniformly. See
* issue #486.
*/
export interface PinnedUnavailableErrorBody {
message: string;
code: "codex_pinned_account_unavailable";
pinnedAccountIndex: number | null;
reason: string | null;
account_skip_reasons: Record<string, string>;
}

export function buildPinnedUnavailableErrorBody(
pinnedIndex: number | null | undefined,
accountSkipReasons: ReadonlyMap<number, string>,
): PinnedUnavailableErrorBody {
const normalizedPinnedIndex =
typeof pinnedIndex === "number" ? pinnedIndex : null;
const skipReason =
normalizedPinnedIndex !== null
? accountSkipReasons.get(normalizedPinnedIndex) ?? null
: null;
const reasonSuffix = skipReason ? ` (${skipReason})` : "";
const displayIndex = (normalizedPinnedIndex ?? 0) + 1;
return {
message: `Pinned account ${displayIndex} is currently unavailable${reasonSuffix}; run \`codex-multi-auth status\` for details, or \`codex-multi-auth unpin\` to allow rotation.`,
code: "codex_pinned_account_unavailable",
pinnedAccountIndex: normalizedPinnedIndex,
reason: skipReason,
account_skip_reasons: Object.fromEntries(
[...accountSkipReasons.entries()].map(([index, reason]) => [
String(index),
reason,
]),
),
};
}

async function withTimeout<T>(
promise: Promise<T>,
timeoutMs: number,
Expand Down Expand Up @@ -1744,35 +1785,19 @@ export async function startRuntimeRotationProxy(
// null reason indicates a forecast/runtime state desync (the pinned
// account was selected but no skip reason was recorded) — see #486.
if (isPinned) {
const pinnedSkipReason =
typeof pinnedIndex === "number"
? accountSkipReasons.get(pinnedIndex) ?? null
: null;
if (pinnedSkipReason === null) {
const errorBody = buildPinnedUnavailableErrorBody(
pinnedIndex,
accountSkipReasons,
);
if (errorBody.reason === null) {
status.lastError = `pinned-503 missing skip reason (pinnedIndex=${pinnedIndex})`;
}
const reasonSuffix = pinnedSkipReason
? ` (${pinnedSkipReason})`
: "";
await usageRecorder?.record({
outcome: "failure",
statusCode: HTTP_STATUS.SERVICE_UNAVAILABLE,
errorCode: "codex_pinned_account_unavailable",
});
writeJson(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
error: {
message: `Pinned account ${(pinnedIndex ?? 0) + 1} is currently unavailable${reasonSuffix}; run \`codex-multi-auth status\` for details, or \`codex-multi-auth unpin\` to allow rotation.`,
code: "codex_pinned_account_unavailable",
pinnedAccountIndex: pinnedIndex,
reason: pinnedSkipReason,
account_skip_reasons: Object.fromEntries(
[...accountSkipReasons.entries()].map(([index, reason]) => [
String(index),
reason,
]),
),
},
});
writeJson(res, HTTP_STATUS.SERVICE_UNAVAILABLE, { error: errorBody });
return;
}

Expand Down
8 changes: 4 additions & 4 deletions test/issue-474-pin-end-to-end.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -430,10 +430,10 @@ describe("issue #474 — end-to-end pin honored over real HTTP proxy", () => {
};
};
expect(body.error.code).toBe("codex_pinned_account_unavailable");
expect(body.error.reason).toMatch(/^cooling-down/);
expect(body.error.message).toMatch(/\(cooling-down[^)]*\)/);
expect(body.error.account_skip_reasons[String(pinnedIndex)]).toMatch(
/^cooling-down/,
expect(body.error.reason).toBe("cooling-down:auth-failure");
expect(body.error.message).toContain("(cooling-down:auth-failure)");
expect(body.error.account_skip_reasons[String(pinnedIndex)]).toBe(
"cooling-down:auth-failure",
);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
expect(upstreamCalls).toHaveLength(0);
},
Expand Down
111 changes: 111 additions & 0 deletions test/issue-474-pin-honored.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { AccountManager } from "../lib/accounts.js";
import { clearCircuitBreakers } from "../lib/circuit-breaker.js";
import {
buildPinnedUnavailableErrorBody,
chooseAccount,
readPinnedAccountIndexFromDisk,
resetPinCacheForTesting,
Expand Down Expand Up @@ -623,6 +624,116 @@ describe("issue #474 — manual pin honored by runtime proxy", () => {
expect(result).toBeNull();
expect(skipReasons.get(0)).toBe("already-attempted");
});

it("records 'workspace-disabled' when every workspace on the pinned account is disabled", () => {
const now = Date.now();
const storage = createStorage(now, 3);
const accountManager = new AccountManager(undefined, storage);
const pinned = accountManager.getAccountByIndex(2);
if (!pinned) throw new Error("setup failed");
pinned.workspaces = [{ id: "ws-1", enabled: false }];
const skipReasons = new Map<number, string>();

const result = chooseAccount({
accountManager,
sessionAffinityStore: null,
sessionKey: null,
family: "codex",
model: null,
attemptedIndexes: new Set(),
now,
policy: null,
pinnedIndex: 2,
skipReasons,
});

expect(result).toBeNull();
expect(skipReasons.get(2)).toBe("workspace-disabled");
});

it("records 'circuit-open' when the pinned account's circuit breaker is open", () => {
const now = Date.now();
const storage = createStorage(now, 3);
const accountManager = new AccountManager(undefined, storage);
const pinned = accountManager.getAccountByIndex(1);
if (!pinned) throw new Error("setup failed");
// Default failure threshold is 3 — trip the breaker explicitly so
// `getAccountRuntimeSkipReason` resolves to "circuit-open".
accountManager.recordFailure(pinned, "codex");
accountManager.recordFailure(pinned, "codex");
accountManager.recordFailure(pinned, "codex");
const skipReasons = new Map<number, string>();

const result = chooseAccount({
accountManager,
sessionAffinityStore: null,
sessionKey: null,
family: "codex",
model: null,
attemptedIndexes: new Set(),
now,
policy: null,
pinnedIndex: 1,
skipReasons,
});

expect(result).toBeNull();
expect(skipReasons.get(1)).toBe("circuit-open");
});
});

// Issue #486: cover the null-reason desync branch directly. `chooseAccount`
// is supposed to record a skip reason for every pinned-unavailability path,
// but if internal state desyncs (e.g. forecast says "rotate" yet runtime
// state is missing a reason), the proxy still needs to produce a 503 body
// with an explicit `reason: null` instead of silently masking the gap.
describe("buildPinnedUnavailableErrorBody", () => {
it("returns reason: null and omits the parenthetical when no skip reason was recorded", () => {
const body = buildPinnedUnavailableErrorBody(
1,
new Map<number, string>(),
);
expect(body.code).toBe("codex_pinned_account_unavailable");
expect(body.reason).toBeNull();
expect(body.pinnedAccountIndex).toBe(1);
expect(body.account_skip_reasons).toEqual({});
expect(body.message).toBe(
"Pinned account 2 is currently unavailable; run `codex-multi-auth status` for details, or `codex-multi-auth unpin` to allow rotation.",
);
expect(body.message).not.toContain("(");
});

it("surfaces the skip reason and appends it to the message when present", () => {
const skipReasons = new Map<number, string>([[1, "rate-limited"]]);
const body = buildPinnedUnavailableErrorBody(1, skipReasons);
expect(body.reason).toBe("rate-limited");
expect(body.account_skip_reasons).toEqual({ "1": "rate-limited" });
expect(body.message).toContain("Pinned account 2");
expect(body.message).toContain("(rate-limited)");
});

it("handles a null pinnedIndex without throwing and emits reason: null", () => {
const body = buildPinnedUnavailableErrorBody(
null,
new Map<number, string>(),
);
expect(body.pinnedAccountIndex).toBeNull();
expect(body.reason).toBeNull();
expect(body.message).toContain("Pinned account 1");
});

it("mirrors the full accountSkipReasons map even when the pinned entry is unknown", () => {
const skipReasons = new Map<number, string>([
[0, "rate-limited"],
[2, "disabled"],
]);
const body = buildPinnedUnavailableErrorBody(1, skipReasons);
expect(body.reason).toBeNull();
expect(body.account_skip_reasons).toEqual({
"0": "rate-limited",
"2": "disabled",
});
});
});

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
describe("readPinnedAccountIndexFromDisk", () => {
Expand Down