Add an experimental Codex session supervisor

Author: ndycode

lib/codex-manager/settings-hub.ts

@@ -28,7 +28,7 @@ import type { PluginConfig } from "../types.js";
 import { ANSI } from "../ui/ansi.js";
 import { UI_COPY } from "../ui/copy.js";
 import { getUiRuntimeOptions, setUiRuntimeOptions } from "../ui/runtime.js";
-import { type MenuItem, select } from "../ui/select.js";
+import { type MenuItem, select, type SelectOptions } from "../ui/select.js";
 import { getUnifiedSettingsPath } from "../unified-settings.js";
 import { sleep } from "../utils.js";
 
@@ -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" }
@@ -281,12 +283,54 @@ type ExperimentalSettingsAction =
 	| { type: "save" }
 	| { type: "back" };
 
+function getExperimentalSelectOptions(
+	ui: ReturnType<typeof getUiRuntimeOptions>,
+	help: string,
+	onInput?: SelectOptions<ExperimentalSettingsAction>["onInput"],
+): SelectOptions<ExperimentalSettingsAction> {
+	return {
+		message: UI_COPY.settings.experimentalTitle,
+		subtitle: UI_COPY.settings.experimentalSubtitle,
+		help,
+		clearScreen: true,
+		theme: ui.theme,
+		selectedEmphasis: "minimal",
+		onInput,
+	};
+}
+
+function mapExperimentalMenuHotkey(
+	raw: string,
+): ExperimentalSettingsAction | undefined {
+	if (raw === "1") return { type: "toggle-session-supervisor" };
+	if (raw === "2") return { type: "sync" };
+	if (raw === "3") return { type: "backup" };
+	if (raw === "4") return { type: "toggle-refresh-guardian" };
+	if (raw === "[" || raw === "-") return { type: "decrease-refresh-interval" };
+	if (raw === "]" || raw === "+") return { type: "increase-refresh-interval" };
+	const lower = raw.toLowerCase();
+	if (lower === "q") return { type: "back" };
+	if (lower === "s") return { type: "save" };
+	return undefined;
+}
+
+function mapExperimentalStatusHotkey(
+	raw: string,
+): ExperimentalSettingsAction | undefined {
+	return raw.toLowerCase() === "q" ? { type: "back" } : undefined;
+}
+
 const BACKEND_TOGGLE_OPTIONS: BackendToggleSettingOption[] = [
 	{
 		key: "liveAccountSync",
 		label: "Enable Live Sync",
 		description: "Keep accounts synced when files change in another window.",
 	},
+	{
+		key: "codexCliSessionSupervisor",
+		label: "Enable Session Resume Supervisor",
+		description: "Wrap interactive Codex sessions so they can relaunch with resume after rotation.",
+	},
 	{
 		key: "sessionAffinity",
 		label: "Enable Session Affinity",
@@ -1279,6 +1323,8 @@ const __testOnly = {
 	cloneDashboardSettings,
 	withQueuedRetry: withQueuedRetryForTests,
 	loadExperimentalSyncTarget,
+	mapExperimentalMenuHotkey,
+	mapExperimentalStatusHotkey,
 	promptExperimentalSettings,
 	persistDashboardSettingsSelection: persistDashboardSettingsSelectionForTests,
 	persistBackendConfigSelection: persistBackendConfigSelectionForTests,
@@ -2530,6 +2576,11 @@ async function promptExperimentalSettings(
 	while (true) {
 		const action = await select<ExperimentalSettingsAction>(
 			[
+				{
+					label: `${formatDashboardSettingState(draft.codexCliSessionSupervisor ?? BACKEND_DEFAULTS.codexCliSessionSupervisor ?? false)} ${UI_COPY.settings.experimentalSessionSupervisor}`,
+					value: { type: "toggle-session-supervisor" },
+					color: "yellow",
+				},
 				{
 					label: UI_COPY.settings.experimentalSync,
 					value: { type: "sync" },
@@ -2573,19 +2624,25 @@ async function promptExperimentalSettings(
 					color: "red",
 				},
 			],
-			{
-				message: UI_COPY.settings.experimentalTitle,
-				subtitle: UI_COPY.settings.experimentalSubtitle,
-				help: UI_COPY.settings.experimentalHelpMenu,
-				clearScreen: true,
-				theme: ui.theme,
-				selectedEmphasis: "minimal",
-				onInput: (raw) =>
-					raw.toLowerCase() === "q" ? { type: "back" } : undefined,
-			},
+			getExperimentalSelectOptions(
+				ui,
+				UI_COPY.settings.experimentalHelpMenu,
+				mapExperimentalMenuHotkey,
+			),
 		);
 		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,
@@ -2647,14 +2704,11 @@ async function promptExperimentalSettings(
 								color: "red",
 							},
 						],
-						{
-							message: UI_COPY.settings.experimentalTitle,
-							subtitle: UI_COPY.settings.experimentalSubtitle,
-							help: UI_COPY.settings.experimentalHelpStatus,
-							clearScreen: true,
-							theme: ui.theme,
-							selectedEmphasis: "minimal",
-						},
+						getExperimentalSelectOptions(
+							ui,
+							UI_COPY.settings.experimentalHelpStatus,
+							mapExperimentalStatusHotkey,
+						),
 					);
 				} catch (error) {
 					const message =
@@ -2674,14 +2728,11 @@ async function promptExperimentalSettings(
 								color: "red",
 							},
 						],
-						{
-							message: UI_COPY.settings.experimentalTitle,
-							subtitle: UI_COPY.settings.experimentalSubtitle,
-							help: UI_COPY.settings.experimentalHelpStatus,
-							clearScreen: true,
-							theme: ui.theme,
-							selectedEmphasis: "minimal",
-						},
+						getExperimentalSelectOptions(
+							ui,
+							UI_COPY.settings.experimentalHelpStatus,
+							mapExperimentalStatusHotkey,
+						),
 					);
 				}
 			} finally {
@@ -2708,14 +2759,11 @@ async function promptExperimentalSettings(
 						color: "red",
 					},
 				],
-				{
-					message: UI_COPY.settings.experimentalTitle,
-					subtitle: UI_COPY.settings.experimentalSubtitle,
-					help: UI_COPY.settings.experimentalHelpStatus,
-					clearScreen: true,
-					theme: ui.theme,
-					selectedEmphasis: "minimal",
-				},
+				getExperimentalSelectOptions(
+					ui,
+					UI_COPY.settings.experimentalHelpStatus,
+					mapExperimentalStatusHotkey,
+				),
 			);
 			continue;
 		}
@@ -2747,14 +2795,11 @@ async function promptExperimentalSettings(
 						color: "red",
 					},
 				],
-				{
-					message: UI_COPY.settings.experimentalTitle,
-					subtitle: UI_COPY.settings.experimentalSubtitle,
-					help: UI_COPY.settings.experimentalHelpStatus,
-					clearScreen: true,
-					theme: ui.theme,
-					selectedEmphasis: "minimal",
-				},
+				getExperimentalSelectOptions(
+					ui,
+					UI_COPY.settings.experimentalHelpStatus,
+					mapExperimentalStatusHotkey,
+				),
 			);
 			continue;
 		}
@@ -2793,20 +2838,16 @@ async function promptExperimentalSettings(
 					color: "red",
 				},
 			],
-			{
-				message: UI_COPY.settings.experimentalTitle,
-				subtitle: UI_COPY.settings.experimentalSubtitle,
-				help: UI_COPY.settings.experimentalHelpStatus,
-				clearScreen: true,
-				theme: ui.theme,
-				selectedEmphasis: "minimal",
-				onInput: (raw) => {
+			getExperimentalSelectOptions(
+				ui,
+				UI_COPY.settings.experimentalHelpPreview,
+				(raw) => {
 					const lower = raw.toLowerCase();
 					if (lower === "q") return { type: "back" };
 					if (lower === "a") return { type: "apply" };
 					return undefined;
 				},
-			},
+			),
 		);
 		if (!review || review.type === "back") continue;
 
@@ -2837,14 +2878,11 @@ async function promptExperimentalSettings(
 				},
 				{ label: UI_COPY.settings.back, value: { type: "back" }, color: "red" },
 			],
-			{
-				message: UI_COPY.settings.experimentalTitle,
-				subtitle: UI_COPY.settings.experimentalSubtitle,
-				help: UI_COPY.settings.experimentalHelpStatus,
-				clearScreen: true,
-				theme: ui.theme,
-				selectedEmphasis: "minimal",
-			},
+			getExperimentalSelectOptions(
+				ui,
+				UI_COPY.settings.experimentalHelpStatus,
+				mapExperimentalStatusHotkey,
+			),
 		);
 	}
 }

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,13 @@ 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;
 }
 
 /**
@@ -331,6 +338,9 @@ export async function fetchCodexQuotaSnapshot(
 	let lastError: Error | null = null;
 
 	for (const model of models) {
+		if (options.signal?.aborted) {
+			throw createAbortError("Quota probe aborted");
+		}
 		try {
 			const instructions = await getCodexInstructions(model);
 			const probeBody: RequestBody = {
@@ -356,6 +366,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 +383,7 @@ export async function fetchCodexQuotaSnapshot(
 				});
 			} finally {
 				clearTimeout(timeout);
+				options.signal?.removeEventListener("abort", onAbort);
 			}
 
 			const snapshotBase = parseQuotaSnapshotBase(response.headers, response.status);
@@ -406,9 +423,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(),
@@ -82,7 +83,13 @@ export type CooldownReasonFromSchema = z.infer<typeof CooldownReasonSchema>;
 /**
  * Last switch reason for account rotation tracking.
  */
-export const SwitchReasonSchema = z.enum(["rate-limit", "initial", "rotation", "best"]);
+export const SwitchReasonSchema = z.enum([
+	"rate-limit",
+	"initial",
+	"rotation",
+	"best",
+	"restore",
+]);
 
 export type SwitchReasonFromSchema = z.infer<typeof SwitchReasonSchema>;