@bitkyc08/opencodex 2.6.17 → 2.6.18

package/src/adapters/openai-chat.ts

@@ -5,6 +5,7 @@ import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoice
 import { mapReasoningEffort } from "../reasoning-effort";
 import { contentPartsToText } from "./image";
 import { neutralizeIdentity } from "./identity";
+import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "./tool-catalog-nudge";
 
 // Z.AI's "glm-5.2[1m]" 1M-context id is a Claude-Code / Anthropic-endpoint-only
 // convention; OpenAI-compatible chat-completions endpoints reject the bracketed
@@ -20,12 +21,16 @@ function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderCon
   const { context, options } = parsed;
   let pendingToolCallIds = new Set<string>();
 
-  if (context.systemPrompt && context.systemPrompt.length > 0) {
+  const toolCatalogNudge = shouldInjectNonOpenAIToolCatalogNudge(provider)
+    ? buildNonOpenAIToolCatalogNudgeForTools(context.tools, options.toolChoice)
+    : undefined;
+  const systemParts = [...(context.systemPrompt ?? []), ...(toolCatalogNudge ? [toolCatalogNudge] : [])];
+  if (systemParts.length > 0) {
     // Codex sends its GPT-5 identity prompt for EVERY model (the per-model catalog
     // base_instructions is ignored at request time). Neutralize that one identity line
     // so routed, non-OpenAI models don't misreport themselves as GPT-5 / OpenAI — without
     // leaking the proxy identity into the payload.
-    const sys = neutralizeIdentity(context.systemPrompt.join("\n\n"));
+    const sys = neutralizeIdentity(systemParts.join("\n\n"));
     out.push({ role: "system", content: sys });
   }
 

package/src/adapters/run-turn-queue.ts

@@ -0,0 +1,58 @@
+import type { AdapterEvent } from "../types";
+
+type QueueReader = (result: IteratorResult<AdapterEvent>) => void;
+
+export interface AdapterEventQueue {
+  push(event: AdapterEvent): void;
+  close(): void;
+  stream(): AsyncIterable<AdapterEvent>;
+  collect(): Promise<AdapterEvent[]>;
+}
+
+export function createAdapterEventQueue(): AdapterEventQueue {
+  const queued: AdapterEvent[] = [];
+  const readers: QueueReader[] = [];
+  let closed = false;
+
+  const push = (event: AdapterEvent): void => {
+    if (closed) return;
+    const reader = readers.shift();
+    if (reader) {
+      reader({ done: false, value: event });
+      return;
+    }
+    queued.push(event);
+  };
+
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    while (readers.length > 0) {
+      readers.shift()?.({ done: true, value: undefined as never });
+    }
+  };
+
+  async function* stream(): AsyncIterable<AdapterEvent> {
+    while (true) {
+      const next = queued.shift();
+      if (next) {
+        yield next;
+        continue;
+      }
+      if (closed) return;
+      const result = await new Promise<IteratorResult<AdapterEvent>>(resolve => {
+        readers.push(resolve);
+      });
+      if (result.done) return;
+      yield result.value;
+    }
+  }
+
+  const collect = async (): Promise<AdapterEvent[]> => {
+    const events: AdapterEvent[] = [];
+    for await (const event of stream()) events.push(event);
+    return events;
+  };
+
+  return { push, close, stream, collect };
+}

package/src/adapters/tool-catalog-nudge.ts

@@ -0,0 +1,71 @@
+import {
+  isAllowedToolChoice,
+  namespacedToolName,
+  toolAllowedByChoice,
+  toolChoiceAliases,
+  type OcxRequestOptions,
+  type OcxTool,
+  type OcxProviderConfig,
+} from "../types";
+
+const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS", "apply_patch"] as const;
+
+function quoteNames(names: readonly string[]): string {
+  return names.map(name => `\`${name}\``).join(", ");
+}
+
+function uniqueNames(names: readonly string[]): string[] {
+  return [...new Set(names.filter(name => name.trim().length > 0))];
+}
+
+function toolChoiceAllows(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
+  if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
+  if (toolChoice === "none") return false;
+  if (isAllowedToolChoice(toolChoice)) return toolAllowedByChoice(tool, new Set(toolChoice.allowedTools));
+  return toolChoiceAliases(tool).includes(toolChoice.name);
+}
+
+function isOpenAIOrChatGPTHost(hostname: string): boolean {
+  return hostname === "openai.com"
+    || hostname.endsWith(".openai.com")
+    || hostname === "chatgpt.com"
+    || hostname.endsWith(".chatgpt.com");
+}
+
+export function shouldInjectNonOpenAIToolCatalogNudge(provider: Pick<OcxProviderConfig, "baseUrl">): boolean {
+  try {
+    return !isOpenAIOrChatGPTHost(new URL(provider.baseUrl).hostname);
+  } catch {
+    return true;
+  }
+}
+
+export function buildNonOpenAIToolCatalogNudgeFromNames(wireNames: readonly string[] | undefined): string | undefined {
+  const names = uniqueNames(wireNames ?? []);
+  if (names.length === 0) return undefined;
+
+  const advertised = new Set(names);
+  const unavailableNeighborNames = NEIGHBOR_AGENT_TOOL_NAMES.filter(name => !advertised.has(name));
+
+  return [
+    "Tool contract: use the current tool catalog as ground truth.",
+    `Valid tool names for this turn are exactly ${quoteNames(names)}.`,
+    "Call only listed names with their listed argument keys; do not invent, translate, or rename tools.",
+    unavailableNeighborNames.length > 0
+      ? `Do not use neighboring-agent tool names ${quoteNames(unavailableNeighborNames)} unless this turn's catalog lists those exact names.`
+      : undefined,
+    "If you need shell, file search, file read, edit, or discovery behavior, choose the listed tool that provides that capability.",
+    "Count a tool call only after its tool result returns; batch independent read-only calls when the runtime supports it.",
+  ].filter((line): line is string => typeof line === "string").join(" ");
+}
+
+export function buildNonOpenAIToolCatalogNudgeForTools(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+  toWireName: (tool: Pick<OcxTool, "namespace" | "name">) => string = tool => namespacedToolName(tool.namespace, tool.name),
+): string | undefined {
+  const visibleNames = tools
+    ?.filter(tool => toolChoiceAllows(tool, toolChoice))
+    .map(toWireName);
+  return buildNonOpenAIToolCatalogNudgeFromNames(visibleNames);
+}

package/src/bridge.ts

@@ -63,6 +63,7 @@ export function bridgeToResponsesSSE(
     stallTimeoutSec?: number;
     hideThinkingSummary?: boolean;
     onTerminal?: (status: ResponsesTerminalStatus) => void;
+    onCompletedResponse?: (response: Record<string, unknown>) => void;
   },
 ): ReadableStream<Uint8Array> {
   // Freeform/custom tools (apply_patch) carry their body in `input`; the model is given a
@@ -437,8 +438,10 @@ export function bridgeToResponsesSSE(
               if (currentRawReasoning) closeCurrentRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (currentWebSearch) closeCurrentWebSearch("completed", []);
+              const response = { ...responseSnapshot("completed", finishedItems), usage: responsesUsage(event.usage) };
+              options?.onCompletedResponse?.(response);
               emit("response.completed", {
-                response: { ...responseSnapshot("completed", finishedItems), usage: responsesUsage(event.usage) },
+                response,
               });
               reportTerminal("completed");
               terminated = true;
@@ -453,6 +456,9 @@ export function bridgeToResponsesSSE(
               emit("response.failed", {
                 response: {
                   ...responseSnapshot("failed", finishedItems),
+                  // Partial consumption from a mid-stream upstream failure: surfaced so the request
+                  // log can record real tokens instead of usageStatus "unreported" with 0.
+                  ...(event.usage ? { usage: responsesUsage(event.usage) } : {}),
                   error: responseError(502, "upstream_error", event.message),
                   last_error: responseError(502, "upstream_error", event.message),
                 },

package/src/cli-help.ts

@@ -14,8 +14,14 @@ const helpEntries: Record<string, HelpEntry> = {
   init: { usage: "ocx init", summary: "Interactive setup for providers and Codex config injection." },
   start: { usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
   stop: { usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
-  restore: { usage: "ocx restore", summary: "Restore native Codex config without stopping the proxy." },
-  eject: { usage: "ocx eject", summary: "Restore native Codex config without stopping the proxy." },
+  restore: {
+    usage: "ocx restore [back]",
+    summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
+  },
+  eject: {
+    usage: "ocx eject [back]",
+    summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
+  },
   "recover-history": {
     usage: "ocx recover-history --legacy-openai",
     summary: "Explicitly recover pre-backup syncResumeHistory rows.",
@@ -72,6 +78,7 @@ Usage:
   ocx start [--port <port>]   Start the proxy server (auto-syncs models to Codex)
   ocx stop                    Stop the proxy AND restore native Codex (plain codex works again)
   ocx restore                 Restore native Codex without stopping (alias: eject)
+  ocx restore back            Re-point codex at the running proxy (undo restore)
   ocx recover-history --legacy-openai
                                Explicitly recover pre-backup syncResumeHistory rows
   ocx uninstall               Remove service/shim/config and restore native Codex (alias: remove)

package/src/cli-status.ts

@@ -1,6 +1,7 @@
 import { durableBunRuntime } from "./bun-runtime";
 import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "./config";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "./codex-plugins-doctor";
+import { isOpencodexHealthz, probeHostname } from "./proxy-liveness";
 import type { OcxConfig } from "./types";
 import { serviceStatusSummary } from "./service";
 
@@ -54,9 +55,6 @@ export type CliStatusView = {
   healthLabel: string;
 };
 
-function healthHost(hostname?: string): string {
-  return !hostname || hostname === "0.0.0.0" || hostname === "::" ? "127.0.0.1" : hostname;
-}
 
 export type ListenTarget = {
   port: number;
@@ -78,7 +76,7 @@ export function selectListenTarget(
     port,
     hostname,
     source: currentRuntimePort ? "runtime" : "config",
-    healthUrl: `http://${healthHost(hostname)}:${port}/healthz`,
+    healthUrl: `http://${probeHostname(hostname)}:${port}/healthz`,
     dashboardUrl: `http://localhost:${port}/`,
   };
 }
@@ -93,7 +91,11 @@ async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
       const message = `returned HTTP ${response.status}`;
       return { ok: false, url, message, label: `${url} ${message}` };
     }
-    const body = await response.json().catch(() => null) as { version?: unknown; uptime?: unknown } | null;
+    const body = await response.json().catch(() => null) as { service?: unknown; status?: unknown; version?: unknown; uptime?: unknown } | null;
+    if (!isOpencodexHealthz(body)) {
+      const message = "responded, but not an opencodex proxy";
+      return { ok: false, url, message, label: `${url} ${message}` };
+    }
     const version = typeof body?.version === "string" ? ` v${body.version}` : "";
     const uptime = typeof body?.uptime === "number" ? `, uptime ${Math.round(body.uptime)}s` : "";
     const message = `ok${version}${uptime}`;

package/src/cli.ts

@@ -9,9 +9,12 @@ import {
   getConfigDir,
   loadConfig,
   readPid,
+  readPidFileValue,
   readRuntimePort,
   removePid,
+  removePidIfValueIs,
   removeRuntimePort,
+  removeRuntimePortIfPidIs,
   saveConfig,
   writePid,
   writeRuntimePort,
@@ -19,12 +22,15 @@ import {
 import { collectStatus } from "./cli-status";
 import { installCrashGuards } from "./crash-guard";
 import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./cli-help";
-import { findAvailablePort, shouldPersistSelectedPort } from "./ports";
-import { killProxy } from "./process-control";
+import { findAvailablePort, isAddrInUse, shouldPersistSelectedPort } from "./ports";
+import { findLiveProxy, probeHostname, type LiveProxy } from "./proxy-liveness";
+import { stopProxy } from "./process-control";
 import { serviceCommand, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "./service";
 import { drainAndShutdown, startServer } from "./server";
 import { maybeShowStarPrompt } from "./star-prompt";
 import { maybeShowUpdatePrompt } from "./update-notify";
+import { syncModelsToCodex } from "./codex-sync";
+import { normalizeUpdateChannel, runGuiUpdateWorker } from "./update-job";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -44,28 +50,6 @@ if (command !== undefined && command !== "help" && hasHelpFlag(args.slice(1))) {
   process.exit(0);
 }
 
-async function syncModelsToCodex(port?: number) {
-  const config = loadConfig();
-  const p = port ?? config.port ?? 10100;
-  let catalogPath: string | null | undefined;
-  try {
-    const { refreshCodexModelCatalog } = await import("./codex-refresh");
-    const cat = await refreshCodexModelCatalog(config);
-    catalogPath = cat.catalogExists ? cat.path : null;
-    if (cat.added > 0) {
-      console.log(`   + ${cat.added} models appended to Codex catalog (${cat.path})`);
-    } else if (catalogPath === null) {
-      console.error("catalog sync skipped: no Codex catalog source found; keeping Codex's native catalog.");
-    }
-  } catch (e) {
-    console.error("catalog sync skipped:", e instanceof Error ? e.message : String(e));
-  }
-  const { injectCodexConfig } = await import("./codex-inject");
-  const result = await injectCodexConfig(p, config, { catalogPath });
-  console.log(result.message);
-  return result;
-}
-
 function parsePortOption(): number | undefined {
   if (args.length === 1) return undefined;
   if (args.length !== 3 || args[1] !== "--port") {
@@ -83,26 +67,13 @@ function parsePortOption(): number | undefined {
   return port;
 }
 
-async function proxyHealthy(port?: number): Promise<boolean> {
-  const config = loadConfig();
-  const p = port ?? config.port ?? 10100;
-  try {
-    const hostname = !config.hostname || config.hostname === "0.0.0.0" || config.hostname === "::" ? "127.0.0.1" : config.hostname;
-    const res = await fetch(`http://${hostname}:${p}/healthz`, {
-      signal: AbortSignal.timeout(750),
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
-async function waitForProxy(timeoutMs = 8_000): Promise<number | null> {
+async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    const config = loadConfig();
-    const port = config.port ?? 10100;
-    if (await proxyHealthy(port)) return port;
+    // Runtime-state-first with identity: finds the proxy even when it started on a
+    // fallback port, and never mistakes a foreign 200 for our proxy.
+    const live = await findLiveProxy();
+    if (live) return live;
     await new Promise(resolve => setTimeout(resolve, 150));
   }
   return null;
@@ -127,9 +98,9 @@ async function handleStart(options: { block?: boolean } = {}) {
   reconcileJournal();
   const existingPid = readPid();
   if (existingPid) {
-    const config = loadConfig();
-    if (await proxyHealthy(config.port)) {
-      console.error(`⚠️  Proxy already running (PID ${existingPid}). Use 'ocx stop' first.`);
+    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);
@@ -140,9 +111,20 @@ async function handleStart(options: { block?: boolean } = {}) {
   // live daemon holding resources while it overwrites its own binary.
   await maybeShowUpdatePrompt();
 
-  const port = await chooseListenPort(requestedPort);
-
-  const server = startServer(port);
+  // Port selection is check-then-bind: a concurrent `ocx start`/`ensure` can win the port
+  // between the probe and Bun.serve. Retry the pick instead of dying on EADDRINUSE.
+  let port = await chooseListenPort(requestedPort);
+  let server: ReturnType<typeof startServer>;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      server = startServer(port);
+      break;
+    } catch (err) {
+      if (!isAddrInUse(err) || attempt >= 2) throw err;
+      console.log(`⚠️  Port ${port} was taken while starting; picking another...`);
+      port = await chooseListenPort(requestedPort);
+    }
+  }
   // A single request's streaming error must never crash the daemon serving every
   // other Codex session — capture the full stack to crash.log and stay up.
   installCrashGuards();
@@ -206,16 +188,17 @@ async function handleStart(options: { block?: boolean } = {}) {
 
 async function handleEnsure() {
   reconcileJournal();
-  let config = loadConfig();
+  const config = loadConfig();
   if (!codexAutoStartEnabled(config)) {
     console.log("Codex autostart is disabled.");
     return;
   }
-  if (await proxyHealthy(config.port)) {
-    await syncModelsToCodex(config.port).catch(e => {
+  const live = await findLiveProxy();
+  if (live) {
+    await syncModelsToCodex(live.port).catch(e => {
       console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
     });
-    console.log(`✅ Proxy running on port ${config.port}`);
+    console.log(`✅ Proxy running on port ${live.port}`);
     return;
   }
 
@@ -227,19 +210,20 @@ async function handleEnsure() {
   });
   child.unref();
 
-  const port = await waitForProxy();
+  const port = (await waitForProxy())?.port;
   if (!port) {
     console.error("❌ Proxy did not become healthy after starting.");
     process.exit(1);
   }
-  config = loadConfig();
-  await syncModelsToCodex(config.port ?? port).catch(e => {
+  // 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 => {
     console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
   });
-  console.log(`✅ Proxy running on port ${config.port ?? port}`);
+  console.log(`✅ Proxy running on port ${port}`);
 }
 
-function handleStop() {
+async function handleStop() {
   const stoppedService = stopServiceIfInstalled();
   if (stoppedService) console.log("🛑 Service manager stopped (won't respawn).");
 
@@ -247,7 +231,9 @@ function handleStop() {
   let stopFailed = false;
   if (pid) {
     try {
-      killProxy(pid);
+      // Graceful-first (management-API drain) — on Windows this is the only path where
+      // the proxy's shutdown handlers actually run; taskkill /F is the fallback inside.
+      await stopProxy(pid);
       console.log(`✅ Proxy (PID ${pid}) stopped.`);
       removePid(pid);
       removeRuntimePort(pid);
@@ -255,8 +241,32 @@ function handleStop() {
       stopFailed = true;
       console.error(`❌ Failed to stop proxy (PID ${pid}).`);
     }
-  } else if (!stoppedService) {
-    console.log("No running proxy found.");
+  } else {
+    // Snapshot the stale on-disk state BEFORE the async probe: a concurrent `ocx start`
+    // can write fresh records mid-probe, and the purge below must never delete those.
+    const stalePidValue = readPidFileValue();
+    const staleRuntimePid = readRuntimePort()?.pid ?? null;
+    // Orphan recovery: a live proxy can outlive its pid file (crash, manual delete,
+    // corrupt file). Identity-checked liveness still finds it via the runtime record.
+    const live = await findLiveProxy();
+    if (live?.pid) {
+      try {
+        await stopProxy(live.pid);
+        console.log(`✅ Proxy (PID ${live.pid}) stopped.`);
+      } catch {
+        stopFailed = true;
+        console.error(`❌ Failed to stop proxy (PID ${live.pid}).`);
+      }
+    } else if (!stoppedService) {
+      console.log("No running proxy found.");
+    }
+    if (!stopFailed) {
+      // `readPid() === null` means the snapshotted pid file was absent, invalid, dead, or
+      // not ours — stale by definition. Purge (guarded by the snapshot) so `ocx update`'s
+      // stop gate can't wedge on it.
+      removePidIfValueIs(stalePidValue);
+      removeRuntimePortIfPidIs(staleRuntimePid);
+    }
   }
   const r = restoreNativeCodex();
   console.log(`↩️  ${r.message}`);
@@ -266,9 +276,9 @@ function handleStop() {
 async function handleUninstall() {
   const failures: string[] = [];
 
-  const runStep = (label: string, step: () => void | boolean) => {
+  const runStep = async (label: string, step: () => void | boolean | Promise<void | boolean>) => {
     try {
-      const changed = step();
+      const changed = await step();
       if (changed === false) console.log(`- ${label}: not installed`);
       else console.log(`✅ ${label}`);
     } catch (err) {
@@ -277,20 +287,20 @@ async function handleUninstall() {
     }
   };
 
-  runStep("service stopped", () => stopServiceIfInstalled());
+  await runStep("service stopped", () => stopServiceIfInstalled());
 
-  runStep("proxy stopped", () => {
+  await runStep("proxy stopped", async () => {
     const pid = readPid();
     if (!pid) return false;
-    killProxy(pid);
+    await stopProxy(pid);
     removePid(pid);
     removeRuntimePort(pid);
     return true;
   });
 
-  runStep("service removed", () => uninstallServiceIfInstalled());
+  await runStep("service removed", () => uninstallServiceIfInstalled());
 
-  runStep("native Codex restored", () => {
+  await runStep("native Codex restored", () => {
     const r = restoreNativeCodex();
     if (!r.success) throw new Error(r.message);
   });
@@ -305,7 +315,7 @@ async function handleUninstall() {
   }
 
   if (failures.length === 0) {
-    runStep("opencodex config removed", () => {
+    await runStep("opencodex config removed", () => {
       rmSync(getConfigDir(), { recursive: true, force: true });
     });
   } else {
@@ -355,6 +365,11 @@ async function handleStatus() {
       console.log(`      Suggested: ${status.json.codexPlugins.suggestedRepair}`);
     }
   }
+  const { oauthLoginSummary } = await import("./oauth/index");
+  console.log(`   OAuth logins:`);
+  for (const e of oauthLoginSummary()) {
+    console.log(`     ${e.provider.padEnd(10)} ${e.loggedIn ? `✓ logged in${e.email ? ` (${e.email})` : ""}` : "✗ not logged in"}`);
+  }
 }
 
 function handleRecoverHistory() {
@@ -364,6 +379,12 @@ function handleRecoverHistory() {
     process.exit(1);
   }
   const r = restoreLegacyOpenaiHistory();
+  if (r.failed) {
+    console.error(
+      "⚠️  Recovery SKIPPED: the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command.",
+    );
+    process.exit(1);
+  }
   console.log(`Recovered ${r.rows} legacy thread(s) to openai (${r.files} rollout file(s) updated).`);
 }
 
@@ -377,13 +398,26 @@ switch (command) {
     await handleStart();
     break;
   case "stop":
-    handleStop();
+    await handleStop();
     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);
+      }
+      await syncModelsToCodex(live.port);
+      console.log("Plain `codex` now routes through opencodex again (undo with: ocx restore).");
+      break;
+    }
     const r = restoreNativeCodex();
     console.log(r.success ? `✅ ${r.message}` : `⚠️  ${r.message}`);
-    console.log("Plain `codex` now runs natively (no proxy).");
+    console.log("Plain `codex` now runs natively (no proxy). Switch back with: ocx restore back");
     break;
   }
   case "recover-history":
@@ -417,7 +451,7 @@ switch (command) {
     break;
   }
   case "sync": {
-    await syncModelsToCodex();
+    await syncModelsToCodex((await findLiveProxy())?.port);
     break;
   }
   case "sync-cache": {
@@ -428,8 +462,10 @@ switch (command) {
   case "gui": {
     const cfg = await import("./config");
     const config = cfg.loadConfig();
-    let pid = cfg.readPid();
-    if (!pid) {
+    // 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, [process.argv[1], "start"], {
         detached: true,
@@ -438,19 +474,19 @@ switch (command) {
         env: process.env,
       });
       child.unref();
-      await new Promise(r => setTimeout(r, 1000));
-      pid = cfg.readPid();
+      live = await waitForProxy();
     }
-    const runtimePort = pid ? cfg.readRuntimePort(pid) : null;
-    const guiPort = runtimePort?.port ?? config.port;
-    const guiUrl = `http://localhost:${guiPort}`;
+    // 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("./open-url");
     openUrl(guiUrl);
     break;
   }
   case "service":
-    serviceCommand(args[1]);
+    await serviceCommand(args[1]);
     break;
   case "codex-shim": {
     const { codexShimStatus, installCodexShim, uninstallCodexShim } = await import("./codex-shim");
@@ -488,6 +524,13 @@ switch (command) {
     await refreshVersionCache(channel);
     break;
   }
+  case "__gui-update-worker": {
+    const jobId = args[1];
+    if (!jobId) process.exit(1);
+    const channel = normalizeUpdateChannel(args[2]);
+    runGuiUpdateWorker(jobId, channel, args[3] === "restart");
+    break;
+  }
   case "help":
   case "--help":
   case "-h":