fix(auth): finish docs parity and isolate storage path state

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,6 +56,16 @@ 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.

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/storage.ts

@@ -167,6 +167,7 @@ export function formatStorageErrorHint(error: unknown, path: string): string {
 let storageMutex: Promise<void> = Promise.resolve();
 const transactionSnapshotContext = new AsyncLocalStorage<{
 	snapshot: AccountStorageV3 | null;
+	storagePath: string;
 	active: boolean;
 }>();
 
@@ -225,11 +226,12 @@ function looksLikeSyntheticFixtureStorage(
 }
 
 async function ensureGitignore(storagePath: string): Promise<void> {
-	if (!currentStoragePath) return;
+	const state = getStoragePathState();
+	if (!state.currentStoragePath) return;
 
 	const configDir = dirname(storagePath);
 	const inferredProjectRoot = dirname(configDir);
-	const candidateRoots = [currentProjectRoot, inferredProjectRoot].filter(
+	const candidateRoots = [state.currentProjectRoot, inferredProjectRoot].filter(
 		(root): root is string => typeof root === "string" && root.length > 0,
 	);
 	const projectRoot = candidateRoots.find((root) =>
@@ -262,10 +264,30 @@ async function ensureGitignore(storagePath: string): Promise<void> {
 	}
 }
 
-let currentStoragePath: string | null = null;
-let currentLegacyProjectStoragePath: string | null = null;
-let currentLegacyWorktreeStoragePath: string | null = null;
-let currentProjectRoot: string | null = null;
+type StoragePathState = {
+	currentStoragePath: string | null;
+	currentLegacyProjectStoragePath: string | null;
+	currentLegacyWorktreeStoragePath: string | null;
+	currentProjectRoot: string | null;
+};
+
+let currentStorageState: StoragePathState = {
+	currentStoragePath: null,
+	currentLegacyProjectStoragePath: null,
+	currentLegacyWorktreeStoragePath: null,
+	currentProjectRoot: null,
+};
+
+const storagePathStateContext = new AsyncLocalStorage<StoragePathState>();
+
+function getStoragePathState(): StoragePathState {
+	return storagePathStateContext.getStore() ?? currentStorageState;
+}
+
+function setStoragePathState(state: StoragePathState): void {
+	currentStorageState = state;
+	storagePathStateContext.enterWith(state);
+}
 
 export function setStorageBackupEnabled(enabled: boolean): void {
 	storageBackupEnabled = enabled;
@@ -754,55 +776,67 @@ export function getLastAccountsSaveTimestamp(): number {
 
 export function setStoragePath(projectPath: string | null): void {
 	if (!projectPath) {
-		currentStoragePath = null;
-		currentLegacyProjectStoragePath = null;
-		currentLegacyWorktreeStoragePath = null;
-		currentProjectRoot = null;
+		setStoragePathState({
+			currentStoragePath: null,
+			currentLegacyProjectStoragePath: null,
+			currentLegacyWorktreeStoragePath: null,
+			currentProjectRoot: null,
+		});
 		return;
 	}
 
 	const projectRoot = findProjectRoot(projectPath);
 	if (projectRoot) {
-		currentProjectRoot = projectRoot;
 		const identityRoot = resolveProjectStorageIdentityRoot(projectRoot);
-		currentStoragePath = join(
+		const currentStoragePath = join(
 			getProjectGlobalConfigDir(identityRoot),
 			ACCOUNTS_FILE_NAME,
 		);
-		currentLegacyProjectStoragePath = join(
+		const currentLegacyProjectStoragePath = join(
 			getProjectConfigDir(projectRoot),
 			ACCOUNTS_FILE_NAME,
 		);
 		const previousWorktreeScopedPath = join(
 			getProjectGlobalConfigDir(projectRoot),
 			ACCOUNTS_FILE_NAME,
 		);
-		currentLegacyWorktreeStoragePath =
+		const currentLegacyWorktreeStoragePath =
 			previousWorktreeScopedPath !== currentStoragePath
 				? previousWorktreeScopedPath
 				: null;
+		setStoragePathState({
+			currentStoragePath,
+			currentLegacyProjectStoragePath,
+			currentLegacyWorktreeStoragePath,
+			currentProjectRoot: projectRoot,
+		});
 	} else {
-		currentStoragePath = null;
-		currentLegacyProjectStoragePath = null;
-		currentLegacyWorktreeStoragePath = null;
-		currentProjectRoot = null;
+		setStoragePathState({
+			currentStoragePath: null,
+			currentLegacyProjectStoragePath: null,
+			currentLegacyWorktreeStoragePath: null,
+			currentProjectRoot: null,
+		});
 	}
 }
 
 export function setStoragePathDirect(path: string | null): void {
-	currentStoragePath = path;
-	currentLegacyProjectStoragePath = null;
-	currentLegacyWorktreeStoragePath = null;
-	currentProjectRoot = null;
+	setStoragePathState({
+		currentStoragePath: path,
+		currentLegacyProjectStoragePath: null,
+		currentLegacyWorktreeStoragePath: null,
+		currentProjectRoot: null,
+	});
 }
 
 /**
  * Returns the file path for the account storage JSON file.
  * @returns Absolute path to the accounts.json file
  */
 export function getStoragePath(): string {
-	if (currentStoragePath) {
-		return currentStoragePath;
+	const state = getStoragePathState();
+	if (state.currentStoragePath) {
+		return state.currentStoragePath;
 	}
 	return join(getConfigDir(), ACCOUNTS_FILE_NAME);
 }
@@ -836,19 +870,20 @@ function getLegacyFlaggedAccountsPath(): string {
 async function migrateLegacyProjectStorageIfNeeded(
 	persist: (storage: AccountStorageV3) => Promise<void> = saveAccounts,
 ): Promise<AccountStorageV3 | null> {
-	if (!currentStoragePath) {
+	const state = getStoragePathState();
+	if (!state.currentStoragePath) {
 		return null;
 	}
 
 	const candidatePaths = [
-		currentLegacyWorktreeStoragePath,
-		currentLegacyProjectStoragePath,
+		state.currentLegacyWorktreeStoragePath,
+		state.currentLegacyProjectStoragePath,
 	]
 		.filter(
 			(path): path is string =>
 				typeof path === "string" &&
 				path.length > 0 &&
-				path !== currentStoragePath,
+				path !== state.currentStoragePath,
 		)
 		.filter((path, index, all) => all.indexOf(path) === index);
 
@@ -864,7 +899,7 @@ async function migrateLegacyProjectStorageIfNeeded(
 	}
 
 	let targetStorage = await loadNormalizedStorageFromPath(
-		currentStoragePath,
+		state.currentStoragePath,
 		"current account storage",
 	);
 	let migrated = false;
@@ -892,7 +927,7 @@ async function migrateLegacyProjectStorageIfNeeded(
 			targetStorage = fallbackStorage;
 			log.warn("Failed to persist migrated account storage", {
 				from: legacyPath,
-				to: currentStoragePath,
+				to: state.currentStoragePath,
 				error: String(error),
 			});
 			continue;
@@ -918,15 +953,15 @@ async function migrateLegacyProjectStorageIfNeeded(
 
 		log.info("Migrated legacy project account storage", {
 			from: legacyPath,
-			to: currentStoragePath,
+			to: state.currentStoragePath,
 			accounts: mergedStorage.accounts.length,
 		});
 	}
 
 	if (migrated) {
 		return targetStorage;
 	}
-	if (targetStorage && !existsSync(currentStoragePath)) {
+	if (targetStorage && !existsSync(state.currentStoragePath)) {
 		return targetStorage;
 	}
 	return null;
@@ -1912,8 +1947,10 @@ export async function withAccountStorageTransaction<T>(
 	) => Promise<T>,
 ): Promise<T> {
 	return withStorageLock(async () => {
+		const storagePath = getStoragePath();
 		const state = {
 			snapshot: await loadAccountsInternal(saveAccountsUnlocked),
+			storagePath,
 			active: true,
 		};
 		const current = state.snapshot;
@@ -1937,8 +1974,10 @@ export async function withAccountAndFlaggedStorageTransaction<T>(
 	) => Promise<T>,
 ): Promise<T> {
 	return withStorageLock(async () => {
+		const storagePath = getStoragePath();
 		const state = {
 			snapshot: await loadAccountsInternal(saveAccountsUnlocked),
+			storagePath,
 			active: true,
 		};
 		const current = state.snapshot;
@@ -2308,17 +2347,22 @@ export async function exportAccounts(
 	beforeCommit?: (resolvedPath: string) => Promise<void> | void,
 ): Promise<void> {
 	const resolvedPath = resolvePath(filePath);
+	const currentStoragePath = getStoragePath();
 
 	if (!force && existsSync(resolvedPath)) {
 		throw new Error(`File already exists: ${resolvedPath}`);
 	}
 
 	const transactionState = transactionSnapshotContext.getStore();
-	const storage = transactionState?.active
-		? transactionState.snapshot
-		: await withAccountStorageTransaction((current) =>
-				Promise.resolve(current),
-			);
+	const storage =
+		transactionState?.active &&
+		transactionState.storagePath === currentStoragePath
+			? transactionState.snapshot
+			: transactionState?.active
+				? await loadAccountsInternal(saveAccountsUnlocked)
+				: await withAccountStorageTransaction((current) =>
+						Promise.resolve(current),
+					);
 	if (!storage || storage.accounts.length === 0) {
 		throw new Error("No accounts to export");
 	}