feat: add experimental Codex session supervisor

lib/codex-manager/settings-hub.ts

@@ -186,6 +186,7 @@ type ThemeConfigAction =
 
 type BackendToggleSettingKey =
 	| "liveAccountSync"
+	| "codexCliSessionSupervisor"
 	| "sessionAffinity"
 	| "proactiveRefreshGuardian"
 	| "retryAllAccountsRateLimited"
@@ -272,6 +273,7 @@ type SettingsHubAction =
 	| { type: "back" };
 
 type ExperimentalSettingsAction =
+	| { type: "toggle-session-supervisor" }
 	| { type: "sync" }
 	| { type: "backup" }
 	| { type: "toggle-refresh-guardian" }
@@ -303,6 +305,7 @@ function mapExperimentalMenuHotkey(
 	if (raw === "1") return { type: "sync" };
 	if (raw === "2") return { type: "backup" };
 	if (raw === "3") return { type: "toggle-refresh-guardian" };
+	if (raw === "4") return { type: "toggle-session-supervisor" };
 	if (raw === "[" || raw === "-") return { type: "decrease-refresh-interval" };
 	if (raw === "]" || raw === "+") return { type: "increase-refresh-interval" };
 	const lower = raw.toLowerCase();
@@ -2583,6 +2586,11 @@ async function promptExperimentalSettings(
 					value: { type: "toggle-refresh-guardian" },
 					color: "yellow",
 				},
+				{
+					label: `${formatDashboardSettingState(draft.codexCliSessionSupervisor ?? BACKEND_DEFAULTS.codexCliSessionSupervisor ?? false)} ${UI_COPY.settings.experimentalSessionSupervisor}`,
+					value: { type: "toggle-session-supervisor" },
+					color: "yellow",
+				},
 				{
 					label: `${UI_COPY.settings.experimentalRefreshInterval}: ${Math.round((draft.proactiveRefreshIntervalMs ?? 60000) / 60000)} min`,
 					value: { type: "back" },
@@ -2619,6 +2627,17 @@ async function promptExperimentalSettings(
 		);
 		if (!action || action.type === "back") return null;
 		if (action.type === "save") return draft;
+		if (action.type === "toggle-session-supervisor") {
+			draft = {
+				...draft,
+				codexCliSessionSupervisor: !(
+					draft.codexCliSessionSupervisor ??
+					BACKEND_DEFAULTS.codexCliSessionSupervisor ??
+					false
+				),
+			};
+			continue;
+		}
 		if (action.type === "toggle-refresh-guardian") {
 			draft = {
 				...draft,

lib/config.ts

@@ -145,6 +145,7 @@ export const DEFAULT_PLUGIN_CONFIG: PluginConfig = {
 	liveAccountSync: true,
 	liveAccountSyncDebounceMs: 250,
 	liveAccountSyncPollMs: 2_000,
+	codexCliSessionSupervisor: false,
 	sessionAffinity: true,
 	sessionAffinityTtlMs: 20 * 60_000,
 	sessionAffinityMaxEntries: 512,
@@ -857,6 +858,25 @@ export function getLiveAccountSyncPollMs(pluginConfig: PluginConfig): number {
 	);
 }
 
+/**
+ * Determines whether the CLI session supervisor wrapper is enabled.
+ *
+ * This accessor is synchronous, side-effect free, and safe for concurrent reads.
+ * It performs no filesystem I/O and does not expose token material.
+ *
+ * @param pluginConfig - The plugin configuration object used as the non-environment fallback
+ * @returns `true` when the session supervisor should wrap interactive Codex sessions
+ */
+export function getCodexCliSessionSupervisor(
+	pluginConfig: PluginConfig,
+): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_CLI_SESSION_SUPERVISOR",
+		pluginConfig.codexCliSessionSupervisor,
+		false,
+	);
+}
+
 /**
  * Indicates whether session affinity is enabled.
  *

lib/quota-probe.ts

@@ -305,6 +305,19 @@ export interface ProbeCodexQuotaOptions {
 	model?: string;
 	fallbackModels?: readonly string[];
 	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+
+function createAbortError(message: string): Error {
+	const error = new Error(message);
+	error.name = "AbortError";
+	return error;
+}
+
+function throwIfQuotaProbeAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) {
+		throw createAbortError("Quota probe aborted");
+	}
 }
 
 /**
@@ -331,8 +344,11 @@ export async function fetchCodexQuotaSnapshot(
 	let lastError: Error | null = null;
 
 	for (const model of models) {
+		throwIfQuotaProbeAborted(options.signal);
 		try {
+			throwIfQuotaProbeAborted(options.signal);
 			const instructions = await getCodexInstructions(model);
+			throwIfQuotaProbeAborted(options.signal);
 			const probeBody: RequestBody = {
 				model,
 				stream: true,
@@ -356,6 +372,12 @@ export async function fetchCodexQuotaSnapshot(
 			headers.set("content-type", "application/json");
 
 			const controller = new AbortController();
+			const onAbort = () => controller.abort(options.signal?.reason);
+			if (options.signal?.aborted) {
+				controller.abort(options.signal.reason);
+			} else {
+				options.signal?.addEventListener("abort", onAbort, { once: true });
+			}
 			const timeout = setTimeout(() => controller.abort(), timeoutMs);
 			let response: Response;
 			try {
@@ -367,6 +389,7 @@ export async function fetchCodexQuotaSnapshot(
 				});
 			} finally {
 				clearTimeout(timeout);
+				options.signal?.removeEventListener("abort", onAbort);
 			}
 
 			const snapshotBase = parseQuotaSnapshotBase(response.headers, response.status);
@@ -390,6 +413,7 @@ export async function fetchCodexQuotaSnapshot(
 
 				const unsupportedInfo = getUnsupportedCodexModelInfo(errorBody);
 				if (unsupportedInfo.isUnsupported) {
+					throwIfQuotaProbeAborted(options.signal);
 					lastError = new Error(
 						unsupportedInfo.message ?? `Model '${model}' unsupported for this account`,
 					);
@@ -406,9 +430,16 @@ export async function fetchCodexQuotaSnapshot(
 			}
 			lastError = new Error("Codex response did not include quota headers");
 		} catch (error) {
+			if (options.signal?.aborted) {
+				throw error instanceof Error ? error : createAbortError("Quota probe aborted");
+			}
 			lastError = error instanceof Error ? error : new Error(String(error));
 		}
 	}
 
+	if (options.signal?.aborted) {
+		throw createAbortError("Quota probe aborted");
+	}
+
 	throw lastError ?? new Error("Failed to fetch quotas");
 }

lib/schemas.ts

@@ -44,6 +44,7 @@ export const PluginConfigSchema = z.object({
 	liveAccountSync: z.boolean().optional(),
 	liveAccountSyncDebounceMs: z.number().min(50).optional(),
 	liveAccountSyncPollMs: z.number().min(500).optional(),
+	codexCliSessionSupervisor: z.boolean().optional(),
 	sessionAffinity: z.boolean().optional(),
 	sessionAffinityTtlMs: z.number().min(1_000).optional(),
 	sessionAffinityMaxEntries: z.number().min(8).optional(),

lib/storage.ts

@@ -381,6 +381,29 @@ function getAccountsBackupRecoveryCandidates(path: string): string[] {
 	return candidates;
 }
 
+async function normalizeStorageComparisonPath(path: string): Promise<string> {
+	let resolved = resolvePath(path);
+	try {
+		resolved = await fs.realpath(resolved);
+	} catch {
+		// Fall back to the normalized input when the path does not exist yet.
+	}
+	if (process.platform !== "win32") {
+		return resolved;
+	}
+	return resolved.replaceAll("\\", "/").toLowerCase();
+}
+
+async function areEquivalentStoragePaths(
+	left: string,
+	right: string,
+): Promise<boolean> {
+	return (
+		(await normalizeStorageComparisonPath(left)) ===
+		(await normalizeStorageComparisonPath(right))
+	);
+}
+
 async function getAccountsBackupRecoveryCandidatesWithDiscovery(
 	path: string,
 ): Promise<string[]> {
@@ -813,8 +836,13 @@ function latestValidSnapshot(
 	snapshots: BackupSnapshotMetadata[],
 ): BackupSnapshotMetadata | undefined {
 	return snapshots
-		.filter((snapshot) => snapshot.valid)
-		.sort((left, right) => (right.mtimeMs ?? 0) - (left.mtimeMs ?? 0))[0];
+		.map((snapshot, index) => ({ snapshot, index }))
+		.filter(({ snapshot }) => snapshot.valid)
+		.sort(
+			(left, right) =>
+				(right.snapshot.mtimeMs ?? 0) - (left.snapshot.mtimeMs ?? 0) ||
+				left.index - right.index,
+		)[0]?.snapshot;
 }
 
 function buildMetadataSection(
@@ -1761,8 +1789,9 @@ async function loadAccountsFromJournal(
 
 async function loadAccountsInternal(
 	persistMigration: ((storage: AccountStorageV3) => Promise<void>) | null,
+	storagePath = getStoragePath(),
 ): Promise<AccountStorageV3 | null> {
-	const path = getStoragePath();
+	const path = storagePath;
 	const resetMarkerPath = getIntentionalResetMarkerPath(path);
 	await cleanupStaleRotatingBackupArtifacts(path);
 	const migratedLegacyStorage = persistMigration
@@ -1926,8 +1955,11 @@ async function loadAccountsInternal(
 	}
 }
 
-async function saveAccountsUnlocked(storage: AccountStorageV3): Promise<void> {
-	const path = getStoragePath();
+async function saveAccountsUnlocked(
+	storage: AccountStorageV3,
+	storagePath = getStoragePath(),
+): Promise<void> {
+	const path = storagePath;
 	const resetMarkerPath = getIntentionalResetMarkerPath(path);
 	const uniqueSuffix = `${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
 	const tempPath = `${path}.${uniqueSuffix}.tmp`;
@@ -2078,18 +2110,25 @@ export async function withAccountStorageTransaction<T>(
 	return withStorageLock(async () => {
 		const storagePath = getStoragePath();
 		const state = {
-			snapshot: await loadAccountsInternal(saveAccountsUnlocked),
-			storagePath,
+			snapshot: await loadAccountsInternal(
+				(storage) => saveAccountsUnlocked(storage, storagePath),
+				storagePath,
+			),
 			active: true,
+			storagePath,
 		};
 		const current = state.snapshot;
 		const persist = async (storage: AccountStorageV3): Promise<void> => {
-			await saveAccountsUnlocked(storage);
+			await saveAccountsUnlocked(storage, storagePath);
 			state.snapshot = storage;
 		};
-		return transactionSnapshotContext.run(state, () =>
-			handler(current, persist),
-		);
+		return transactionSnapshotContext.run(state, async () => {
+			try {
+				return await handler(current, persist);
+			} finally {
+				state.active = false;
+			}
+		});
 	});
 }
 
@@ -2104,10 +2143,14 @@ export async function withAccountAndFlaggedStorageTransaction<T>(
 ): Promise<T> {
 	return withStorageLock(async () => {
 		const storagePath = getStoragePath();
+		const flaggedStoragePath = getFlaggedAccountsPath();
 		const state = {
-			snapshot: await loadAccountsInternal(saveAccountsUnlocked),
-			storagePath,
+			snapshot: await loadAccountsInternal(
+				(storage) => saveAccountsUnlocked(storage, storagePath),
+				storagePath,
+			),
 			active: true,
+			storagePath,
 		};
 		const current = state.snapshot;
 		const persist = async (
@@ -2116,13 +2159,13 @@ export async function withAccountAndFlaggedStorageTransaction<T>(
 		): Promise<void> => {
 			const previousAccounts = cloneAccountStorageForPersistence(state.snapshot);
 			const nextAccounts = cloneAccountStorageForPersistence(accountStorage);
-			await saveAccountsUnlocked(nextAccounts);
+			await saveAccountsUnlocked(nextAccounts, storagePath);
 			try {
-				await saveFlaggedAccountsUnlocked(flaggedStorage);
+				await saveFlaggedAccountsUnlocked(flaggedStorage, flaggedStoragePath);
 				state.snapshot = nextAccounts;
 			} catch (error) {
 				try {
-					await saveAccountsUnlocked(previousAccounts);
+					await saveAccountsUnlocked(previousAccounts, storagePath);
 					state.snapshot = previousAccounts;
 				} catch (rollbackError) {
 					const combinedError = new AggregateError(
@@ -2141,9 +2184,13 @@ export async function withAccountAndFlaggedStorageTransaction<T>(
 				throw error;
 			}
 		};
-		return transactionSnapshotContext.run(state, () =>
-			handler(current, persist),
-		);
+		return transactionSnapshotContext.run(state, async () => {
+			try {
+				return await handler(current, persist);
+			} finally {
+				state.active = false;
+			}
+		});
 	});
 }
 
@@ -2377,8 +2424,9 @@ export async function loadFlaggedAccounts(): Promise<FlaggedAccountStorageV1> {
 
 async function saveFlaggedAccountsUnlocked(
 	storage: FlaggedAccountStorageV1,
+	storagePath = getFlaggedAccountsPath(),
 ): Promise<void> {
-	const path = getFlaggedAccountsPath();
+	const path = storagePath;
 	const markerPath = getIntentionalResetMarkerPath(path);
 	const uniqueSuffix = `${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
 	const tempPath = `${path}.${uniqueSuffix}.tmp`;
@@ -2477,22 +2525,32 @@ export async function exportAccounts(
 	beforeCommit?: (resolvedPath: string) => Promise<void> | void,
 ): Promise<void> {
 	const resolvedPath = resolvePath(filePath);
-	const currentStoragePath = getStoragePath();
+	const activeStoragePath = getStoragePath();
 
 	if (!force && existsSync(resolvedPath)) {
 		throw new Error(`File already exists: ${resolvedPath}`);
 	}
 
 	const transactionState = transactionSnapshotContext.getStore();
-	const storage =
+	if (
 		transactionState?.active &&
-		transactionState.storagePath === currentStoragePath
-			? transactionState.snapshot
-			: transactionState?.active
-				? await loadAccountsInternal(saveAccountsUnlocked)
-				: await withAccountStorageTransaction((current) =>
-						Promise.resolve(current),
-					);
+		!(await areEquivalentStoragePaths(
+			transactionState.storagePath,
+			activeStoragePath,
+		))
+	) {
+		// A fresh load here can silently export from the wrong storage file while a
+		// different transaction still owns the current snapshot.
+		throw new Error(
+			`Export blocked by storage path mismatch: transaction path is ` +
+				`${transactionState.storagePath}, active path is ${activeStoragePath}`,
+		);
+	}
+	const storage = transactionState?.active
+		? transactionState.snapshot
+		: await withAccountStorageTransaction((current) =>
+				Promise.resolve(current),
+			);
 	if (!storage || storage.accounts.length === 0) {
 		throw new Error("No accounts to export");
 	}

lib/ui/copy.ts

@@ -95,9 +95,10 @@ export const UI_COPY = {
 		experimentalTitle: "Experimental",
 		experimentalSubtitle: "Preview sync and backup actions before they become stable",
 		experimentalHelpMenu:
-			"Enter Select | 1 Sync | 2 Backup | 3 Guard | [ - Down | ] + Up | S Save | Q Back",
+			"Enter Select | 1 Sync | 2 Backup | 3 Guard | 4 Supervisor | [ - Down | ] + Up | S Save | Q Back",
 		experimentalHelpPreview: "Enter Select | A Apply | Q Back",
 		experimentalHelpStatus: "Enter Select | Q Back",
+		experimentalSessionSupervisor: "Enable Session Resume Supervisor",
 		experimentalSync: "Sync Accounts to oc-chatgpt-multi-auth",
 		experimentalApplySync: "Apply Sync",
 		experimentalBackup: "Save Pool Backup",