@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/cli/registry.ts

@@ -0,0 +1,384 @@
+export interface CliCommandEntry {
+  name: string;
+  aliases?: string[];
+  usage: string;
+  summary: string;
+  details?: string[];
+  hidden?: boolean;
+}
+
+export const CLI_COMMANDS: CliCommandEntry[] = [
+  {
+    name: "init",
+    aliases: ["setup"],
+    usage: "ocx init",
+    summary: "Interactive setup for providers and Codex config injection.",
+  },
+  {
+    name: "setup",
+    aliases: [],
+    usage: "ocx setup",
+    summary: "Interactive setup for providers and Codex config injection (alias of init).",
+  },
+  { name: "start", usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
+  { name: "stop", usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
+  {
+    name: "restore",
+    aliases: ["eject"],
+    usage: "ocx restore [back]",
+    summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
+  },
+  {
+    name: "eject",
+    aliases: [],
+    usage: "ocx eject [back]",
+    summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
+  },
+  {
+    name: "recover-history",
+    usage: "ocx recover-history --legacy-openai",
+    summary: "Explicitly recover pre-backup syncResumeHistory rows.",
+  },
+  {
+    name: "uninstall",
+    aliases: ["remove"],
+    usage: "ocx uninstall",
+    summary: "Remove service/shim/config and restore native Codex.",
+    details: [
+      "Alias: ocx remove",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
+  },
+  {
+    name: "remove",
+    aliases: [],
+    usage: "ocx remove",
+    summary: "Remove service/shim/config and restore native Codex.",
+    details: [
+      "Alias of: ocx uninstall",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
+  },
+  {
+    name: "service",
+    usage: "ocx service [install|start|stop|status|uninstall|remove]",
+    summary: "Run as a background service.",
+    details: [
+      "With no subcommand, installs/updates and starts the background service.",
+      "Use `ocx service status` to see diagnostics and log paths.",
+    ],
+  },
+  {
+    name: "codex-shim",
+    usage: "ocx codex-shim <install|status|uninstall|remove>",
+    summary: "Auto-start the proxy when `codex` launches.",
+    details: ["Use `remove` as an alias for `uninstall`."],
+  },
+  {
+    name: "tray",
+    usage: "ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]",
+    summary: "Install and control the Windows status tray icon.",
+    details: [
+      "The tray starts at Windows login and provides one-click proxy controls.",
+      "Tray start/stop controls the icon only; use its menu to start or stop the proxy.",
+      "--no-start (install only) installs the tray without launching it immediately.",
+    ],
+  },
+  { name: "ensure", usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
+  {
+    name: "sync",
+    usage: "ocx sync [--restart-codex]",
+    summary: "Fetch provider models and inject them into Codex config.",
+    details: [
+      "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  {
+    name: "sync-cache",
+    usage: "ocx sync-cache [--restart-codex]",
+    summary: "Refresh Codex's model cache from the active catalog.",
+    details: [
+      "Warns when Codex app-server processes still hold an in-memory model list.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  { name: "status", usage: "ocx status", summary: "Check proxy server status." },
+  {
+    name: "doctor",
+    usage: "ocx doctor",
+    summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability).",
+  },
+  {
+    name: "debug",
+    usage: "ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>",
+    summary: "Show or toggle runtime provider, usage, injection, and Claude debug capture.",
+    details: [
+      "Provider: ocx debug provider on | off | status | reset | logs [-f]",
+      "Usage JSONL: ocx debug usage on | off | status | reset | logs [-f]",
+      "Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
+    ],
+  },
+  { name: "login", usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
+  { name: "logout", usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
+  { name: "gui", usage: "ocx gui", summary: "Open the opencodex dashboard." },
+  {
+    name: "update",
+    usage: "ocx update [--tag latest|preview]",
+    summary: "Update opencodex. Preview installs stay on the preview tag unless overridden.",
+  },
+  {
+    name: "provider",
+    usage: "ocx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
+    summary: "Non-interactive provider management.",
+    details: [
+      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
+      "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
+      "Run `ocx provider --help` for full usage and examples.",
+    ],
+  },
+  {
+    name: "account",
+    usage: "ocx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
+    summary: "List and switch provider accounts and API-key pools (GUI parity).",
+    details: [
+      "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
+      "current <provider>  Show the active account or key.",
+      "use <provider> <id> Switch the active credential; 'main' selects the Codex App login.",
+      "refresh <provider>  Force-refresh Codex or provider quota reports.",
+      "auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.",
+      "priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.",
+      "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
+      "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+      "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
+      "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
+      "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
+      "Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.",
+      "A selection-order change applies from the next unbound request and never moves a bound thread.",
+    ],
+  },
+  {
+    name: "models",
+    aliases: ["model"],
+    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|context|shadow> ...",
+    summary: "List models and manage custom (manually registered) models.",
+    details: [
+      "List available models from static config with no subcommand (liveModels may add more at runtime).",
+      "add: register a model the provider catalog does not advertise yet.",
+      "  --display-name <name>     Human label (no slashes).",
+      "  --context-window <tokens> e.g. 200000.",
+      "  --modalities text,image   Comma-separated (text|image|audio).",
+      "remove: delete a custom model by UUID or <provider>/<modelId>.",
+      "list-custom: show all custom models.",
+      "Changes apply immediately to a running proxy (catalog sync).",
+    ],
+  },
+  {
+    name: "model",
+    aliases: [],
+    usage: "ocx model <subcommand>",
+    summary: "Alias of ocx models.",
+  },
+  {
+    name: "combo",
+    usage: "ocx combo <list|show|set|remove> ...",
+    summary: "Manage combo failover and round-robin virtual models.",
+    details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
+  },
+  {
+    name: "route",
+    usage: "ocx route combo <list|show|set|remove> ...",
+    summary: "Manage routing features; combo is currently the supported routing resource.",
+  },
+  {
+    name: "agent",
+    usage: "ocx agent <status|injection|effort|subagents|fallback|sidecar> ...",
+    summary: "Manage headless multi-agent, roster, effort, injection, and sidecar settings.",
+  },
+  {
+    name: "observe",
+    usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
+    summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
+  },
+  { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
+  {
+    name: "usage",
+    usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]",
+    summary: "Alias of ocx observe usage.",
+  },
+  { name: "storage", usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
+  { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
+  {
+    name: "access",
+    usage: "ocx access <key|endpoints|models|test> ...",
+    summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
+  },
+  { name: "api-key", usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
+  {
+    name: "export",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (opencode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code) wired to the running proxy.",
+    details: [
+      "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
+      "--out <path> writes the native config there and refuses to replace an existing file without --force.",
+      "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
+      "The destination path is printed for merging by hand — ocx never writes your real client config.",
+    ],
+  },
+  {
+    name: "grok",
+    usage: "ocx grok <status|exclude|include|set|clear|apply> ...",
+    summary: "Manage and apply the Grok Build model fence.",
+  },
+  { name: "integration", usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
+  {
+    name: "system",
+    usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
+    summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
+  },
+  {
+    name: "config",
+    usage: "ocx config <show|get|set|unset|validate|export|import> ...",
+    summary: "Inspect and safely modify validated OpenCodex configuration.",
+    details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
+  },
+  {
+    name: "claude",
+    usage: "ocx claude [claude args...]",
+    summary: "Launch Claude Code wired to the proxy (env injection + gateway model discovery).",
+    details: [
+      "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
+      "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
+      "Routed models appear in the native /model picker with stable claude-opus-4-8-2026MMDD slot aliases (Claude Code >= 2.1.129).",
+      "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
+      "User-exported ANTHROPIC_* variables always take precedence.",
+      "",
+      "Claude Desktop profile:",
+      "  ocx claude desktop [apply]                         Save and apply the four-family profile",
+      "  ocx claude desktop show [--json]                   Show routes, families, and defaults",
+      "  ocx claude desktop move <route> <family> [--default]",
+      "  ocx claude desktop default <family> <route|none>",
+      "  ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
+      "  ocx claude desktop import <path> [--apply]         Validate and import JSON",
+      "Families: opus, fable, sonnet, haiku. New routes start in opus.",
+      "`none` is valid only when that family is empty.",
+      "Legacy apply flags remain supported: --static, --hybrid, --discovery-only.",
+      "",
+      "Claude Code settings: ocx claude config <status|set> ...",
+    ],
+  },
+  {
+    name: "opencode",
+    usage: "ocx opencode [opencode args...]",
+    summary: "Launch opencode wired to the proxy (runtime provider config).",
+    details: [
+      "Ensures the proxy is running, then execs `opencode` with the generated `provider.opencodex`",
+      "block injected through OpenCode's inline runtime layer (`OPENCODE_CONFIG_CONTENT`). Any",
+      "existing inline config in the environment is preserved and only `provider.opencodex` is",
+      "overwritten for this launch.",
+      "Global/project opencode.json may be read to warn about an existing provider.opencodex",
+      "override; on-disk files are never modified.",
+      "Routed models appear in the model picker as opencodex/<provider>/<model>.",
+      "Stop using `ocx opencode` and plain `opencode` behaves exactly as before.",
+    ],
+  },
+  {
+    name: "restart",
+    usage: "ocx restart",
+    summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
+  },
+  {
+    name: "v2",
+    usage: "ocx v2 <status|on|off|mode <v1|default|v2>|threads <n>>",
+    summary: "Toggle the Codex multi_agent_v2 feature (multi-agent surface).",
+    details: [
+      "status                Show flag, multi-agent mode, and thread limit.",
+      "on | off              Enable/disable multi_agent_v2 (catalog resyncs).",
+      "mode <v1|default|v2>  Force all models to one surface, or respect upstream pins.",
+      "threads <n>           Set max_concurrent_threads_per_session (integer >= 1).",
+      "Flips preserve the active thread limit while moving between v1/v2 modes.",
+    ],
+  },
+  {
+    name: "health",
+    usage: "ocx health [--json]",
+    summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
+    details: ["Use --json for structured output: {ok, pid, port}."],
+  },
+  {
+    name: "ready",
+    usage: "ocx ready [--json] [--wait [--timeout <seconds>]]",
+    summary: "Check post-sync readiness. Exits 0 only when ready.",
+    details: [
+      "Exact unauthenticated GET /readyz returns HTTP 200 when ready, or 503 with Retry-After: 1 for pending or failed.",
+      "Its sanitized HTTP identity is {service, version, uptime, pid, port, status}; /healthz is separate liveness, not readiness.",
+      "Default is a single identity-checked /readyz probe; old proxies without /readyz fail closed as unreachable.",
+      "--wait polls until ready or timeout, but exits immediately on terminal failed (default 45s, max 300s).",
+      "--timeout requires --wait and accepts a positive integer (1..300).",
+      "--json emits {ready, status, pid, port}; status is one of ready|pending|failed|unreachable.",
+      "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
+    ],
+  },
+  {
+    name: "lab",
+    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
+    summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
+    details: [
+      "status                Projection availability, schema versions, and row counts.",
+      "verdicts              Paginated derived compatibility verdicts with filters.",
+      "subjects              List subjects; subject <id> returns one typed subject.",
+      "observations          Paginated observation rows from the projection.",
+      "events                Event history; event <id> returns one safe typed event.",
+      "artifacts             Artifact metadata only (no content download).",
+      "catalog               Packaged protocol/live scenario catalog metadata.",
+      "Reads never rebuild the projection, trigger probes, or require the proxy.",
+    ],
+  },
+  {
+    name: "__refresh-version",
+    hidden: true,
+    usage: "ocx __refresh-version [preview|latest]",
+    summary: "Hidden detached helper: refresh the cached latest version.",
+  },
+  {
+    name: "__tray-start",
+    hidden: true,
+    usage: "ocx __tray-start",
+    summary: "Hidden internal: start the tray proxy.",
+  },
+  {
+    name: "__tray-restart",
+    hidden: true,
+    usage: "ocx __tray-restart",
+    summary: "Hidden internal: restart the tray proxy.",
+  },
+  {
+    name: "__startup-health",
+    hidden: true,
+    usage: "ocx __startup-health",
+    summary: "Hidden internal: print startup health JSON.",
+  },
+  {
+    name: "__tray-host",
+    hidden: true,
+    usage: "ocx __tray-host",
+    summary: "Hidden internal: run the Windows tray host.",
+  },
+  {
+    name: "__gui-update-worker",
+    hidden: true,
+    usage: "ocx __gui-update-worker <jobId> [channel] [restart]",
+    summary: "Hidden internal: run the GUI update worker.",
+  },
+];
+
+export function findCommand(name: string): CliCommandEntry | undefined {
+  // Exact-name wins so alias-name entries (setup/eject/remove/model) keep their
+  // own help text; the canonical entry is the fallback for alias lookups.
+  return CLI_COMMANDS.find(entry => entry.name === name)
+    ?? CLI_COMMANDS.find(entry => entry.aliases?.includes(name));
+}
+
+export function commandNames(): string[] {
+  return CLI_COMMANDS.map(entry => entry.name);
+}

package/src/cli/root.ts

@@ -0,0 +1,86 @@
+/**
+ * CLI head: version/help early exits, `ocx ready` pre-parse, and the bounded
+ * Codex-shim auto-restore preflight, in that order (Phase 1 of the CLI
+ * deepening — moved out of src/cli/index.ts).
+ *
+ * `parseCliHead` is pure (no I/O, no process access) so the ordering and the
+ * single-parse contract are unit-testable without a subprocess. `runCli` owns
+ * the exit paths and the shim preflight, then returns the dispatchable head
+ * for the command switch in src/cli/index.ts.
+ */
+import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
+import { parseReadyArgs, type ReadyArgs } from "./ready";
+import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
+
+export interface CliHead {
+  kind: "version" | "help" | "ready" | "command";
+  command: string | undefined;
+  args: string[];
+  /** For kind "help": the subcommand whose usage should print, if any. */
+  helpTarget?: string;
+  /** Present only for `ready`; undefined when the ready args failed to parse. */
+  readyArgs?: ReadyArgs;
+}
+
+export function parseCliHead(argv: string[]): CliHead {
+  const command = argv[0];
+  const args = argv;
+  if (command === "--version" || command === "-v" || command === "version") {
+    return { kind: "version", command, args };
+  }
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    // `ocx help <sub>` carries the subcommand; bare/flag help prints the full usage.
+    return {
+      kind: "help",
+      command,
+      args,
+      ...(command === "help" && args[1] ? { helpTarget: args[1] } : {}),
+    };
+  }
+  if (command !== "help" && hasHelpFlag(args.slice(1))) {
+    // `ocx <cmd> --help|-h|help` prints that command's usage, not the full list.
+    return { kind: "help", command, args, helpTarget: command };
+  }
+  // P1: pre-parse `ocx ready` and reject invalid arguments with exit 64 BEFORE
+  // maybeAutoRestoreCodexShim (or any discovery/probe/filesystem-capable global
+  // preflight) runs. `ready --help` / `help ready` already exited above, so this
+  // only sees ready args without a help flag. Valid args are stashed so the
+  // switch dispatch can call runReady without a second parse.
+  if (command === "ready") {
+    const parsed = parseReadyArgs(args.slice(1));
+    if (!parsed.ok) return { kind: "ready", command, args, readyArgs: undefined };
+    return { kind: "ready", command, args, readyArgs: parsed.args };
+  }
+  return { kind: "command", command, args };
+}
+
+export async function runCli(argv: string[]): Promise<CliHead> {
+  const head = parseCliHead(argv);
+  switch (head.kind) {
+    case "version":
+      printVersion();
+      process.exit(0);
+    case "help": {
+      if (head.helpTarget) printSubcommandUsage(head.helpTarget);
+      else printUsage();
+      process.exit(0);
+    }
+    case "ready": {
+      // Fail-closed impossible-state guard: parseCliHead already ran the
+      // pre-parse before any shim/preflight side effect, so reaching here
+      // without readyArgs means dispatch diverged. Refuse with code 64 and
+      // perform NO I/O (no discovery/probe).
+      if (!head.readyArgs) {
+        console.error("Usage: ocx ready [--json] [--wait [--timeout <seconds>]]");
+        console.error("  --timeout requires --wait; <seconds> must be a positive integer (1..300).");
+        console.error("  Default wait timeout is 45 seconds.");
+        process.exit(64);
+      }
+      maybeAutoRestoreCodexShim(head.command, head.args);
+      return head;
+    }
+    case "command":
+      maybeAutoRestoreCodexShim(head.command, head.args);
+      return head;
+  }
+}

package/src/cli/status.ts

@@ -2,6 +2,7 @@ import { durableBunRuntime } from "../lib/bun-runtime";
 import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "../config";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
 import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
+import { directLocalHttpFetch } from "../server/direct-local-http";
 import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
@@ -110,12 +111,18 @@ export function resolveStatusPid(
   return live ? live.pid : pidFile;
 }
 
+export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "timed out" | "unreachable" {
+  return signal.aborted || (error instanceof Error && error.name === "AbortError")
+    ? "timed out"
+    : "unreachable";
+}
+
 async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
   const url = target.healthUrl;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 800);
   try {
-    const response = await fetch(url, { signal: controller.signal });
+    const response = await directLocalHttpFetch(url, { signal: controller.signal });
     if (!response.ok) {
       const message = `returned HTTP ${response.status}`;
       return { ok: false, url, message, label: `${url} ${message}` };
@@ -130,7 +137,7 @@ async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
     const message = `ok${version}${uptime}`;
     return { ok: true, url, message, label: `${url} ${message}` };
   } catch (error) {
-    const reason = error instanceof Error && error.name === "AbortError" ? "timed out" : "unreachable";
+    const reason = proxyHealthFailureReason(error, controller.signal);
     return { ok: false, url, message: reason, label: `${url} ${reason}` };
   } finally {
     clearTimeout(timer);

package/src/cli/v2.ts

@@ -12,7 +12,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { dirname } from "node:path";
-import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, transitionMultiAgentV2 } from "../codex/features";
+import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
 import { loadConfig, saveConfig } from "../config";
@@ -121,11 +121,46 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     log.log(`agents.max_depth: ${maxDepth ?? "(unset — upstream default 1)"}${v2Active ? " (V1-only — ignored while multi_agent_v2 is enabled)" : ""}`);
     const instructions = getSubagentDeveloperInstructions();
     log.log(`subagent_developer_instructions: ${instructions === null ? "(unset — children inherit)" : instructions === "" ? '"" (clears inherited instructions)' : JSON.stringify(instructions)}`);
+    const modeHint = getMultiAgentModeHintText();
+    log.log(`multi_agent_mode_hint_text: ${modeHint === null ? "(unset — effort-derived policy: ultra=proactive, else explicit)" : JSON.stringify(modeHint)}`);
     if (isEnabled() && hasMaxThreads()) {
       log.log("WARNING: [agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove it from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
     }
     return 0;
   }
+  if (verb === "mode-hint") {
+    const value = args[1];
+    if (value === undefined) {
+      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
+      return 1;
+    }
+    if (value === "--clear") {
+      const result = setMultiAgentModeHintText(null);
+      if (!result.ok) {
+        log.error(`v2 mode-hint: ${result.error}`);
+        return 1;
+      }
+      log.log(result.changed
+        ? "multi_agent_mode_hint_text cleared — effort-derived policy resumes (new sessions)."
+        : "multi_agent_mode_hint_text already unset — nothing to do.");
+      return 0;
+    }
+    // `--clear` is the only reserved token; hints are otherwise arbitrary
+    // nonblank text and may legitimately begin with a hyphen.
+    if (value.trim().length === 0) {
+      log.error("v2 mode-hint: pass the hint text, or --clear to unset it.");
+      return 1;
+    }
+    const result = setMultiAgentModeHintText(value);
+    if (!result.ok) {
+      log.error(`v2 mode-hint: ${result.error}`);
+      return 1;
+    }
+    log.log(result.changed
+      ? `multi_agent_mode_hint_text set (new sessions).`
+      : "multi_agent_mode_hint_text already set — nothing to do.");
+    return 0;
+  }
   if (verb === "threads") {
     const value = Number((args[1] ?? "").trim());
     if (!Number.isInteger(value) || value < 1) {
@@ -170,7 +205,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     return 0;
   }
   if (verb !== "on" && verb !== "off") {
-    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|threads <n>)`);
+    log.error(`v2: unknown verb '${verb}' (expected status|on|off|mode <v1|default|v2>|threads <n>|mode-hint <text|--clear>)`);
     return 1;
   }
 

package/src/codex/account-label.ts

@@ -1,5 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
-import type { CodexAccount } from "../types";
+import type { CodexAccount, OcxConfig } from "../types";
+import type { CodexAuthContext } from "./auth-context";
+import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
 
 export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/;
 
@@ -22,6 +24,17 @@ export function codexAccountLogLabel(account: CodexAccount): string {
     : fallbackCodexAccountLogLabel(account.id);
 }
 
+/** Effective durable label for a resolved Codex Pool account. */
+export function codexAuthContextLogLabel(
+  authCtx: CodexAuthContext,
+  config: Pick<OcxConfig, "codexAccounts">,
+): "main" | `p${string}` | undefined {
+  if (authCtx.kind !== "pool" && authCtx.kind !== "main-pool") return undefined;
+  if (authCtx.accountId === MAIN_CODEX_ACCOUNT_ID) return "main";
+  const account = (config.codexAccounts ?? []).find(candidate => candidate.id === authCtx.accountId);
+  return account ? codexAccountLogLabel(account) as `p${string}` : undefined;
+}
+
 export function withCodexAccountLogLabel(
   account: Omit<CodexAccount, "logLabel"> & Partial<Pick<CodexAccount, "logLabel">>,
   existingAccounts: readonly CodexAccount[],

package/src/codex/account-store.ts

@@ -491,11 +491,22 @@ export async function getValidCodexToken(id: string): Promise<CodexTokenResult>
       throw new TokenRefreshError(reason, `Codex token refresh failed (${reason}); reauthenticate the account.`);
     }
     const data = (await res.json()) as { access_token: string; refresh_token?: string; expires_in: number };
+    // Guard against a missing/non-finite/negative expires_in (malformed upstream
+    // response): a NaN expiry would never compare as expired, and a negative
+    // duration would stamp an already-past expiry — both block refresh semantics.
+    const expiresIn =
+      typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in >= 0
+        ? data.expires_in
+        : 3600;
+    // The computed timestamp itself must stay finite: Number.MAX_VALUE passes
+    // Number.isFinite but overflows to Infinity once multiplied by 1000.
+    const expiresAt = Date.now() + expiresIn * 1000;
+    const safeExpiresAt = Number.isFinite(expiresAt) ? expiresAt : Date.now() + 3600 * 1000;
 
     const updated: CodexAccountCredentials = {
       accessToken: data.access_token,
       refreshToken: data.refresh_token ?? lockedCred.refreshToken,
-      expiresAt: Date.now() + data.expires_in * 1000,
+      expiresAt: safeExpiresAt,
       chatgptAccountId: lockedCred.chatgptAccountId,
     };
     if (!saveCodexAccountCredentialIfGeneration(id, startGeneration, updated)) {

package/src/codex/admission.ts

@@ -33,6 +33,7 @@ import {
   CODEX_PROFILE_PATH,
   DEFAULT_CATALOG_PATH,
   getCodexHome,
+  resolveCodexStateDbPath,
 } from "./paths";
 
 export type CodexAdmission =
@@ -162,7 +163,7 @@ export function admitCodexWrite(deps: AdmissionDeps = {}): CodexAdmission {
   const config = diagnostics.config;
   const opencodexHome = getConfigDir();
   const integrationRecord = join(opencodexHome, "integrations", "codex.json");
-  const historyDb = join(codexHome, "state_5.sqlite");
+  const historyDb = resolveCodexStateDbPath({ codexHome });
 
   const canonicalTargets = {
     codexHome,

package/src/codex/auth-api.ts

@@ -5,7 +5,7 @@ import {
   saveConfigPreservingClaudeCode,
   withConfigMutationLockSync,
 } from "../config";
-import { withCodexAccountLogLabel } from "./account-label";
+import { codexAccountLogLabel, withCodexAccountLogLabel } from "./account-label";
 import {
   getCodexAccountCredential,
   getValidCodexToken,
@@ -239,7 +239,7 @@ function poolAccountDto(
     email: maskEmail(account.email) ?? account.email,
     ...(account.alias !== undefined ? { alias: account.alias } : {}),
     ...(plan !== undefined ? { plan } : {}),
-    ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
+    logLabel: codexAccountLogLabel(account),
     isMain: false,
     paused,
     priority,
@@ -1228,6 +1228,7 @@ export async function listCodexAuthAccountsSnapshot(
     id: MAIN_CODEX_ACCOUNT_ID,
     email: maskEmail(mainInfo.email) ?? "Codex App login",
     plan: mainInfo.plan,
+    logLabel: "main",
     isMain: true,
     paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
     priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),