Merge branch 'git-plan/01-headless-auth' into git-plan/02-workspace-routing

Author: ndycode

README.md

@@ -109,6 +109,21 @@ codex auth fix --dry-run
 codex auth doctor --fix
 ```
 
+If the shell should not launch a browser, use the manual callback flow:
+
+```bash
+codex auth login --manual
+CODEX_AUTH_NO_BROWSER=1 codex auth login
+```
+
+In non-TTY/manual shells, provide the full redirect URL on stdin instead of waiting for a browser callback:
+
+```bash
+echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual
+```
+
+No new npm scripts or storage migration steps are required for this login-flow update.
+
 ---
 
 ## Command Toolkit
@@ -234,6 +249,7 @@ codex auth login
 - `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
 - Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
 - OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
+- Browser launch is blocked or you are in a headless shell: re-run `codex auth login --manual` or set `CODEX_AUTH_NO_BROWSER=1`
 - `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
 
 </details>

docs/features.md

@@ -54,7 +54,9 @@ User-facing capability map for `codex-multi-auth`.
 | Quick switch and search hotkeys | Faster navigation in the dashboard |
 | Account action hotkeys | Per-account set, refresh, toggle, and delete shortcuts |
 | In-dashboard settings hub | Runtime and display tuning without editing files directly |
-| Browser-first OAuth with manual fallback | Works in normal and constrained terminal environments |
+| Browser-first OAuth with manual fallback | `codex auth login` stays browser-first, while `--manual`, `--no-browser`, and `CODEX_AUTH_NO_BROWSER=1` keep login usable in browser-restricted shells |
+
+Manual/non-TTY login accepts the full callback URL on stdin, so automation and host-managed shells can complete auth without relying on a local browser handoff.
 
 ---
 

docs/getting-started.md

@@ -56,6 +56,21 @@ codex auth list
 codex auth check
 ```
 
+If browser launch is blocked or you want to handle the callback manually:
+
+```bash
+codex auth login --manual
+CODEX_AUTH_NO_BROWSER=1 codex auth login
+```
+
+In non-TTY/manual shells, provide the full redirect URL on stdin:
+
+```bash
+echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual
+```
+
+`codex auth login` remains browser-first by default. No new npm scripts or storage migration steps are required for this auth-flow update.
+
 ---
 
 ## Add More Accounts
@@ -111,6 +126,7 @@ If the OAuth callback on port `1455` fails:
 
 - stop the process using port `1455`
 - rerun `codex auth login`
+- if browser launch is unavailable, rerun `codex auth login --manual`
 
 If account state looks stale:
 

docs/reference/commands.md

@@ -56,12 +56,23 @@ Compatibility aliases are supported:
 
 ---
 
+## Upgrade Notes
+
+- `codex auth login` remains browser-first by default.
+- `codex auth login --manual` and `codex auth login --no-browser` force the manual callback flow instead of launching a browser.
+- `CODEX_AUTH_NO_BROWSER=1` suppresses browser launch for automation/headless sessions. False-like values such as `0` and `false` do not disable browser launch by themselves.
+- In non-TTY/manual shells, pass the full redirect URL on stdin, for example: `echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual`.
+- No new npm scripts or storage migration steps were introduced for this auth-flow update.
+
+---
+
 ## Compatibility and Non-TTY Behavior
 
 - `codex` remains the primary wrapper entrypoint. It routes `codex auth ...` and the compatibility aliases to the multi-auth runtime, and forwards every other command to the official `@openai/codex` CLI.
 - 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`.
 
 ---
 

docs/upgrade.md

@@ -49,6 +49,18 @@ codex auth forecast --live --model gpt-5-codex
 
 ---
 
+## Login Flow Upgrade Notes
+
+- `codex auth login` remains the default browser-first path.
+- `codex auth login --manual` and `codex auth login --no-browser` force manual callback handling for browser-restricted shells.
+- `CODEX_AUTH_NO_BROWSER=1` suppresses browser launch for automation/headless sessions. False-like values such as `0` and `false` no longer force manual mode.
+- 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`.
+- No new npm scripts, storage migrations, or extra upgrade steps were introduced for this auth-flow change.
+
+For the full command/behavior reference, see [reference/commands.md](reference/commands.md).
+
+---
+
 ## Configuration Upgrade Notes
 
 During upgrades, runtime config source precedence is:

lib/auth/browser.ts

@@ -9,6 +9,7 @@ import path from "node:path";
 import { PLATFORM_OPENERS } from "../constants.js";
 
 const BROWSER_DISABLED_VALUES = new Set(["0", "false", "no", "off", "none"]);
+const NO_BROWSER_TRUTHY_VALUES = new Set(["1", "true", "yes", "on"]);
 
 /**
  * Gets the platform-specific command to open a URL in the default browser
@@ -23,8 +24,8 @@ export function getBrowserOpener(): string {
 
 export function isBrowserLaunchSuppressed(): boolean {
 	const explicitNoBrowser = (process.env.CODEX_AUTH_NO_BROWSER ?? "").trim().toLowerCase();
-	if (explicitNoBrowser === "1" || BROWSER_DISABLED_VALUES.has(explicitNoBrowser)) {
-		return true;
+	if (explicitNoBrowser.length > 0) {
+		return NO_BROWSER_TRUTHY_VALUES.has(explicitNoBrowser);
 	}
 
 	const browserSetting = (process.env.BROWSER ?? "").trim().toLowerCase();

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();
@@ -1141,7 +1144,50 @@ async function promptManualCallback(
 			console.log("");
 			console.log(stylePromptText(UI_COPY.oauth.pastePrompt, "accent"));
 		}
-		const answer = await rl.question(useInteractivePrompt ? "◆  " : "");
+		const answer = useInteractivePrompt
+			? await rl.question("◆  ")
+			: await new Promise<string | null>((resolve, reject) => {
+					if (input.readableEnded || input.destroyed) {
+						resolve(null);
+						return;
+					}
+					let settled = false;
+					const handleInputClosed = () => {
+						if (settled) return;
+						settled = true;
+						input.off("end", handleInputClosed);
+						input.off("close", handleInputClosed);
+						resolve(null);
+					};
+					const finish = (value: string) => {
+						if (settled) return;
+						settled = true;
+						input.off("end", handleInputClosed);
+						input.off("close", handleInputClosed);
+						resolve(value);
+					};
+					const fail = (error: unknown) => {
+						if (settled) return;
+						settled = true;
+						input.off("end", handleInputClosed);
+						input.off("close", handleInputClosed);
+						reject(error);
+					};
+					rl.question("")
+						.then((value) => finish(value))
+						.catch((error) => {
+							if (isAbortError(error) || isReadlineClosedError(error)) {
+								handleInputClosed();
+								return;
+							}
+							fail(error);
+						});
+					input.once("end", handleInputClosed);
+					input.once("close", handleInputClosed);
+				});
+		if (answer === null) {
+			return null;
+		}
 		if (answer.includes("\u001b")) {
 			return null;
 		}
@@ -1160,7 +1206,7 @@ async function promptManualCallback(
 		if (parsed.state && parsed.state !== state) return null;
 		return parsed.code;
 	} catch (error) {
-		if (isAbortError(error)) {
+		if (isAbortError(error) || isReadlineClosedError(error)) {
 			return null;
 		}
 		throw error;
@@ -1169,6 +1215,17 @@ async function promptManualCallback(
 	}
 }
 
+function isReadlineClosedError(error: unknown): boolean {
+	if (!(error instanceof Error)) {
+		return false;
+	}
+	const errorCode =
+		typeof error === "object" && error !== null && "code" in error
+			? String((error as { code?: unknown }).code)
+			: "";
+	return errorCode === "ERR_USE_AFTER_CLOSE" || /readline was closed/i.test(error.message);
+}
+
 type OAuthSignInMode = "browser" | "manual" | "cancel";
 
 async function promptOAuthSignInMode(): Promise<OAuthSignInMode> {
@@ -1468,13 +1525,8 @@ async function runOAuthFlow(
 ): Promise<TokenResult> {
 	const { pkce, state, url } = await createAuthorizationFlow({ forceNewLogin });
 	const preferManualMode = options.manual || isBrowserLaunchSuppressed();
-	let oauthServer: Awaited<ReturnType<typeof startLocalOAuthServer>> | null = null;
-	try {
-		oauthServer = await startLocalOAuthServer({ state });
-	} catch {
-		oauthServer = null;
-	}
 	let code: string | null = null;
+	let oauthServer: Awaited<ReturnType<typeof startLocalOAuthServer>> | null = null;
 	try {
 		const signInMode = preferManualMode ? "manual" : await promptOAuthSignInMode();
 		if (signInMode === "cancel") {
@@ -1485,6 +1537,29 @@ async function runOAuthFlow(
 			};
 		}
 
+		if (signInMode === "browser") {
+			try {
+				oauthServer = await startLocalOAuthServer({ state });
+			} 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;
+			}
+		}
+
 		if (signInMode === "browser") {
 			const opened = openBrowserUrl(url);
 			if (opened) {
@@ -1523,7 +1598,9 @@ async function runOAuthFlow(
 				stylePromptText(
 					waitingForCallback
 						? UI_COPY.oauth.callbackMissed
-						: UI_COPY.oauth.callbackUnavailable,
+						: signInMode === "manual"
+							? UI_COPY.oauth.callbackBypassed
+							: UI_COPY.oauth.callbackUnavailable,
 					"warning",
 				),
 			);