fix(auth): log callback fallback causes and cover manual bind failures

Author: ndycode

docs/reference/commands.md

@@ -62,6 +62,7 @@ Compatibility aliases are supported:
 - In non-TTY or host-managed sessions, including `CODEX_TUI=1`, `CODEX_DESKTOP=1`, `TERM_PROGRAM=codex`, or `ELECTRON_RUN_AS_NODE=1`, auth flows degrade to deterministic text behavior.
 - The non-TTY fallback keeps `codex auth login` predictable: it defaults to add-account mode, skips the extra "add another account" prompt, and auto-picks the default workspace selection when a follow-up choice is needed.
 - `codex auth login --manual` keeps the login flow usable in browser-restricted shells by printing the OAuth URL and accepting manual callback input instead of trying to open a browser.
+- In non-TTY/manual shells, provide the full redirect URL on stdin, for example: `echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual`.
 
 ---
 

lib/codex-manager.ts

@@ -37,6 +37,7 @@ import {
 	summarizeForecast,
 	type ForecastAccountResult,
 } from "./forecast.js";
+import { createLogger } from "./logger.js";
 import { MODEL_FAMILIES, type ModelFamily } from "./prompts/codex.js";
 import {
 	fetchCodexQuotaSnapshot,
@@ -87,6 +88,8 @@ type TokenSuccessWithAccount = TokenSuccess & {
 };
 type PromptTone = "accent" | "success" | "warning" | "danger" | "muted";
 
+const log = createLogger("codex-manager");
+
 function stylePromptText(text: string, tone: PromptTone): string {
 	if (!output.isTTY) return text;
 	const ui = getUiRuntimeOptions();
@@ -1471,7 +1474,22 @@ async function runOAuthFlow(
 	let oauthServer: Awaited<ReturnType<typeof startLocalOAuthServer>> | null = null;
 	try {
 		oauthServer = await startLocalOAuthServer({ state });
-	} catch {
+	} catch (serverError) {
+		log.warn(
+			"Local OAuth callback server unavailable; falling back to manual callback entry.",
+			serverError instanceof Error
+				? {
+					message: serverError.message,
+					stack: serverError.stack,
+					code:
+						typeof serverError === "object" &&
+						serverError !== null &&
+						"code" in serverError
+							? String(serverError.code)
+							: undefined,
+				}
+				: { error: String(serverError) },
+		);
 		oauthServer = null;
 	}
 	let code: string | null = null;

test/codex-manager-cli.test.ts

@@ -3110,6 +3110,55 @@ describe("codex manager cli commands", () => {
 		expect(storageState.accounts).toHaveLength(1);
 	});
 
+	it("falls back to pasted manual input when Windows-style callback bind fails", async () => {
+		setInteractiveTTY(false);
+		const now = Date.now();
+		let storageState = {
+			version: 3 as const,
+			activeIndex: 0,
+			activeIndexByFamily: { codex: 0 },
+			accounts: [] as Array<Record<string, unknown>>,
+		};
+		loadAccountsMock.mockImplementation(async () => structuredClone(storageState));
+		saveAccountsMock.mockImplementation(async (nextStorage) => {
+			storageState = structuredClone(nextStorage);
+		});
+		promptLoginModeMock.mockResolvedValueOnce({ mode: "cancel" });
+		promptQuestionMock.mockResolvedValueOnce(
+			"http://127.0.0.1:1455/auth/callback?code=oauth-code&state=oauth-state",
+		);
+
+		const authModule = await import("../lib/auth/auth.js");
+		vi.mocked(authModule.createAuthorizationFlow).mockResolvedValueOnce({
+			pkce: { challenge: "pkce-challenge", verifier: "pkce-verifier" },
+			state: "oauth-state",
+			url: "https://auth.openai.com/mock",
+		});
+		vi.mocked(authModule.exchangeAuthorizationCode).mockResolvedValueOnce({
+			type: "success",
+			access: "access-eacces",
+			refresh: "refresh-eacces",
+			expires: now + 7_200_000,
+			idToken: "id-token-eacces",
+			multiAccount: true,
+		});
+
+		const browserModule = await import("../lib/auth/browser.js");
+		const openBrowserUrlMock = vi.mocked(browserModule.openBrowserUrl);
+		const serverModule = await import("../lib/auth/server.js");
+		vi.mocked(serverModule.startLocalOAuthServer).mockRejectedValueOnce(
+			Object.assign(new Error("permission denied"), { code: "EACCES" }),
+		);
+
+		const { runCodexMultiAuthCli } = await import("../lib/codex-manager.js");
+		const exitCode = await runCodexMultiAuthCli(["auth", "login", "--manual"]);
+
+		expect(exitCode).toBe(0);
+		expect(promptQuestionMock).toHaveBeenCalledWith("");
+		expect(openBrowserUrlMock).not.toHaveBeenCalled();
+		expect(storageState.accounts).toHaveLength(1);
+	});
+
 	it("preserves distinct same-email workspaces when oauth login reuses a refresh token", async () => {
 		const now = Date.now();
 		let storageState = {

test/index.test.ts

@@ -564,6 +564,7 @@ describe("OpenAIOAuthPlugin", () => {
 		it("uses manual auth flow when browser launch is globally suppressed", async () => {
 			const browserModule = await import("../lib/auth/browser.js");
 			vi.mocked(browserModule.isBrowserLaunchSuppressed).mockReturnValueOnce(true);
+			const openBrowserUrlMock = vi.mocked(browserModule.openBrowserUrl);
 			const autoMethod = plugin.auth.methods[0] as unknown as {
 				authorize: (inputs?: Record<string, string>) => Promise<{
 					method: string;
@@ -577,6 +578,7 @@ describe("OpenAIOAuthPlugin", () => {
 			expect(flow.method).toBe("code");
 			expect(flow.instructions).toContain("copy the full redirect URL");
 			expect(flow.validate("invalid-callback-value")).toContain("No authorization code found");
+			expect(openBrowserUrlMock).not.toHaveBeenCalled();
 		});
 
 		it("rejects manual OAuth callbacks with mismatched state", async () => {