@bitkyc08/opencodex 2.7.43-preview.20260728 → 2.8.0

package/src/cli/agent-driven.ts

@@ -0,0 +1,37 @@
+/**
+ * Detects whether this process was started by a coding agent rather than typed
+ * by a person.
+ *
+ * Agent harnesses run `ocx` on the user's behalf and answer prompts from their
+ * own logic, which means a consent question would be decided by the agent
+ * instead of the account owner. Prompts that act on the user's identity check
+ * this and defer instead: they stay silent so the question reaches the human on
+ * a later hand-typed run.
+ *
+ * Detection is env-var based and deliberately conservative — a false positive
+ * only postpones a prompt, while a false negative would let an agent answer for
+ * the user.
+ */
+
+/** Env vars set by agent harnesses and CI runners inside the shell they spawn. */
+const AGENT_ENV_VARS = [
+  "CLAUDECODE",
+  "CLAUDE_CODE_ENTRYPOINT",
+  "CODEX_THREAD_ID",
+  "CODEX_SHELL",
+  "CODEX_CI",
+  "CURSOR_TRACE_ID",
+  "CURSOR_SESSION_TOKEN",
+  "AIDER_CHAT",
+  "REPL_ID",
+  "CI",
+  "GITHUB_ACTIONS",
+] as const;
+
+/**
+ * True when an agent or automated runner is driving this process. Reads the
+ * environment on every call so tests and long-lived processes see current state.
+ */
+export function isAgentDriven(env: NodeJS.ProcessEnv = process.env): boolean {
+  return AGENT_ENV_VARS.some(name => (env[name] ?? "").trim() !== "");
+}

package/src/cli/catalog-prewarm.ts

@@ -0,0 +1,24 @@
+import type { OcxConfig } from "../types";
+
+type GatherRoutedModels = (config: OcxConfig) => Promise<unknown>;
+
+export type CatalogPrewarmDeps = {
+  loadConfig?: () => OcxConfig;
+  importCatalog?: () => Promise<{ gatherRoutedModels: GatherRoutedModels }>;
+};
+
+/**
+ * After the listen port is bound, kick off live provider discovery so the first
+ * GUI /v1/models and syncModelsToCodex share one gather flight instead of racing
+ * duplicate upstream /models fetches.
+ */
+export function scheduleCatalogPrewarm(deps: CatalogPrewarmDeps = {}): void {
+  void Promise.resolve()
+    .then(async () => {
+      const load = deps.loadConfig ?? (await import("../config")).loadConfig;
+      const { gatherRoutedModels } = await (deps.importCatalog?.() ?? import("../codex/catalog"));
+      return gatherRoutedModels(load());
+    })
+    .catch(() => {});
+}
+

package/src/cli/claude.ts

@@ -14,6 +14,7 @@ import { refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
 import { commandInvocation } from "../lib/win-exec";
 import { findLiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
+import { configuredAdminToken } from "../lib/admin-secrets";
 import { PROXY_MARKER, ownAdmissionTokens, defaultAuthDetectDeps, detectClaudeAuth, type AuthDetectDeps } from "../claude/auth-detect";
 import { resolveClaudeAuthMode } from "../claude/auth-mode";
 
@@ -47,6 +48,27 @@ export function buildClaudeEnv(
   // leaving the child with no token at all (audit R2-1). It is opencodex state, never
   // user auth, so dropping it unconditionally is safe.
   if (env.ANTHROPIC_AUTH_TOKEN === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
+  // Step 1b — drop Anthropic credentials that the bundled Bun runtime synthesized from a
+  // project `.env`/`.env.local` (issue #701). Claude Code disables claude.ai connectors the
+  // moment either token slot is populated, so an ambient project file silently moved a
+  // subscriber onto API billing while their OAuth login stayed healthy. The npm launcher
+  // runs under Node, which does NOT auto-load dotenv, so it records the slots that existed
+  // before Bun started; anything populated now but absent then came from the working
+  // directory, not from the user. A genuine shell export is still honored, which keeps
+  // auto-mode API-key auth working. An ABSENT marker means provenance is unknowable
+  // (a direct `bun src/cli/index.ts` run, a test, or an older launcher), and then we
+  // change nothing rather than guess — an EMPTY marker is different: the launcher ran
+  // and saw no pre-existing slots.
+  const preBunSlots = base.OCX_PRE_BUN_ANTHROPIC_ENV;
+  if (preBunSlots !== undefined) {
+    const exported = new Set(preBunSlots.split(",").filter(name => name.length > 0));
+    for (const name of ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"] as const) {
+      const value = env[name];
+      if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
+    }
+  }
+  // Never forward the seam itself to Claude Code.
+  delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
   const setDefault = (name: string, value: string | undefined) => {
     if (value === undefined || value.length === 0) return;
     if (env[name] !== undefined && env[name] !== "") return; // user wins
@@ -75,15 +97,19 @@ export function buildClaudeEnv(
   if ((config.apiKeys?.length ?? 0) > 0) {
     setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
   }
-  // Detection reads the SAME base env this launch will use, so the resolver and the
-  // spawned process cannot disagree. Injected deps are spread FIRST and `env` bound
-  // LAST, and the injection type excludes `env`, so a test fake cannot break that.
-  // `ownTokens` is bound last for the same reason: it is config-derived, and a fake
-  // that replaced it could make our own admission key look like user auth.
+  // Detection reads the SANITIZED launch env — the exact object spawned below — so the
+  // resolver and the spawned process cannot disagree. It deliberately does NOT read the
+  // raw base: the provenance strip above already removed dotenv-only credentials, and
+  // letting a value the child never receives decide the marker left an auto-mode user
+  // with neither the credential NOR the proxy marker (#701 audit round 2). Injected deps
+  // are spread FIRST and `env` bound LAST, and the injection type excludes `env`, so a
+  // test fake cannot break that. `ownTokens` is bound last for the same reason: it is
+  // config-derived, and a fake that replaced it could make our own admission key look
+  // like user auth.
   const resolved = resolveClaudeAuthMode(config, detectClaudeAuth({
-    ...defaultAuthDetectDeps(base as NodeJS.ProcessEnv),
+    ...defaultAuthDetectDeps(env as NodeJS.ProcessEnv),
     ...(deps.authDetect ?? {}),
-    env: () => base as NodeJS.ProcessEnv,
+    env: () => env as NodeJS.ProcessEnv,
     ownTokens: ownAdmissionTokens(config),
   }));
   if (!env.ANTHROPIC_AUTH_TOKEN && resolved.markerMode === "proxy") {
@@ -149,14 +175,13 @@ export function buildClaudeEnv(
 
 /**
  * Context-window map from the RUNNING proxy's management API (warm TTL cache; the
- * daemon registers every selector form — audit R3#1). 3s bound + auth header
- * (OPENCODEX_API_AUTH_TOKEN first, config key fallback — audit R4#1). Failure → {}
+ * daemon registers every selector form — audit R3#1). 3s bound + management auth header.
  * (no [1m] marking, conservative).
  */
 export async function fetchClaudeContextWindows(config: OcxConfig, port: number, timeoutMs = 3_000): Promise<Record<string, number>> {
   try {
     const headers = new Headers();
-    const token = process.env.OPENCODEX_API_AUTH_TOKEN || config.apiKeys?.[0]?.key;
+    const token = configuredAdminToken();
     if (token) headers.set("x-opencodex-api-key", token);
     const res = await fetch(`http://127.0.0.1:${port}/api/claude-code`, {
       headers,

package/src/cli/doctor.ts

@@ -11,9 +11,11 @@ import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, readRuntimePort, resolveEnvValue } from "../config";
+import { findLiveProxy } from "../server/proxy-liveness";
 import { gracefulStopHost } from "../lib/process-control";
 import { maskAccountId } from "../lib/privacy";
-import { loadServiceTokenFromFile } from "../lib/service-secrets";
+import { PROXY_ENV_KEYS, proxyEnvPresent } from "../lib/proxy-env";
+import { configuredAdminToken } from "../lib/admin-secrets";
 import { readCodexTokens } from "../codex/auth-collision";
 import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
 import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
@@ -285,17 +287,15 @@ export function collectWslDualInstall(deps: WslDualInstallDeps = {}): WslDualIns
   };
 }
 
-const PROXY_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY"] as const;
-
 export type ProxyEnvRow = { key: string; present: boolean };
 export type EnvMap = Record<string, string | undefined>;
 
 /** Report only presence/absence of proxy env vars - never the value (it may
  * embed credentials). Checks both upper- and lower-case forms. */
 export function collectProxyEnv(env: EnvMap = process.env): ProxyEnvRow[] {
-  return PROXY_KEYS.map(key => ({
+  return PROXY_ENV_KEYS.map(key => ({
     key,
-    present: !!(env[key]?.trim() || env[key.toLowerCase()]?.trim()),
+    present: proxyEnvPresent(key, env),
   }));
 }
 
@@ -307,13 +307,47 @@ export type ConfiguredProxyDiagnostic = {
   detail: string;
 };
 
-function envReferenceName(value: string): string | null {
+export function envReferenceName(value: string): string | null {
   const braced = value.match(/^\$\{(\w+)\}$/);
   if (braced) return braced[1]!;
   const bare = value.match(/^\$(\w+)$/);
   return bare ? bare[1]! : null;
 }
 
+export type ProviderApiKeyDiagnostic = {
+  provider: string;
+  envName: string;
+  detail: string;
+};
+
+/** Warn when a key-auth provider's apiKey env reference resolves empty in this process. */
+export function collectProviderApiKeyDiagnostics(
+  providers: Record<string, { authMode?: string; apiKey?: string }> = readConfigDiagnostics().config.providers ?? {},
+  env: EnvMap = process.env,
+): ProviderApiKeyDiagnostic[] {
+  const resolveInEnv = (value: string): string | undefined => {
+    const name = envReferenceName(value);
+    if (!name) return value;
+    return env[name];
+  };
+  const rows: ProviderApiKeyDiagnostic[] = [];
+  for (const [provider, config] of Object.entries(providers)) {
+    if (config.authMode !== "key") continue;
+    const raw = typeof config.apiKey === "string" ? config.apiKey.trim() : "";
+    if (!raw) continue;
+    const envName = envReferenceName(raw);
+    if (!envName) continue;
+    const resolved = resolveInEnv(raw);
+    if (resolved?.trim()) continue;
+    rows.push({
+      provider,
+      envName,
+      detail: `provider ${provider}: env reference ${envName} is unset or empty in this process`,
+    });
+  }
+  return rows;
+}
+
 export function collectConfiguredProxy(): ConfiguredProxyDiagnostic {
   const diagnostics = readConfigDiagnostics();
   const rawProxy = typeof diagnostics.config.proxy === "string" ? diagnostics.config.proxy.trim() : "";
@@ -571,7 +605,7 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
   const lines: string[] = [];
   lines.push(`  --     doctor process Bun ${Bun.version} (this is NOT the service process)`);
   if (report.status === "unauthorized") {
-    lines.push("  --     proxy reachable but rejected the request — set OPENCODEX_API_AUTH_TOKEN to match the service");
+    lines.push("  --     proxy reachable but rejected the request — set OPENCODEX_ADMIN_AUTH_TOKEN to match the service");
     return lines;
   }
   if (report.status === "unreachable") {
@@ -718,9 +752,21 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     }
   }
 
+  // #618: identity-verified liveness first so pid-file absence does not hide a live service.
+  // Reuse the diagnostics config already loaded above so doctor stays read-only on malformed JSON.
+  const live = await findLiveProxy({
+    configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
+  });
+  const livePid = live ? live.pid : readPid();
+  const liveRuntime = live
+    ? { pid: live.pid ?? 0, port: live.port, hostname: live.hostname }
+    : (livePid ? readRuntimePort(livePid) : null);
+
   const currentProxyEnv = collectProxyEnv();
   const configuredProxy = collectConfiguredProxy();
-  const runningProxyEnv = collectRunningProxyEnv();
+  const runningProxyEnv = collectRunningProxyEnv({
+    readPidFn: () => (live ? live.pid : readPid()),
+  });
 
   console.log("\nCurrent doctor process proxy env (presence only)");
   for (const row of currentProxyEnv) {
@@ -730,6 +776,16 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log("\nConfigured proxy (value hidden)");
   console.log(`  ${configuredProxy.present ? "set    " : "unset  "} ${configuredProxy.key} (${configuredProxy.source}; ${configuredProxy.detail})`);
 
+  const providerApiKeys = collectProviderApiKeyDiagnostics(doctorConfig.providers);
+  console.log("\nProvider API keys (value hidden)");
+  if (providerApiKeys.length === 0) {
+    console.log("  ok     no empty env-referenced provider keys detected in this process");
+  } else {
+    for (const row of providerApiKeys) {
+      console.log(`  !!     ${row.detail}`);
+    }
+  }
+
   console.log("\nRunning proxy process proxy env (presence only)");
   if (runningProxyEnv.status === "not_running") {
     console.log("  --     no running ocx proxy process found");
@@ -742,21 +798,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     }
   }
 
-  // #314: service-process memory/runtime identity via the authed management
-  // endpoint. readPid() FIRST (liveness), then the pid-scoped runtime record —
-  // readRuntimePort alone can serve a stale file pointing at a foreign port.
-  // Hoisted out of the block below: the Hints section reuses the same liveness pair
-  // for the proxy-down restart hint.
-  const livePid = readPid();
-  const liveRuntime = livePid ? readRuntimePort(livePid) : null;
   console.log("\nMemory / runtime");
   {
     const runtime = liveRuntime;
-    if (!runtime) {
+    if (!runtime || !live) {
       console.log(`  --     doctor process Bun ${Bun.version} (this is NOT the service process)`);
       console.log("  --     no running ocx proxy found (no live pid/runtime record)");
     } else {
-      const token = process.env.OPENCODEX_API_AUTH_TOKEN ?? loadServiceTokenFromFile(process.env);
+      const token = configuredAdminToken();
       const report = await fetchServiceMemory(gracefulStopHost(runtime.hostname), runtime.port, token);
       for (const line of formatServiceMemoryLines(report)) console.log(line);
     }
@@ -815,11 +864,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   // Hints, not fixes.
   const hints: string[] = [];
   const proxyDown = proxyDownRestartHint({
-    proxyRunning: Boolean(livePid && liveRuntime),
-    port: doctorConfig.port ?? 10100,
+    proxyRunning: Boolean(live),
+    port: live?.port ?? doctorConfig.port ?? 10100,
     serviceViable: startup.serviceViable,
   });
   if (proxyDown) hints.push(proxyDown);
+  for (const row of providerApiKeys) {
+    hints.push(`${row.detail}. Set ${row.envName} in the shell that starts the proxy, or store a literal key in config (value hidden here).`);
+  }
   const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
   const noProxy = currentProxyEnv.every(p => !p.present) && !configuredProxy.present;
   if (!startup.rebootSafe) {

package/src/cli/help.ts

@@ -30,12 +30,18 @@ const helpEntries: Record<string, HelpEntry> = {
   uninstall: {
     usage: "ocx uninstall",
     summary: "Remove service/shim/config and restore native Codex.",
-    details: ["Alias: ocx remove"],
+    details: [
+      "Alias: ocx remove",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
   },
   remove: {
     usage: "ocx remove",
     summary: "Remove service/shim/config and restore native Codex.",
-    details: ["Alias of: ocx uninstall"],
+    details: [
+      "Alias of: ocx uninstall",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
   },
   service: {
     usage: "ocx service [install|start|stop|status|uninstall|remove]",
@@ -60,8 +66,22 @@ const helpEntries: Record<string, HelpEntry> = {
     ],
   },
   ensure: { usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
-  sync: { usage: "ocx sync", summary: "Fetch provider models and inject them into Codex config." },
-  "sync-cache": { usage: "ocx sync-cache", summary: "Refresh Codex's model cache from the active catalog." },
+  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).",
+    ],
+  },
+  "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).",
+    ],
+  },
   status: { usage: "ocx status", summary: "Check proxy server status." },
   doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
   debug: {
@@ -184,6 +204,20 @@ const helpEntries: Record<string, HelpEntry> = {
       "Claude Code settings: ocx claude config <status|set> ...",
     ],
   },
+  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.",
+    ],
+  },
   restart: {
     usage: "ocx restart",
     summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
@@ -232,8 +266,9 @@ Usage:
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
   ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
   ocx ensure                  Ensure the proxy is running and Codex config/cache are current
-  ocx sync                    Fetch models from providers and inject into Codex config
-  ocx sync-cache              Refresh Codex's model cache from the active catalog
+  ocx sync [--restart-codex]  Fetch models from providers and inject into Codex config
+  ocx sync-cache [--restart-codex]
+                              Refresh Codex's model cache from the active catalog
   ocx status                  Check proxy server status
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
   ocx debug <scope>           provider/usage/injection/claude on|off|status|reset
@@ -256,6 +291,7 @@ Usage:
   ocx config <sub>            Validated configuration show/get/set/import/export
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
+  ocx opencode [args...]      Launch opencode wired to the proxy (runtime provider config)
   ocx help [command]          Show help
   ocx --version | -v          Print version
 

package/src/cli/index.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env bun
 import { spawn } from "node:child_process";
-import { rmSync } from "node:fs";
 import { currentExternalCodexModelProvider, restoreNativeCodex, shouldInjectApiAuthHeader } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
 import { restoreLegacyOpenaiHistory } from "../codex/history-provider";
@@ -31,7 +30,7 @@ import { 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 { drainAndShutdown, startServer } from "../server";
+import { drainAndShutdown, isRecyclingForExit, startServer } from "../server";
 import { injectSystemEnv, revertSystemEnv } from "../server/system-env";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
 import { installShellHook, uninstallShellHook } from "../server/system-env";
@@ -39,10 +38,12 @@ 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];
@@ -190,6 +191,10 @@ async function handleStart(options: { block?: boolean } = {}) {
   for (let attempt = 0; ; attempt++) {
     try {
       server = startServer(port);
+      // 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.
+      scheduleCatalogPrewarm();
       break;
     } catch (err) {
       if (!isAddrInUse(err) || attempt >= 2) throw err;
@@ -227,24 +232,40 @@ async function handleStart(options: { block?: boolean } = {}) {
   let historyGuardian: ReturnType<typeof startHistoryMigrationGuardian> | undefined;
 
   let cleaned = false;
+  let cleanupSucceeded = true;
   const syncCleanup = () => {
-    if (cleaned) return;
+    if (cleaned) return cleanupSucceeded;
     cleaned = true;
     try { guardian.stop(); } catch { /* best-effort */ }
     try { historyGuardian?.stop(); } catch { /* best-effort */ }
-    try { revertSystemEnv(); } catch { /* best-effort */ }
+    // Dashboard drain-and-restart (#563) must not tear down injection: the replacement
+    // process expects Codex/Grok/env fences to still be in place.
+    const recycling = isRecyclingForExit();
+    if (!recycling) {
+      try { revertSystemEnv(); } catch { /* best-effort */ }
+    }
     removePid(process.pid);
     removeRuntimePort(process.pid);
-    if (!process.env.OCX_SERVICE && !currentExternalCodexModelProvider()) {
-      try { restoreNativeCodex(); } catch { /* best-effort restore */ }
+    if (!recycling && !process.env.OCX_SERVICE && !currentExternalCodexModelProvider()) {
+      try {
+        const restored = restoreNativeCodex();
+        if (!restored.success) {
+          cleanupSucceeded = false;
+          console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+        }
+      } catch (error) {
+        cleanupSucceeded = false;
+        console.error(`⚠️  Native Codex restore failed during shutdown: ${error instanceof Error ? error.message : String(error)}`);
+      }
     }
     // Same ownership rule as `ocx stop`: if the installed service belongs to another home, the
     // 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 (!process.env.OCX_SERVICE && serviceEnvironmentOwnedHere()) {
+    if (!recycling && !process.env.OCX_SERVICE && serviceEnvironmentOwnedHere()) {
       try { stripGrokConfig(); } catch { /* best-effort restore */ }
     }
+    return cleanupSucceeded;
   };
 
   let shuttingDown = false;
@@ -269,8 +290,8 @@ async function handleStart(options: { block?: boolean } = {}) {
       try {
         await drainAndShutdown(server, config.shutdownTimeoutMs ?? 5000);
       } finally {
-        syncCleanup(); // idempotent (cleaned-guard); also re-run by process.on("exit")
-        process.exit(0);
+        const restored = syncCleanup(); // idempotent (cleaned-guard); also re-run by process.on("exit")
+        process.exit(restored ? 0 : 1);
       }
     })();
   };
@@ -288,7 +309,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   // Auto-install .zshrc hook (idempotent — skips if already present).
   installShellHook();
 
-  await maybeShowStarPrompt(); // once-only [y/N] GitHub-star prompt on first interactive start
+  await maybeShowStarPrompt(); // once-only Yes/No GitHub-star prompt on first interactive start
   await syncModelsToCodex(port).catch(() => {});
   if (!currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
     historyGuardian = startHistoryMigrationGuardian();
@@ -499,7 +520,11 @@ async function handleStop() {
   }
   if (!ownershipBlocked) {
     const r = restoreNativeCodex();
-    console.log(`↩️  ${r.message}`);
+    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).
@@ -588,7 +613,13 @@ async function handleUninstall() {
 
   if (failures.length === 0) {
     await runStep("opencodex config removed", () => {
-      rmSync(getConfigDir(), { recursive: true, force: true });
+      const result = removeOwnedConfigState(getConfigDir());
+      if (result.status === "absent") return false;
+      if (result.status === "removed") return true;
+      const residual = result.residualPaths.length > 0
+        ? ` Residual path(s): ${result.residualPaths.join(", ")}`
+        : "";
+      throw new Error(`${result.status} uninstall: ${result.reason ?? "config state was not removed"}.${residual}`);
     });
   } else {
     console.error("Leaving opencodex config/backups in place so the failed restore step can be retried.");
@@ -716,19 +747,40 @@ switch (command) {
         console.error("No running proxy found. Run 'ocx start' — it injects opencodex automatically.");
         process.exit(1);
       }
-      await syncModelsToCodex(live.port);
+      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;
     }
-    const r = restoreNativeCodex();
-    console.log(r.success ? `✅ ${r.message}` : `⚠️  ${r.message}`);
+    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}`);
+      else if (!g.ok) {
+        console.error(`⚠️  ${g.message}`);
+        process.exitCode = 1;
+      }
     } catch { /* best-effort */ }
-    console.log("Plain `codex` now runs natively (no proxy). Switch back with: ocx restore back");
+    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":
@@ -767,7 +819,20 @@ switch (command) {
     break;
   }
   case "sync": {
-    await syncModelsToCodex((await findLiveProxy())?.port);
+    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": {
@@ -776,8 +841,13 @@ switch (command) {
     break;
   }
   case "sync-cache": {
+    const restartCodex = args.slice(1).includes("--restart-codex");
     const { invalidateCodexModelsCache } = await import("../codex/catalog");
-    invalidateCodexModelsCache();
+    // 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": {
@@ -1005,6 +1075,10 @@ switch (command) {
       break;
     }
     process.exit(await cmdClaude(args.slice(1)));
+  }
+  case "opencode": {
+    const { cmdOpencode } = await import("./opencode");
+    process.exit(await cmdOpencode(args.slice(1)));
   }
     case "help":
   case "--help":