fix(runtime): emit consistent token_invalidated body on upstream-401 path (#497)

* fix(runtime): emit consistent token_invalidated body on upstream-401 path

The upstream-401 invalidation path forwarded the raw OpenAI body, so
clients keying off error.code saw a stable "token_invalidated" code on
the refresh-failure path but not here (Greptile P3 on #496).

- Add buildTokenInvalidationBody(): wraps both paths in the same
  { error: { message, code: "token_invalidated" } } shape, preserving
  the upstream message when present and falling back to a stable message
  for non-JSON bodies (no markup echoed to clients).
- Force content-type: application/json and drop content-length/-encoding
  via responseHeadersForClient since the body is rewritten.
- Document that applyMonotonicAuthCooldown intentionally uses Date.now()
  (not the injected now()) to match the markAccountCoolingDown/nowMs()
  write domain, guarding against a regression that would defeat the
  monotonic cooldown race protection.
- Strengthen existing upstream-401 and html-body tests to assert the
  client contract (code + message).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(runtime): route refresh-failure 401 through shared invalidation builder + unit-test branches

Addresses two Greptile P2 comments on this PR:

- The refresh-failure invalidation exit still hardcoded the body literals
  the new constants were meant to centralise, reopening the exact drift
  risk this PR closes. Route it through buildTokenInvalidationBody(""),
  which yields the same { error: { message: <fallback>, code:
  "token_invalidated" } } so both paths can no longer diverge.
- Export buildTokenInvalidationBody and add 8 unit tests covering all
  message-extraction branches: empty input, top-level message, nested
  error.message, top-level-wins priority, blank-top-level -> nested
  fallback, non-JSON body, and no-usable-message fallback.

Full suite: 4062 tests pass (4054 + 8). typecheck/lint/build clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ndycode

lib/runtime-rotation-proxy.ts

@@ -666,6 +666,11 @@ function applyMonotonicAuthCooldown(
 	cooldownMs: number,
 ): void {
 	const existing = accountManager.getAccountByIndex(account.index)?.coolingDownUntil ?? 0;
+	// Intentionally Date.now(), not the proxy's injected now(): coolingDownUntil is
+	// written by markAccountCoolingDown via nowMs() (== Date.now()), so both sides of
+	// this comparison must live in the same real-wall-clock domain. Switching to the
+	// injected now() would mis-compare an injected-clock value against a real-clock
+	// deadline and silently defeat the monotonic guard.
 	if (Date.now() + cooldownMs > existing) {
 		accountManager.markAccountCoolingDown(account, cooldownMs, "auth-failure");
 	}
@@ -843,6 +848,41 @@ async function readErrorBody(response: Response): Promise<string> {
 	}
 }
 
+const TOKEN_INVALIDATED_CODE = "token_invalidated";
+const TOKEN_INVALIDATED_FALLBACK_MESSAGE =
+	"OAuth token has been invalidated. Please re-login.";
+
+// Both invalidation exit paths (refresh-failure and upstream-401) must hand the
+// client the same machine-readable shape — { error: { message, code:
+// "token_invalidated" } } — so a consumer keying off error.code behaves
+// identically regardless of which vector fired. The upstream forwards a raw body
+// with no guaranteed code, so we wrap it here while preserving its human-readable
+// message when one is present.
+export function buildTokenInvalidationBody(upstreamBodyText: string): string {
+	let message = TOKEN_INVALIDATED_FALLBACK_MESSAGE;
+	const trimmed = upstreamBodyText.trim();
+	if (trimmed) {
+		try {
+			const parsed = JSON.parse(trimmed) as unknown;
+			if (isRecord(parsed)) {
+				const direct = parsed.message;
+				if (typeof direct === "string" && direct.trim()) {
+					message = direct.trim();
+				} else if (isRecord(parsed.error)) {
+					const nested = parsed.error.message;
+					if (typeof nested === "string" && nested.trim()) {
+						message = nested.trim();
+					}
+				}
+			}
+		} catch {
+			// Non-JSON upstream body (e.g. HTML error page): keep the stable fallback
+			// message rather than echoing markup back to the client.
+		}
+	}
+	return JSON.stringify({ error: { message, code: TOKEN_INVALIDATED_CODE } });
+}
+
 function extractErrorCodeFromBody(bodyText: string): string | null {
 	if (!bodyText.trim()) return null;
 	try {
@@ -1516,14 +1556,10 @@ export async function startRuntimeRotationProxy(
 						// return auth error to client instead of rotating to the next account.
 						sessionAffinityStore?.forgetSession(context.sessionKey);
 						res.writeHead(HTTP_STATUS.UNAUTHORIZED, { "content-type": "application/json" });
-						res.end(
-							JSON.stringify({
-								error: {
-									message: "OAuth token has been invalidated. Please re-login.",
-									code: "token_invalidated",
-								},
-							}),
-						);
+						// Route through the shared builder so both invalidation exit paths stay
+						// in lockstep — empty input yields { error: { message: <fallback>,
+						// code: "token_invalidated" } }.
+						res.end(buildTokenInvalidationBody(""));
 						await usageRecorder.record({
 							outcome: "failure",
 							statusCode: HTTP_STATUS.UNAUTHORIZED,
@@ -1742,8 +1778,13 @@ export async function startRuntimeRotationProxy(
 						);
 						sessionAffinityStore?.forgetSession(context.sessionKey);
 						accountManager.saveToDiskDebounced();
-						res.writeHead(upstream.status, responseHeadersForClient(upstream.headers));
-						res.end(bodyText);
+						// Emit the same machine-readable shape as the refresh-failure path
+						// (code: "token_invalidated") instead of forwarding the raw upstream
+						// body, so the client contract is consistent across both vectors.
+						const clientHeaders = responseHeadersForClient(upstream.headers);
+						clientHeaders["content-type"] = "application/json";
+						res.writeHead(upstream.status, clientHeaders);
+						res.end(buildTokenInvalidationBody(bodyText));
 						await usageRecorder.record({
 							outcome: "failure",
 							statusCode: upstream.status,

test/runtime-rotation-proxy.test.ts

@@ -4,6 +4,7 @@ import { AccountManager } from "../lib/accounts.js";
 import { HTTP_STATUS, OPENAI_HEADERS } from "../lib/constants.js";
 import {
 	startRuntimeRotationProxy,
+	buildTokenInvalidationBody,
 	type RuntimeRotationProxyServer,
 } from "../lib/runtime-rotation-proxy.js";
 import { clearCircuitBreakers } from "../lib/circuit-breaker.js";
@@ -1857,6 +1858,13 @@ describe("runtime rotation proxy", () => {
 		const response = await postResponses(proxy, { model: "gpt-5-codex" });
 
 		expect(response.status).toBe(HTTP_STATUS.UNAUTHORIZED);
+		// upstream-401 invalidation path emits the same machine-readable contract as
+		// the refresh-failure path, preserving the upstream message
+		const body = (await response.json()) as { error: { message: string; code: string } };
+		expect(body.error.code).toBe("token_invalidated");
+		expect(body.error.message).toBe(
+			"Encountered invalidated oauth token for user, failing request",
+		);
 		expect(calls).toHaveLength(1);
 		expect(calls[0]?.headers.get(OPENAI_HEADERS.ACCOUNT_ID)).toBe("acc_1");
 		expect(accountManager.getAccountByIndex(0)?.cooldownReason).toBe("auth-failure");
@@ -2027,7 +2035,69 @@ describe("runtime rotation proxy", () => {
 		const response = await postResponses(proxy, { model: "gpt-5-codex" });
 
 		expect(response.status).toBe(HTTP_STATUS.UNAUTHORIZED);
+		// non-JSON upstream body falls back to the stable message rather than echoing
+		// markup back to the client, but still carries the consistent code
+		const body = (await response.json()) as { error: { message: string; code: string } };
+		expect(body.error.code).toBe("token_invalidated");
+		expect(body.error.message).toBe("OAuth token has been invalidated. Please re-login.");
 		expect(calls).toHaveLength(1);
 		expect(proxy.getStatus().rotations).toBe(0);
 	});
 });
+
+describe("buildTokenInvalidationBody", () => {
+	const FALLBACK = "OAuth token has been invalidated. Please re-login.";
+	const parse = (raw: string) =>
+		JSON.parse(raw) as { error: { message: string; code: string } };
+
+	it("always emits the token_invalidated code", () => {
+		expect(parse(buildTokenInvalidationBody("")).error.code).toBe("token_invalidated");
+		expect(
+			parse(buildTokenInvalidationBody(JSON.stringify({ message: "x" }))).error.code,
+		).toBe("token_invalidated");
+	});
+
+	it("uses the stable fallback message for empty input", () => {
+		expect(parse(buildTokenInvalidationBody("")).error.message).toBe(FALLBACK);
+	});
+
+	it("preserves a top-level message", () => {
+		const body = JSON.stringify({ message: "Encountered invalidated oauth token" });
+		expect(parse(buildTokenInvalidationBody(body)).error.message).toBe(
+			"Encountered invalidated oauth token",
+		);
+	});
+
+	it("preserves a nested error.message when no top-level message is present", () => {
+		const body = JSON.stringify({ error: { message: "nested invalidation detail" } });
+		expect(parse(buildTokenInvalidationBody(body)).error.message).toBe(
+			"nested invalidation detail",
+		);
+	});
+
+	it("prefers a top-level message over a nested error.message", () => {
+		const body = JSON.stringify({
+			message: "top-level wins",
+			error: { message: "nested loses" },
+		});
+		expect(parse(buildTokenInvalidationBody(body)).error.message).toBe("top-level wins");
+	});
+
+	it("falls back to nested error.message when top-level message is blank/whitespace", () => {
+		const body = JSON.stringify({
+			message: "   ",
+			error: { message: "nested fallback" },
+		});
+		expect(parse(buildTokenInvalidationBody(body)).error.message).toBe("nested fallback");
+	});
+
+	it("falls back to the stable message for non-JSON bodies (no markup echoed)", () => {
+		const html = "<html><body>oauth token has been invalidated</body></html>";
+		expect(parse(buildTokenInvalidationBody(html)).error.message).toBe(FALLBACK);
+	});
+
+	it("falls back to the stable message when no usable message field exists", () => {
+		const body = JSON.stringify({ error: { code: "something_else" } });
+		expect(parse(buildTokenInvalidationBody(body)).error.message).toBe(FALLBACK);
+	});
+});