@iislee/opencodex 2.11.0 → 2.35.0

package/src/cli/index.ts

@@ -1,13 +1,20 @@
 #!/usr/bin/env bun
 import { spawn } from "node:child_process";
-import { currentExternalCodexModelProvider, restoreNativeCodex, shouldInjectApiAuthHeader } from "../codex/inject";
+import { currentExternalCodexModelProvider, restoreNativeCodex, restoreNativeCodexAsync, shouldInjectApiAuthHeader } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
-import { restoreLegacyOpenaiHistory } from "../codex/history-provider";
+import {
+  describeHistoryJobFailure,
+  resolveCodexHistoryJobTarget,
+  runCodexHistoryJob,
+} from "../codex/history-job";
 import { reconcileJournal } from "../codex/journal";
 import {
   codexAutoStartEnabled,
   getConfigDir,
   loadConfig,
+  saveConfig,
+} from "../config";
+import {
   readPid,
   readPidFileValue,
   readRuntimePort,
@@ -15,56 +22,84 @@ import {
   removePidIfValueIs,
   removeRuntimePort,
   removeRuntimePortIfPidIs,
-  saveConfig,
   writePid,
   writeRuntimePort,
-} from "../config";
-import { collectStatus } from "./status";
-import { dispatchInternalCliCommand, type InternalCliCommand } from "./internal-dispatch";
-import { runTrayProxyRestart, runTrayProxyStart } from "./tray-proxy";
+} from "../config/process-state";
+import { collectStatus, unusedProxyWarningLines } from "./status";
+import { takeFlag } from "./runtime-api";
+
+import {
+  discoverStableProxyForRestart,
+  isProxyReplacement,
+  runProxyRestart,
+  runTrayProxyStart,
+  type ProxyRestartLive,
+  type ProxyRestartResult,
+} from "./tray-proxy";
+import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
-import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
+import { dispatchCommand } from "./dispatch";
 import { findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
-import { stopProxy } from "../lib/process-control";
+import { createReadinessGate } from "../server/readiness";
+import { runReady, type ReadyArgs } from "./ready";
+import { runCli } from "./root";
+import { ProxyOwnershipRefusedError, stopProxy } from "../lib/process-control";
 import { loadServiceTokenFromFile } from "../lib/service-secrets";
-import { diagnoseService, isServiceOwnershipError, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "../service";
-import { startupHealthSummary } from "../codex/autostart-health";
+import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "../service";
+import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import { drainAndShutdown, isRecyclingForExit, startServer } from "../server";
-import { injectSystemEnv, revertSystemEnv } from "../server/system-env";
+import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
-import { installShellHook, uninstallShellHook } from "../server/system-env";
 import { startTokenGuardian } from "../oauth/token-guardian";
 import { startHistoryMigrationGuardian } from "../codex/history-migration-guardian";
-import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 import { maybeShowStarPrompt } from "./star-prompt";
 import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
-import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
-import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
-import { removeOwnedConfigState } from "../lib/config-ownership";
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-if (command === "--version" || command === "-v" || command === "version") {
-  printVersion();
-  process.exit(0);
-}
+import {
+  shouldSyncGrokOnStart,
+  syncCodexOnStartIfEnabled,
+} from "../codex/desired-state";
+import {
+  reconcileClientStartupBeforeReady,
+  syncClaudeAgentDefsAtProxyStartup,
+} from "./claude-agent-startup-sync";
+import {
+  grokSyncFailureMessage,
+  reconcileEnsureDesiredIntegrations,
+} from "./ensure-desired-integrations";
 
-if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-  if (command === "help" && args[1]) printSubcommandUsage(args[1]);
-  else printUsage();
-  process.exit(0);
+/**
+ * A failed shell-hook reconcile is not cosmetic: a stale hook keeps sourcing
+ * `claude-env.sh` from every new interactive shell, pointing at a proxy or a CLI that may no
+ * longer exist. `reconcileShellHook` already reports `state: "failed"`, but both call sites
+ * discarded it, so the one outcome the user has to act on was the one they never saw.
+ */
+function reportShellHookFailure(result: { state: "installed" | "absent" | "failed"; reason?: string }): void {
+  if (result.state !== "failed") return;
+  console.warn(`   Claude shell hook not reconciled${result.reason ? `: ${result.reason}` : ""}`);
+  console.warn("   Check ~/.zshrc for the '# opencodex claude-env hook' block.");
 }
 
-if (command !== undefined && command !== "help" && hasHelpFlag(args.slice(1))) {
-  printSubcommandUsage(command);
-  process.exit(0);
-}
 
-maybeAutoRestoreCodexShim(command, args);
+import { removeOwnedConfigState } from "../lib/config-ownership";
+import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { initializeNodeLauncherContext } from "./launcher-context";
+import { createLocalAttestationSecret } from "../lib/local-management-attestation";
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+
+initializeNodeLauncherContext();
+
+// Head: version/help early exits, `ready` pre-parse (exit 64 before any
+// preflight), and the bounded Codex-shim auto-restore preflight live in
+// src/cli/root.ts (Phase 1 of the CLI deepening). runCli exits for
+// version/help and returns the dispatchable head otherwise; the switch below
+// owns command dispatch.
+const head = await runCli(process.argv.slice(2));
+const args = head.args;
+const command = head.command;
 
 function parsePortOption(): number | undefined {
   if (args.length === 1) return undefined;
@@ -95,34 +130,31 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
-/**
- * A Grok fence sync that throws is best-effort by design — it must never block startup.
- * Reporting nothing, however, is what lets a STALE fence survive: `~/.grok/config.toml`
- * keeps naming whatever port the last successful sync wrote, and once that listener is
- * gone every grok turn retries against a refused connection while our own log stays
- * silent (2026-07-27 field report: 8 entries pinned to a dead 127.0.0.1:4179).
- * So say what failed and name the single command that repairs it.
- */
-function grokSyncFailureMessage(err: unknown): string {
-  const detail = err instanceof Error ? err.message : String(err);
-  return `Grok Build config sync failed: ${detail}. `
-    + "~/.grok/config.toml may still point at a previous proxy port — "
-    + "run 'ocx ensure' (or apply from the dashboard's Grok page) to repoint it.";
-}
-
 /** Argv for detached `start`, optionally hard-pinning the listen port. */
 function startArgv(port?: number): string[] {
-  const args = [process.argv[1], "start"];
+  const args = ["start"];
   if (typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535) {
     args.push("--port", String(Math.trunc(port)));
   }
-  return args;
+  return selfLaunchArgv(args);
 }
 
 async function chooseListenPort(requestedPort?: number): Promise<number> {
   const config = loadConfig();
   const preferred = requestedPort ?? config.port ?? 10100;
   const hardPin = requestedPort !== undefined && requestedPort > 0;
+  const reservedLoopbackPort = config.unauthenticatedLoopbackListener?.enabled
+    ? config.unauthenticatedLoopbackListener.port
+    : undefined;
+  // Before the reclaim path, not after (#1102). Asking for the port the loopback listener is
+  // configured to bind is a configuration mistake, and reclaim would spend up to 60 seconds
+  // waiting for a socket to free before reporting "port is busy" — the wrong diagnosis for a
+  // collision the config can state outright.
+  if (reservedLoopbackPort !== undefined && preferred === reservedLoopbackPort) {
+    throw new Error(
+      `Port ${preferred} is reserved for unauthenticatedLoopbackListener; choose a different proxy port.`,
+    );
+  }
   // Soft start: brief prefer-retry then ephemeral hop.
   // Explicit `--port` (service wrappers / update restart): wait for the pinned port
   // to free without killing any listener (healthy ocx / foreign). Never hop.
@@ -146,6 +178,11 @@ async function chooseListenPort(requestedPort?: number): Promise<number> {
       preferRetryMs: hardPin ? 5_000 : 750,
       preferRetryIntervalMs: 50,
       allowEphemeralFallback: !hardPin,
+      // Never hand the public listener the port the loopback listener is configured to
+      // bind (#1102). Without this, `--port <loopback port>` binds the public listener
+      // first and the loopback bind then fails, rolling back a startup that was only
+      // ever a config collision.
+      ...(reservedLoopbackPort !== undefined ? { reservedPort: reservedLoopbackPort } : {}),
     });
     if (preferred > 0 && selected !== preferred) {
       console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
@@ -165,22 +202,49 @@ async function chooseListenPort(requestedPort?: number): Promise<number> {
   }
 }
 
+async function findProxyOwnerBeforeJournalRecovery(
+  options: { probeConfiguredPort?: boolean } = {},
+): Promise<{ live: LiveProxy | null; pidSnapshot: number | null }> {
+  const pidSnapshot = readPidFileValue();
+  const hasRuntimeOwner = readRuntimePort() !== null;
+  const shouldProbe = pidSnapshot !== null || hasRuntimeOwner || options.probeConfiguredPort === true;
+  const live = shouldProbe ? await findLiveProxy() : null;
+  if (live) return { live, pidSnapshot };
+
+  // The probe established that the snapshotted owner is stale. Compare before
+  // deleting so a concurrent start that rewrote the PID file keeps its state.
+  removePidIfValueIs(pidSnapshot);
+  if (!currentExternalCodexModelProvider()) reconcileJournal();
+  return { live: null, pidSnapshot };
+}
+
 async function handleStart(options: { block?: boolean } = {}) {
   // Native (WinSW) service mode has no batch wrapper to read the service token file
   // into the environment, so the app loads it here before the server binds. The server
   // auth path reads OPENCODEX_API_AUTH_TOKEN from the environment.
   const serviceToken = loadServiceTokenFromFile(process.env);
   if (serviceToken) process.env.OPENCODEX_API_AUTH_TOKEN = serviceToken;
+  // The service wrapper (and WinSW via OCX_API_TOKEN_FILE) can still export a colliding
+  // token that install now refuses to write. Refuse it here too, before bind, so an
+  // already-broken file cannot fence /api/* closed at boot (#2696).
+  const present = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (present) assertNotAdminToken(present);
   const requestedPort = parsePortOption();
-  if (!currentExternalCodexModelProvider()) reconcileJournal();
-  const existingPid = readPid();
-  if (existingPid) {
-    const live = await findLiveProxy();
-    if (live) {
-      console.error(`⚠️  Proxy already running (PID ${live.pid ?? existingPid}, port ${live.port}). Use 'ocx stop' first.`);
-      process.exit(1);
-    }
-    removePid(existingPid);
+  const owner = await findProxyOwnerBeforeJournalRecovery();
+  if (owner.live) {
+    // Service-wrapper context (opencodex-service.cmd `:loop`): a healthy proxy from
+    // ANY source means the requested port is already served. Exit 0 so the wrapper's
+    // `if %ERRORLEVEL% NEQ 0` retry loop terminates instead of respawning every 5s
+    // against a listener it can never claim (observed as an endless
+    // "Proxy already running" service.log loop).
+    // Only the exact "1" sentinel takes this path — the same check syncCleanup
+    // uses — so an env value like "0" or "false" cannot bypass the conflict error.
+    if (process.env.OCX_SERVICE === "1") {
+      console.log(`Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}); service wrapper staying out of the way.`);
+      process.exit(0);
+    }
+    console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+    process.exit(1);
   }
 
   // Interactive-only update prompt. Must run BEFORE we bind a port / write a
@@ -192,10 +256,16 @@ async function handleStart(options: { block?: boolean } = {}) {
   // between the probe and Bun.serve. Soft starts may re-pick; hard-pinned `--port` retries
   // the same port only (never hop — that was the remaining PR #152 gap).
   let port = await chooseListenPort(requestedPort);
+  // One private readiness gate for this startServer invocation, captured by the
+  // listener's closure. handleStart owns it and transitions it after the
+  // post-startup sync settles. A second startServer in the same process would
+  // get its own gate and could never reset/mutate this one.
+  const readinessGate = createReadinessGate();
   let server: ReturnType<typeof startServer>;
+  const localAttestationSecret = createLocalAttestationSecret();
   for (let attempt = 0; ; attempt++) {
     try {
-      server = startServer(port);
+      server = startServer(port, { localAttestationSecret, readinessGate });
       // Prewarm the live provider model cache as soon as the port is bound so the
       // first GUI /v1/models (and syncModelsToCodex below) share one discovery flight
       // instead of racing duplicate upstream /models fetches.
@@ -223,7 +293,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   writePid(process.pid);
 
   const config = loadConfig();
-  writeRuntimePort({ pid: process.pid, port, hostname: config.hostname });
+  writeRuntimePort({ pid: process.pid, port, hostname: config.hostname, attestationSecret: localAttestationSecret });
   // No pre-emptive snapshot here. `injectCodexConfig` journals the exact bytes it
   // is about to transform; snapshotting earlier only captured a baseline that could
   // already be stale by the time injection ran (#477).
@@ -251,7 +321,8 @@ async function handleStart(options: { block?: boolean } = {}) {
     }
     removePid(process.pid);
     removeRuntimePort(process.pid);
-    if (!recycling && !process.env.OCX_SERVICE && !currentExternalCodexModelProvider()) {
+    const preserveRouting = process.env.OCX_SERVICE === "1";
+    if (!recycling && !preserveRouting && !currentExternalCodexModelProvider()) {
       try {
         const restored = restoreNativeCodex();
         if (!restored.success) {
@@ -267,7 +338,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     // Grok fence is shared state we must not remove — that service keeps running and would be
     // left pointing nowhere. This guard also covers signal-driven exits, which is the path that
     // would otherwise bypass handleStop's gate entirely.
-    if (!recycling && !process.env.OCX_SERVICE && serviceEnvironmentOwnedHere()) {
+    if (!recycling && !preserveRouting && serviceEnvironmentOwnedHere()) {
       try { stripGrokConfig(); } catch { /* best-effort restore */ }
     }
     return cleanupSucceeded;
@@ -310,12 +381,32 @@ async function handleStart(options: { block?: boolean } = {}) {
 
   // System-wide env injection AFTER signal handlers are registered (crash safety:
   // syncCleanup reverts even if injection itself or subsequent startup steps fail).
-  await injectSystemEnv(port, config).catch(() => {});
-  // Auto-install .zshrc hook (idempotent — skips if already present).
-  installShellHook();
-
+  const systemEnv = await injectSystemEnv(port, config).catch(() => ({ injected: false }));
+  // The hook is useful only for an installed Claude Code CLI. Reconcile instead of
+  // appending unconditionally so stale OpenCodex-owned hooks are removed as well.
+  reportShellHookFailure(reconcileShellHook(systemEnv.injected));
   await maybeShowStarPrompt(); // once-only Yes/No GitHub-star prompt on first interactive start
-  await syncModelsToCodex(port).catch(() => {});
+  // Codex sync owns the ready/failed verdict, but its successful transition is
+  // deferred until the best-effort Claude roster reconciliation settles. This
+  // keeps /readyz closed across both startup writes without making an optional
+  // Claude integration failure prevent the proxy from starting.
+  const startupSync = await reconcileClientStartupBeforeReady(
+    readinessGate,
+    gate => syncCodexOnStartIfEnabled(port, config, undefined, gate),
+    () => systemEnv.injected
+      ? Promise.resolve(null)
+      : syncClaudeAgentDefsAtProxyStartup(config, port),
+  );
+  if (!startupSync.ran) console.log("   Codex integration OFF; startup left Codex native.");
+  // #1046: one warning per startup, after BOTH writes. The server's cache
+  // invalidation happens first and the catalog sync second, so the mtime is only
+  // final here — and neither write site warns on its own, or a boot that hits
+  // both would warn twice.
+  const { consumeStartupCacheInvalidationWrite } = await import("../server");
+  if (consumeStartupCacheInvalidationWrite() || startupSync.catalogWritten || startupSync.cacheSynced) {
+    const { warnIfStaleCodexAppServersAfterStartupWrite } = await import("../codex/app-server-processes");
+    warnIfStaleCodexAppServersAfterStartupWrite({ log: console });
+  }
   if (!currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
     historyGuardian = startHistoryMigrationGuardian();
   }
@@ -335,7 +426,10 @@ async function handleStart(options: { block?: boolean } = {}) {
   // absent or the bind is non-loopback; removed again by stop/eject/uninstall/shutdown.
   // Deliberately a SIBLING of the Desktop-3P block above: nesting it there meant a catalog
   // failure skipped the fence entirely, even though syncGrokConfig handles that case itself.
-  try {
+  //
+  // Gated on the persisted switch: without this, turning Grok off lasted exactly
+  // one restart, because the toggle removed the fence and start wrote it back.
+  if (shouldSyncGrokOnStart(config)) try {
     const { syncGrokConfig } = await import("../grok/sync");
     const r = await syncGrokConfig(port, config, config.hostname ? { hostname: config.hostname } : {});
     if (r.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
@@ -354,30 +448,46 @@ async function handleStart(options: { block?: boolean } = {}) {
   }
 }
 
-async function handleEnsure() {
-  if (!currentExternalCodexModelProvider()) reconcileJournal();
+function detachedStartEnvironment(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  // Only a real service wrapper may claim supervision. A detached ensure/tray child
+  // is an ordinary owner: while live it maintains routing, and on exit it restores it.
+  delete env.OCX_SERVICE;
+  return withProcessRuntimeProvenance(env);
+}
+
+async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Promise<boolean> {
+  const owner = await findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true });
   const config = loadConfig();
   if (!codexAutoStartEnabled(config)) {
     console.log("Codex autostart is disabled.");
-    return;
+    return false;
   }
-  const live = await findLiveProxy();
-    if (live) {
-      await syncModelsToCodex(live.port).catch(e => {
+  const live = owner.live;
+  if (live) {
+    if (options.existingIsSuccess === false) {
+      console.error("Proxy appeared while restart was confirming absence; no start was attempted.");
+      return false;
+    }
+      const synced = await syncModelsToCodex(live.port).catch(e => {
         console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
       });
+      if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
       // Ensure env file exists for already-running proxy (may have been deleted or pre-dates this feature).
-      await injectSystemEnv(live.port, config).catch(() => {});
+      const systemEnv = await injectSystemEnv(live.port, config).catch(() => ({ injected: false }));
+      reportShellHookFailure(reconcileShellHook(systemEnv.injected));
+      if (!systemEnv.injected) await syncClaudeAgentDefsAtProxyStartup(config, live.port);
       // Refresh the Grok Build fence too (same contract as start). live.hostname is the
       // hostname the running proxy actually bound — config.hostname may have drifted.
-      try {
-        const { syncGrokConfig } = await import("../grok/sync");
-        const g = await syncGrokConfig(live.port, config, live.hostname ? { hostname: live.hostname } : {});
-        if (g.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
-        else if (!g.ok) console.error(`⚠️  ${g.message}`);
-      } catch (err) { console.error(`⚠️  ${grokSyncFailureMessage(err)}`); }
+      // The reconciler re-reads immediately before each client-file mutation; only
+      // the live proxy's observed bind host is safe to carry across this boundary.
+      await reconcileEnsureDesiredIntegrations(
+        live.port,
+        { kind: "live", hostname: live.hostname },
+      );
       console.log(`✅ Proxy running on port ${live.port}`);
-      return;
+      return true;
     }
 
   const pinPort = config.port ?? 10100;
@@ -385,36 +495,42 @@ async function handleEnsure() {
     detached: true,
     stdio: "ignore",
     windowsHide: true,
-    env: { ...process.env, OCX_SERVICE: "1" },
+    env: detachedStartEnvironment(),
   });
   child.unref();
 
   const port = (await waitForProxy())?.port;
   if (!port) {
     console.error("❌ Proxy did not become healthy after starting.");
-    process.exit(1);
-  }
-  // Deterministic fence guarantee: the spawned child injects late in its own startup, but
-  // this parent returns as soon as /healthz responds — inject here too (idempotent block
-  // replace) so `ocx ensure` never returns without the Grok fence in place.
-  try {
-    const { syncGrokConfig } = await import("../grok/sync");
-    const g = await syncGrokConfig(port, config, config.hostname ? { hostname: config.hostname } : {});
-    if (g.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
-    else if (!g.ok) console.error(`⚠️  ${g.message}`);
-  } catch (err) { console.error(`⚠️  ${grokSyncFailureMessage(err)}`); }
+    process.exitCode = 1;
+    return false;
+  }
+  // Deterministic fence guarantee when the durable switch is ON: the spawned child
+  // injects late in its own startup, but this parent returns as soon as /healthz
+  // responds — align here too so `ocx ensure` never returns with a stale ON/OFF mismatch.
+  // Persisted state is loaded inside each mutation after waitForProxy, so a
+  // toggle while the child starts wins over the pre-spawn snapshot.
+  await reconcileEnsureDesiredIntegrations(port, { kind: "spawned" });
   // Always sync the LIVE port: after a fallback-port start, config.port still names the
   // busy preferred port — syncing that would point Codex at a dead listener.
-  await syncModelsToCodex(port).catch(e => {
+  const synced = await syncModelsToCodex(port).catch(e => {
     console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
   });
+  if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
+  // The child opens /healthz before its best-effort roster reconcile. Await the same idempotent
+  // operation in the parent so `ocx ensure` cannot report success while stale ocx-*.md files are
+  // still observable. Always use the live port, including fallback-port starts.
+  await syncClaudeAgentDefsAtProxyStartup(config, port);
   console.log(`✅ Proxy running on port ${port}`);
+  return true;
 }
 
 /** Fixed tray action: start the proxy without depending on codexAutoStart. */
-async function handleTrayProxyStart(): Promise<void> {
+async function handleTrayProxyStart(existingIsSuccess = true): Promise<boolean> {
   const ok = await runTrayProxyStart({
     findLive: findLiveProxy,
+    existingIsSuccess,
     diagnoseService: () => {
       const service = diagnoseService();
       return { installed: service.installed, startable: serviceStartableFromTray(service), summary: service.summary };
@@ -427,29 +543,117 @@ async function handleTrayProxyStart(): Promise<void> {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: { ...process.env, OCX_SERVICE: "1" },
+        env: detachedStartEnvironment(),
       });
       child.unref();
     },
-    waitForProxy,
+    // serviceCommand("start") already spends up to 20s confirming the supervised
+    // child. Slow Windows hosts can still be publishing native-main state after that
+    // first window, so keep one shared follow-up budget instead of returning a false
+    // failure while Task Scheduler is still starting the approved child.
+    waitForProxy: () => waitForProxy(40_000),
     info: message => console.log(message),
     error: message => console.error(message),
   });
-  if (!ok) process.exitCode = 1;
+  // serviceCommand("start") can set exitCode=1 after its own 20s probe, while
+  // the coordinator's bounded follow-up observes the same service become live.
+  // The final observed state, not the earlier probe, owns this command result.
+  process.exitCode = ok ? 0 : 1;
+  return ok;
 }
 
-async function handleTrayProxyRestart(): Promise<void> {
-  const ok = await runTrayProxyRestart({
-    stop: async () => {
-      await handleStop();
-      return !process.exitCode || process.exitCode === 0;
-    },
-    start: async () => {
-      await handleTrayProxyStart();
-      return !process.exitCode || process.exitCode === 0;
-    },
+const PROXY_RESTART_OBSERVE_MS = MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIMEOUT_MS + 15_000;
+
+async function waitForProxyReplacement(
+  previous: ProxyRestartLive,
+  deadlineAt: number,
+): Promise<ProxyRestartLive | null> {
+  while (Date.now() < deadlineAt) {
+    const live = await findLiveProxy({ deadlineAt });
+    if (Date.now() >= deadlineAt) return null;
+    // Modern /healthz publishes a PID. Require a different, identity-verified process;
+    // merely seeing the old port online again is not proof that restart completed.
+    if (isProxyReplacement(previous, live)) {
+      return live;
+    }
+    const remainingMs = deadlineAt - Date.now();
+    if (remainingMs > 0) await Bun.sleep(Math.min(250, remainingMs));
+  }
+  return null;
+}
+
+function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: false }>): void {
+  if (result.phase === "identity") {
+    console.error("❌ Refusing to restart because the running proxy identity could not be attested.");
+  } else if (result.phase === "request") {
+    const code = result.error instanceof Error ? result.error.message : "";
+    if (code === "restart_capability_unsupported") {
+      console.error("❌ The running proxy predates process-bound restart support; no unsafe fallback was attempted.");
+      console.error("   After confirming this home owns the proxy, run `ocx stop` and then `ocx start` once.");
+    } else {
+      console.error("❌ Proxy restart request could not be confirmed; no fallback stop/start was attempted.");
+    }
+  } else if (result.phase === "replacement") {
+    console.error("❌ Proxy restart was accepted, but no identity-verified replacement became healthy in time.");
+  } else {
+    console.error("❌ Proxy was not running and the fallback start did not become healthy.");
+  }
+}
+
+async function handleProxyRestart(
+  startWhenStopped: () => Promise<boolean | "skipped">,
+): Promise<boolean> {
+  const deadlineAt = Date.now() + PROXY_RESTART_OBSERVE_MS;
+  const result = await runProxyRestart({
+    findLive: () => discoverStableProxyForRestart({
+      findLive: () => findLiveProxy({ deadlineAt, attempts: 2 }),
+      expired: () => Date.now() >= deadlineAt,
+    }),
+    startWhenStopped,
+    requestInPlaceRestart: previous => requestBoundSystemRestart(previous, deadlineAt),
+    waitForReplacement: previous => waitForProxyReplacement(previous, deadlineAt),
   });
-  if (!ok) process.exitCode = 1;
+  if (!result.ok) reportRestartFailure(result);
+  process.exitCode = result.ok ? 0 : 1;
+  return result.ok;
+}
+
+async function handleTrayProxyRestart(): Promise<void> {
+  await handleProxyRestart(() => handleTrayProxyStart(false));
+}
+
+async function handleRestartStartWhenStopped(): Promise<boolean | "skipped"> {
+  if (!codexAutoStartEnabled(loadConfig())) {
+    console.log("Codex autostart is disabled; no proxy was started.");
+    return "skipped";
+  }
+  return handleEnsure({ existingIsSuccess: false });
+}
+
+async function restoreSharedClientStateAfterStop(): Promise<boolean> {
+  let restored = true;
+  try {
+    const result = await restoreNativeCodexAsync();
+    if (result.success) console.log(`↩️  ${result.message}`);
+    else {
+      restored = false;
+      console.error(`⚠️  ${result.message}`);
+    }
+  } catch (error) {
+    restored = false;
+    console.error(`⚠️  Native Codex restore failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // A refused or thrown Grok strip is actionable because it would point Grok at a dead proxy.
+  try {
+    const grok = stripGrokConfig();
+    if (grok.changed) console.log(`↩️  ${grok.message}`);
+    else if (!grok.ok) { restored = false; console.error(`⚠️  ${grok.message}`); }
+  } catch (error) {
+    restored = false;
+    console.error(`⚠️  Grok config restore failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return restored;
 }
 
 async function handleStop() {
@@ -493,6 +697,10 @@ async function handleStop() {
       // exact teardown the refusal exists to prevent.
       const detail = err instanceof Error ? err.message : String(err);
       if (detail) console.error(`   ${detail}`);
+      if (err instanceof ProxyOwnershipRefusedError) {
+        ownershipBlocked = true;
+        console.error("   Skipping shared teardown (native Codex restore, Grok config): the foreign proxy is still running.");
+      }
     }
   } else {
     // Snapshot the stale on-disk state BEFORE the async probe: a concurrent `ocx start`
@@ -511,6 +719,10 @@ async function handleStop() {
         console.error(`❌ Failed to stop proxy (PID ${live.pid}).`);
         const detail = err instanceof Error ? err.message : String(err);
         if (detail) console.error(`   ${detail}`);
+        if (err instanceof ProxyOwnershipRefusedError) {
+          ownershipBlocked = true;
+          console.error("   Skipping shared teardown (native Codex restore, Grok config): the foreign proxy is still running.");
+        }
       }
     } else if (!stoppedService) {
       console.log("No running proxy found.");
@@ -523,26 +735,11 @@ async function handleStop() {
       removeRuntimePortIfPidIs(staleRuntimePid);
     }
   }
-  if (!ownershipBlocked) {
-    const r = restoreNativeCodex();
-    if (r.success) console.log(`↩️  ${r.message}`);
-    else {
-      stopFailed = true;
-      console.error(`⚠️  ${r.message}`);
-    }
-  }
-  // revertSystemEnv is NOT gated: it carries its own ownership check and concerns launchctl
-  // user env, not CODEX_HOME. Safety net for when the daemon's syncCleanup didn't run (SIGKILL).
+  // Environment ownership is independent from service ownership. Always roll back
+  // current-home variables; the helper refuses foreign markers on its own.
   try { revertSystemEnv(); } catch { /* best-effort */ }
   if (!ownershipBlocked) {
-    // Same safety net for the Grok Build managed block (marker-owned, idempotent).
-    try {
-      const g = stripGrokConfig();
-      if (g.changed) console.log(`↩️  ${g.message}`);
-      // A refused strip (e.g. orphaned marker) leaves the fence pointing at a dead proxy —
-      // reporting success there hides a broken end state.
-      else if (!g.ok) { stopFailed = true; console.error(`⚠️  ${g.message}`); }
-    } catch { /* best-effort */ }
+    if (!await restoreSharedClientStateAfterStop()) stopFailed = true;
   }
   // Set the code rather than exiting inline: `restart` and the tray coordinator call this
   // function and need it to RETURN so they can decide what to do next.
@@ -586,8 +783,8 @@ async function handleUninstall() {
     });
   }
 
-  await runStep("native Codex restored", () => {
-    const r = restoreNativeCodex();
+  await runStep("native Codex restored", async () => {
+    const r = await restoreNativeCodexAsync();
     if (!r.success) throw new Error(r.message);
   });
 
@@ -634,13 +831,17 @@ async function handleUninstall() {
     console.error(`\nUninstall finished with ${failures.length} failed step(s): ${failures.join(", ")}`);
     process.exit(1);
   }
-  console.log("\n✅ opencodex local state removed. Remove the package with: npm uninstall -g @iislee/opencodex");
+  console.log("\n✅ opencodex local state removed. Remove the package with: npm uninstall -g @bitkyc08/opencodex");
 }
 
 async function handleStatus() {
   const statusArgs = args.slice(1);
-  const wantsJson = statusArgs.length === 1 && statusArgs[0] === "--json";
-  if (statusArgs.length > 1 || (statusArgs.length === 1 && !wantsJson)) {
+  // Order-independent: the previous form only honoured `--json` as the LONE argument, so
+  // `ocx status --json --anything` silently printed human output to a caller that asked
+  // for JSON. Take the flag out of argv, then reject whatever is left over -- which keeps
+  // the strict unknown-argument behaviour rather than trading one defect for another.
+  const wantsJson = takeFlag(statusArgs, "--json");
+  if (statusArgs.length > 0) {
     console.error("Usage: ocx status [--json]");
     process.exit(1);
   }
@@ -657,9 +858,28 @@ async function handleStatus() {
     console.log(`❌ Proxy: ${status.proxyLabel}`);
   }
   console.log(`   Health: ${status.healthLabel}`);
+  // Printed here, not only in --json: a stale ocx on PATH is exactly the situation where
+  // the operator is reading human output and wondering why the CLI disagrees with the
+  // dashboard. Adding the JSON field alone would satisfy a test and help nobody (#2701).
+  if (status.json.versionSkew.warning) {
+    console.log(`   ⚠️  ${status.json.versionSkew.warning}`);
+  }
+  for (const line of unusedProxyWarningLines({
+    proxyUp: Boolean(status.json.proxy.pid || status.json.proxy.health.ok),
+    routingKind: status.json.startup.routingKind,
+  })) {
+    console.log(`   ${line}`);
+  }
   if (!(status.json.proxy.pid || status.json.proxy.health.ok)) {
     console.log("   ↳ Not running — Codex/Claude requests will fail with connection errors.");
-    console.log("     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
+    // The service summary a few lines below already tells a registered-but-not-serving
+    // user to repair. Printing "install the persistent service" unconditionally
+    // contradicted it in the same report, and install re-registers: UAC on Windows and a
+    // possible WinSW-to-scheduler switch for someone who already has a service.
+    const installed = status.json.startup.serviceInstalled && !status.json.startup.serviceConflict;
+    console.log(installed
+      ? "     Restart with 'ocx start', or refresh the installed service: 'ocx service repair'."
+      : "     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
   }
   console.log(`   Dashboard: ${status.json.dashboard.url}`);
   console.log(`   Config: ${status.json.paths.config}`);
@@ -669,6 +889,7 @@ async function handleStatus() {
   console.log(`   Default provider: ${status.json.defaultProvider}`);
   console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}`);
   console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}`);
+  console.log(`   ${formatStartupRoutingDetail(status.json.startup)}`);
   console.log(`   Service: ${status.json.service.summary}`);
   console.log(`   ${status.json.codexShim.summary}`);
   console.log(`   Codex runtime: ${status.json.codexRuntime.path}`);
@@ -707,407 +928,75 @@ async function handleStatus() {
   }
 }
 
-function handleRecoverHistory() {
+async function handleRecoverHistory() {
   if (args[1] !== "--legacy-openai") {
-    console.error("Usage: ocx recover-history --legacy-openai");
-    console.error("Only use this if an older syncResumeHistory build already remapped OpenAI Codex App history to opencodex before backup support existed.");
+    console.error("Usage: ocx recover-history --legacy-openai --yes");
+    console.error("This force-relabels every user-message opencodex row to OpenAI, including legitimate dedicated-provider history. Back up first and use it only for pre-backup legacy recovery.");
+    process.exit(1);
+  }
+  console.error("WARNING: this force-relabels every user-message opencodex row to OpenAI, normalizes exec to cli, and includes legitimate dedicated-provider history.");
+  if (args.length !== 3 || args[2] !== "--yes") {
+    console.error("Re-run with explicit confirmation: ocx recover-history --legacy-openai --yes");
     process.exit(1);
   }
-  const r = restoreLegacyOpenaiHistory();
+  // Manifest-independent legacy ejection, serialized like every other history
+  // mutation. It is a separate operation from generic restore precisely because
+  // it must not read, consume or replace the backup manifest.
+  const outcome = await runCodexHistoryJob({
+    ...resolveCodexHistoryJobTarget(),
+    operation: "recover-legacy-openai",
+  });
+  const r = outcome.kind === "converged"
+    ? { rows: outcome.rows, files: outcome.files, failed: undefined }
+    : { rows: 0, files: 0, failed: true as const };
   if (r.failed) {
     console.error(
-      "⚠️  Recovery SKIPPED: the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command.",
+      `⚠️  Recovery SKIPPED: ${describeHistoryJobFailure(outcome, "recover-legacy")}`,
     );
     process.exit(1);
   }
   console.log(`Recovered ${r.rows} legacy thread(s) to openai (${r.files} rollout file(s) updated).`);
 }
 
-switch (command) {
-  case "init":
-  case "setup": {
-    const { runInit } = await import("./init");
-    await runInit();
-    break;
-  }
-  case "start":
-    await handleStart();
-    break;
-  case "stop": {
-    // Downtime warning lives HERE, not in handleStop: `restart`/tray-restart callers
-    // re-start the proxy immediately, so warning there would contradict the next line.
-    if (await handleStop()) {
-      console.log("⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').");
-    }
-    break;
-  }
-  case "restore":
-  case "eject": {
-    if (args[1] === "back") {
-      // Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
-      // lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
-      // this only re-runs the same inject (config + catalog + history) `ocx start` does.
-      const live = await findLiveProxy();
-      if (!live) {
-        console.error("No running proxy found. Run 'ocx start' — it injects opencodex automatically.");
-        process.exit(1);
-      }
-      const synced = await syncModelsToCodex(live.port);
-      if (!synced.ok) {
-        process.exitCode = 1;
-        console.error("Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.");
-        break;
-      }
-      const target = collectOrcaCodexHomeDiagnostic();
-      console.log(`Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`);
-      break;
-    }
-    let r: { success: boolean; message: string };
-    try {
-      r = restoreNativeCodex();
-    } catch (err) {
-      r = { success: false, message: err instanceof Error ? err.message : String(err) };
-    }
-    if (r.success) console.log(`✅ ${r.message}`);
-    else {
-      console.error(`⚠️  ${r.message}`);
-      process.exitCode = 1;
-    }
-    try {
-      const g = stripGrokConfig();
-      if (g.changed) console.log(`✅ ${g.message}`);
-      else if (!g.ok) {
-        console.error(`⚠️  ${g.message}`);
-        process.exitCode = 1;
-      }
-    } catch { /* best-effort */ }
-    if (r.success) {
-      console.log("Plain `codex` now runs natively (no proxy). Switch back with: ocx restore back");
-    } else {
-      console.error("Plain `codex` was not fully restored. Inspect $CODEX_HOME/config.toml before using native Codex.");
-    }
-    break;
-  }
-  case "recover-history":
-    handleRecoverHistory();
-    break;
-  case "uninstall":
-  case "remove":
-    await handleUninstall();
-    break;
-  case "status":
-    await handleStatus();
-    break;
-  case "doctor": {
-    const { runDoctor } = await import("./doctor");
-    await runDoctor(args.slice(1));
-    break;
-  }
-  case "debug": {
-    const { handleDebugCommand } = await import("./debug");
-    await handleDebugCommand(args.slice(1));
-    break;
-  }
-  case "ensure":
-    await handleEnsure();
-    break;
-  case "login": {
-    const { handleLogin } = await import("../oauth/login-cli");
-    await handleLogin(args[1]);
-    break;
-  }
-  case "logout": {
-    const { removeCredential } = await import("../oauth/store");
-    const name = (args[1] ?? "").trim().toLowerCase();
-    await removeCredential(name);
-    console.log(`Logged out of ${name || "(none)"}.`);
-    break;
-  }
-  case "sync": {
-    const restartCodex = args.slice(1).includes("--restart-codex");
-    const synced = await syncModelsToCodex((await findLiveProxy())?.port);
-    if (!synced.ok) {
-      process.exitCode = 1;
-      console.error("Codex sync did not complete. Fix the reported Codex config issue and retry.");
-    }
-    // Only warn/restart when a catalog or models_cache write actually happened. This is
-    // deliberately not an `else`: refreshCodexModelCatalog runs before injectCodexConfig,
-    // so a sync can fail (`ok: false`) after the catalog was already rewritten — which is
-    // exactly when a long-lived app-server is holding the stale list.
-    if (synced.catalogWritten || synced.cacheSynced) {
-      const { afterCatalogWriteHandleAppServers } = await import("../codex/app-server-processes");
-      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
-    }
-    break;
-  }
-  case "v2": {
-    const { cmdV2 } = await import("./v2");
-    process.exitCode = await cmdV2(args.slice(1), {}, async () => (await findLiveProxy())?.port);
-    break;
-  }
-  case "sync-cache": {
-    const restartCodex = args.slice(1).includes("--restart-codex");
-    const { invalidateCodexModelsCache } = await import("../codex/catalog");
-    // Only warn/restart when models_cache was actually rewritten from a readable catalog.
-    if (invalidateCodexModelsCache()) {
-      const { afterCatalogWriteHandleAppServers } = await import("../codex/app-server-processes");
-      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
-    }
-    break;
-  }
-  case "gui": {
-    const cfg = await import("../config");
-    const config = cfg.loadConfig();
-    // Identity-checked liveness (not the pid file + a fixed sleep): finds a fallback-port
-    // proxy and waits until the spawned one actually answers before opening the browser.
-    let live = await findLiveProxy();
-    if (!live) {
-      console.log("Proxy not running. Starting...");
-      const child = spawn(process.execPath, startArgv((config.port ?? 10100) > 0 ? (config.port ?? 10100) : undefined), {
-        detached: true,
-        stdio: "ignore",
-        windowsHide: true,
-        env: process.env,
-      });
-      child.unref();
-      live = await waitForProxy();
-      if (!live) {
-        console.error("❌ Proxy did not become healthy after starting. Not opening the GUI.");
-        process.exit(1);
-      }
-    }
-    // Open the host the proxy actually binds — `localhost` only answers for
-    // loopback/wildcard binds, not a concrete LAN/IPv6 hostname.
-    const guiHost = probeHostname(live?.hostname ?? config.hostname);
-    const guiUrl = `http://${guiHost === "127.0.0.1" ? "localhost" : guiHost}:${live?.port ?? config.port}`;
-    console.log(`Opening ${guiUrl}`);
-    const { openUrl } = await import("../lib/open-url");
-    openUrl(guiUrl);
-    break;
-  }
-  case "service":
-    await serviceCommand(...args.slice(1));
-    break;
-  case "tray": {
-    const { windowsTrayCommand } = await import("../tray/windows");
-    await windowsTrayCommand(args.slice(1));
-    break;
-  }
-  case "codex-shim": {
-    const { codexShimStatus, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
-    switch (args[1]) {
-      case "install": {
-        const r = installCodexShim();
-        console.log(r.installed ? `✅ ${r.message}` : `⚠️  ${r.message}`);
-        break;
-      }
-      case "status":
-        console.log(codexShimStatus());
-        break;
-      case "uninstall":
-      case "remove": {
-        const r = uninstallCodexShim();
-        console.log(r.removed ? `✅ ${r.message}` : `⚠️  ${r.message}`);
-        break;
-      }
-      default:
-        console.error("Usage: ocx codex-shim <install|status|uninstall|remove>");
-        process.exit(1);
-    }
-    break;
-  }
-  case "update": {
-    // `ocx update --help` must print usage and exit WITHOUT side effects — running the
-    // real self-update stops the proxy and drops in-flight routed streams (issue #168).
-    if (hasHelpFlag(args.slice(1))) {
-      printSubcommandUsage("update");
-      break;
-    }
-    const { runUpdate } = await import("../update");
-    await runUpdate();
-    break;
-  }
-  case "__refresh-version": {
-    // Hidden, detached helper spawned by the update prompt to refresh the
-    // cached latest version without blocking the foreground start. Not in help.
-    const { refreshVersionCache } = await import("../update/notify");
-    const channel = args[1] === "preview" ? "preview" : "latest";
-    await refreshVersionCache(channel);
-    break;
-  }
-  case "__tray-start":
-  case "__tray-restart":
-  case "__startup-health":
-    await dispatchInternalCliCommand(command as InternalCliCommand, {
-      trayStart: handleTrayProxyStart,
-      trayRestart: handleTrayProxyRestart,
-      startupHealth: async () => {
-        const { collectStartupHealth } = await import("../codex/autostart-health");
-        console.log(JSON.stringify(collectStartupHealth(loadConfig())));
-      },
-    });
-    break;
-  case "__tray-host": {
-    const { runWindowsTrayHost } = await import("../tray/windows");
-    await runWindowsTrayHost();
-    break;
-  }
-  case "__gui-update-worker": {
-    const jobId = args[1];
-    if (!jobId) process.exit(1);
-    const channel = normalizeUpdateChannel(args[2]);
-    await runGuiUpdateWorker(jobId, channel, args[3] === "restart");
-    break;
-  }
-  case "restart": {
-    // A failed stop must not be followed by a re-inject: with a foreign service still running
-    // (ownership mismatch) we would rewrite shared config we just declined to touch.
-    if (await handleStop()) await handleEnsure();
-    else console.error("↩️  Restart aborted: the proxy was not stopped cleanly.");
-    break;
-  }
-  case "health": {
-    const healthArgs = args.slice(1);
-    const wantsHealthJson = healthArgs.includes("--json");
-    const live = await findLiveProxy();
-    if (wantsHealthJson) {
-      console.log(JSON.stringify({ ok: !!live, pid: live?.pid ?? null, port: live?.port ?? null }));
-    } else {
-      console.log(live ? `Proxy healthy (PID ${live.pid}, port ${live.port})` : "Proxy not healthy");
-    }
-    process.exit(live ? 0 : 1);
-  }
-    case "provider": {
-    const { handleProviderCommand } = await import("./provider");
-    await handleProviderCommand(args.slice(1));
-    break;
-  }
-  case "account": {
-    const { cmdAccount } = await import("./account");
-    process.exitCode = await cmdAccount(args.slice(1));
-    break;
-  }
-  case "models":
-  case "model": {
-    const { handleModels } = await import("./models");
-    await handleModels(args.slice(1));
-    break;
-  }
-  case "combo": {
-    const { handleComboCommand } = await import("./combo");
-    process.exitCode = await handleComboCommand(args.slice(1));
-    break;
-  }
-  case "route": {
-    if (args[1] !== "combo") {
-      console.error("Usage: ocx route combo <subcommand>");
-      process.exitCode = 2;
-      break;
-    }
-    const { handleComboCommand } = await import("./combo");
-    process.exitCode = await handleComboCommand(args.slice(2));
-    break;
-  }
-  case "agent": {
-    const { handleAgentCommand } = await import("./agent");
-    process.exitCode = await handleAgentCommand(args.slice(1));
-    break;
-  }
-  case "observe": {
-    const { handleObserveCommand } = await import("./observe");
-    process.exitCode = await handleObserveCommand(args.slice(1));
-    break;
-  }
-  case "logs":
-  case "usage":
-  case "storage":
-  case "memory": {
-    const { handleObserveCommand } = await import("./observe");
-    process.exitCode = await handleObserveCommand([command, ...args.slice(1)]);
-    break;
-  }
-  case "access": {
-    const { handleAccessCommand } = await import("./access");
-    process.exitCode = await handleAccessCommand(args.slice(1));
-    break;
-  }
-  case "api-key": {
-    const { handleAccessCommand } = await import("./access");
-    process.exitCode = await handleAccessCommand(["key", ...args.slice(1)]);
-    break;
-  }
-  case "export": {
-    const { handleExportCommand } = await import("./export-command");
-    process.exitCode = await handleExportCommand(args.slice(1));
-    break;
-  }
-  case "grok": {
-    const { handleGrokCommand } = await import("./integrations");
-    process.exitCode = await handleGrokCommand(args.slice(1));
-    break;
-  }
-  case "integration": {
-    const integration = args[1];
-    if (integration === "grok") {
-      const { handleGrokCommand } = await import("./integrations");
-      process.exitCode = await handleGrokCommand(args.slice(2));
-    } else if (integration === "claude") {
-      const { handleClaudeConfigCommand } = await import("./integrations");
-      process.exitCode = await handleClaudeConfigCommand(args.slice(2));
-    } else {
-      console.error("Usage: ocx integration <claude|grok> <subcommand>");
-      process.exitCode = 2;
-    }
-    break;
-  }
-  case "system": {
-    const { handleSystemCommand } = await import("./system-command");
-    process.exitCode = await handleSystemCommand(args.slice(1));
-    break;
-  }
-  case "config": {
-    const { handleConfigCommand } = await import("./config-command");
-    process.exitCode = await handleConfigCommand(args.slice(1));
-    break;
-  }
-  case "sync-cloud": {
-    const { handleSyncCloudCommand } = await import("./sync-cloud");
-    process.exitCode = await handleSyncCloudCommand(args.slice(1));
-    break;
-  }
-  case "claude": {
-    const { cmdClaude } = await import("./claude");
-    // "ocx claude desktop" → write Desktop 3P config
-    if (args[1] === "desktop") {
-      const { handleClaudeDesktopCommand } = await import("./claude-desktop");
-      const exitCode = await handleClaudeDesktopCommand(args.slice(2));
-      if (exitCode !== 0) process.exit(exitCode);
-      break;
-    }
-    if (args[1] === "config") {
-      const { handleClaudeConfigCommand } = await import("./integrations");
-      process.exitCode = await handleClaudeConfigCommand(args.slice(2));
-      break;
-    }
-    process.exit(await cmdClaude(args.slice(1)));
-  }
-  case "opencode": {
-    const { cmdOpencode } = await import("./opencode");
-    process.exit(await cmdOpencode(args.slice(1)));
-  }
-  case "pi": {
-    const { handlePiCommand } = await import("./pi");
-    process.exitCode = await handlePiCommand(args.slice(1));
-    break;
-  }
-    case "help":
-  case "--help":
-  case "-h":
-  case undefined:
-    printUsage();
-    break;
-  default:
-    console.error(`Unknown command: ${command}`);
-    printUsage();
-    process.exit(1);
+/**
+ * `ocx ready` — arguments are pre-parsed above (before
+ * maybeAutoRestoreCodexShim) so invalid usage exits 64 before any global
+ * preflight. This handler only runs the dependency-injected runner in ./ready
+ * and exits with the returned code; it performs no parsing and no I/O of its
+ * own. The full behavior is unit-testable without spawning a subprocess.
+ */
+async function handleReady(args: ReadyArgs): Promise<number> {
+  return runReady(args);
 }
+
+process.exit(await dispatchCommand(head, {
+  args,
+  command,
+  head,
+  loadConfig,
+  findLiveProxy,
+  probeHostname,
+  waitForProxy,
+  startArgv,
+  spawnDetached: argv => {
+    const child = spawn(process.execPath, argv, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: withProcessRuntimeProvenance(process.env),
+    });
+    child.unref();
+  },
+  handleStart,
+  handleStop,
+  handleEnsure,
+  handleTrayProxyStart,
+  handleTrayProxyRestart,
+  handleRestartStartWhenStopped,
+  handleProxyRestart,
+  handleUninstall,
+  handleStatus,
+  handleRecoverHistory,
+  handleReady,
+  serviceCommand,
+}));