@bitkyc08/opencodex 2.5.6 → 2.6.0

package/src/service-secrets.ts

@@ -0,0 +1,6 @@
+import { join } from "node:path";
+import { getConfigDir } from "./config";
+
+export function serviceApiTokenFilePath(): string {
+  return join(getConfigDir(), "service-api-token");
+}

package/src/service.ts

@@ -6,12 +6,15 @@
  * restore it via the command.
  */
 import { execFileSync, execSync } from "node:child_process";
-import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { getConfigDir } from "./config";
+import { dirname, join, resolve } from "node:path";
+import { getConfigDir, readPid, removePid } from "./config";
+import { loadConfig } from "./config";
 import { restoreNativeCodex } from "./codex-inject";
-import { durableBunPath } from "./bun-runtime";
+import { durableBunPath, durableBunRuntime } from "./bun-runtime";
+import { isProcessAlive, killProxy } from "./process-control";
+import { serviceApiTokenFilePath } from "./service-secrets";
 
 const LABEL = "com.opencodex.proxy";
 const TASK = "opencodex-proxy";
@@ -31,10 +34,99 @@ function logPath(): string {
   return join(getConfigDir(), "service.log");
 }
 
+export function serviceLogPath(): string {
+  return logPath();
+}
+
 function windowsServiceScriptPath(): string {
   return join(getConfigDir(), "opencodex-service.cmd");
 }
 
+function windowsTaskXmlPath(): string {
+  return join(getConfigDir(), "opencodex-service-task.xml");
+}
+
+function serviceStatePath(): string {
+  return join(getConfigDir(), "service-state.json");
+}
+
+function defaultOpenCodexHome(): string {
+  return resolve(join(homedir(), ".opencodex"));
+}
+
+function serviceStatePaths(): string[] {
+  const paths = [serviceStatePath()];
+  const defaultPath = join(defaultOpenCodexHome(), "service-state.json");
+  if (normalizePathForCompare(defaultPath) !== normalizePathForCompare(paths[0])) paths.push(defaultPath);
+  return paths;
+}
+
+function currentCodexHome(): string {
+  return resolve(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"));
+}
+
+function currentOpenCodexHome(): string {
+  return resolve(process.env.OPENCODEX_HOME?.trim() || getConfigDir());
+}
+
+function normalizePathForCompare(path: string): string {
+  const resolved = resolve(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+interface ServiceInstallState {
+  version: 1;
+  codexHome: string;
+  opencodexHome: string;
+}
+
+function writeServiceInstallState(): void {
+  const state: ServiceInstallState = {
+    version: 1,
+    codexHome: currentCodexHome(),
+    opencodexHome: currentOpenCodexHome(),
+  };
+  for (const path of serviceStatePaths()) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(state, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  }
+}
+
+function readServiceInstallState(): ServiceInstallState | null {
+  for (const path of serviceStatePaths()) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as ServiceInstallState;
+      if (parsed.version === 1) return parsed;
+    } catch {
+      /* try the next known state path */
+    }
+  }
+  return null;
+}
+
+export function assertServiceEnvironmentMatchesInstall(): void {
+  const state = readServiceInstallState();
+  if (!state) return;
+  const expected = normalizePathForCompare(state.codexHome);
+  const actual = normalizePathForCompare(currentCodexHome());
+  if (expected !== actual) {
+    throw new Error(
+      `Service was installed with CODEX_HOME=${state.codexHome}, but current CODEX_HOME=${currentCodexHome()}. ` +
+        "Run the service command from the same Codex home so native Codex restore updates the correct config.",
+    );
+  }
+  const expectedOpenCodexHome = normalizePathForCompare(state.opencodexHome);
+  const actualOpenCodexHome = normalizePathForCompare(currentOpenCodexHome());
+  if (expectedOpenCodexHome !== actualOpenCodexHome) {
+    throw new Error(
+      `Service was installed with OPENCODEX_HOME=${state.opencodexHome}, but current OPENCODEX_HOME=${currentOpenCodexHome()}. ` +
+        "Run the service command from the same OpenCodex home so service state and secrets match.",
+    );
+  }
+}
+
 function plistString(value: string): string {
   return value
     .replace(/&/g, "&")
@@ -44,12 +136,45 @@ function plistString(value: string): string {
     .replace(/'/g, "'");
 }
 
+function isLoopbackHostname(hostname: string | undefined): boolean {
+  const normalized = (hostname ?? "127.0.0.1").trim().toLowerCase();
+  return normalized === "" || normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1" || normalized === "[::1]";
+}
+
+export function assertServiceAuthEnvironment(): void {
+  const config = loadConfig();
+  if (isLoopbackHostname(config.hostname)) return;
+  if (process.env.OPENCODEX_API_AUTH_TOKEN?.trim()) return;
+  throw new Error(
+    "OPENCODEX_API_AUTH_TOKEN is required before installing a service for non-loopback hostname. " +
+      "Set it in the same shell, then rerun `ocx service install`.",
+  );
+}
+
+function writeServiceApiTokenFile(): string | null {
+  const token = process.env.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (!token) return null;
+  const path = serviceApiTokenFilePath();
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${token}\n`, { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+  return path;
+}
+
 export function buildPlist(): string {
   const { bun, cli } = cliEntry();
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = process.env.CODEX_HOME?.trim();
-  const codexHomeXml = codexHome ? `    <key>CODEX_HOME</key><string>${plistString(codexHome)}</string>` : "";
+  const opencodexHome = process.env.OPENCODEX_HOME?.trim();
+  const envLines = [
+    `    <key>OCX_SERVICE</key><string>1</string>`,
+    `    <key>PATH</key><string>${plistString(path)}</string>`,
+    codexHome ? `    <key>CODEX_HOME</key><string>${plistString(codexHome)}</string>` : null,
+    opencodexHome ? `    <key>OPENCODEX_HOME</key><string>${plistString(opencodexHome)}</string>` : null,
+  ].filter((line): line is string => Boolean(line)).join("\n");
+  const command = buildServiceShellCommand(bun, cli);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -57,17 +182,16 @@ export function buildPlist(): string {
   <key>Label</key><string>${LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${plistString(bun)}</string>
-    <string>${plistString(cli)}</string>
-    <string>start</string>
+    <string>/bin/sh</string>
+    <string>-lc</string>
+    <string>${plistString(command)}</string>
   </array>
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
   <key>EnvironmentVariables</key>
   <dict>
-    <key>OCX_SERVICE</key><string>1</string>
-    <key>PATH</key><string>${plistString(path)}</string>
-${codexHomeXml ? `${codexHomeXml}\n` : ""}  </dict>
+${envLines}
+  </dict>
   <key>StandardOutPath</key><string>${plistString(log)}</string>
   <key>StandardErrorPath</key><string>${plistString(log)}</string>
 </dict>
@@ -75,6 +199,15 @@ ${codexHomeXml ? `${codexHomeXml}\n` : ""}  </dict>
 `;
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function buildServiceShellCommand(bun: string, cli: string): string {
+  const tokenFile = serviceApiTokenFilePath();
+  return `if [ -f ${shellQuote(tokenFile)} ]; then OPENCODEX_API_AUTH_TOKEN="$(cat ${shellQuote(tokenFile)})"; export OPENCODEX_API_AUTH_TOKEN; fi; exec ${shellQuote(bun)} ${shellQuote(cli)} start`;
+}
+
 function systemdQuote(value: string): string {
   return `"${value
     .replace(/\\/g, "\\\\")
@@ -112,7 +245,11 @@ function schtasks(args: string[]): string {
 }
 
 function windowsBatchValue(value: string): string {
-  return value.replace(/%/g, "%%").replace(/[\r\n]/g, "");
+  return value
+    .replace(/%/g, "%%")
+    .replace(/\^/g, "^^")
+    .replace(/"/g, "")
+    .replace(/[\r\n]/g, "");
 }
 
 function windowsBatchSet(name: string, value: string | undefined): string | null {
@@ -120,8 +257,18 @@ function windowsBatchSet(name: string, value: string | undefined): string | null
   return `set "${name}=${windowsBatchValue(value)}"`;
 }
 
-export function buildWindowsServiceScript(): string {
-  const { bun, cli } = cliEntry();
+function taskXmlString(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+export function buildWindowsServiceScript(entry = cliEntry()): string {
+  const { bun, cli } = entry;
+  const bunRuntime = durableBunRuntime();
   const path = process.env.PATH ?? "";
   const lines = [
     "@echo off",
@@ -129,9 +276,25 @@ export function buildWindowsServiceScript(): string {
     windowsBatchSet("OCX_SERVICE", "1"),
     windowsBatchSet("PATH", path),
     windowsBatchSet("CODEX_HOME", process.env.CODEX_HOME?.trim()),
+    windowsBatchSet("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim()),
+    windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath()),
+    windowsBatchSet("OCX_SERVICE_LOG", serviceLogPath()),
+    windowsBatchSet("OCX_BUN", bun),
+    windowsBatchSet("OCX_CLI", cli),
+    'if exist "%OCX_API_TOKEN_FILE%" (',
+    '  set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"',
+    ")",
     ":loop",
-    `"${bun}" "${cli}" start`,
+    '>>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] opencodex service wrapper start',
+    '>>"%OCX_SERVICE_LOG%" echo bun="%OCX_BUN%"',
+    `>>"%OCX_SERVICE_LOG%" echo bun_source="${bunRuntime.source}"`,
+    '>>"%OCX_SERVICE_LOG%" echo cli="%OCX_CLI%"',
+    '>>"%OCX_SERVICE_LOG%" echo opencodex_home="%OPENCODEX_HOME%"',
+    '>>"%OCX_SERVICE_LOG%" echo codex_home="%CODEX_HOME%"',
+    '>>"%OCX_SERVICE_LOG%" echo token_file="%OCX_API_TOKEN_FILE%"',
+    '"%OCX_BUN%" "%OCX_CLI%" start >>"%OCX_SERVICE_LOG%" 2>&1',
     "if %ERRORLEVEL% NEQ 0 (",
+    '  >>"%OCX_SERVICE_LOG%" echo [%DATE% %TIME%] child exited with code %ERRORLEVEL%; restarting in 5s',
     "  timeout /t 5 /nobreak >nul",
     "  goto loop",
     ")",
@@ -141,7 +304,52 @@ export function buildWindowsServiceScript(): string {
 }
 
 export function buildWindowsSchtasksCreateArgs(script = windowsServiceScriptPath()): string[] {
-  return ["/create", "/tn", TASK, "/tr", `"${script}"`, "/sc", "onlogon", "/rl", "highest", "/f"];
+  const xml = script === windowsServiceScriptPath() ? windowsTaskXmlPath() : `${script}.xml`;
+  return ["/create", "/tn", TASK, "/xml", xml, "/f"];
+}
+
+export function buildWindowsTaskXml(script = windowsServiceScriptPath()): string {
+  const escapedScript = taskXmlString(script);
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>OpenCodex proxy service wrapper</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${escapedScript}</Command>
+    </Exec>
+  </Actions>
+</Task>
+`;
 }
 
 // ── macOS (launchd) ──
@@ -149,10 +357,12 @@ function installLaunchd(): void {
   const dir = join(homedir(), "Library", "LaunchAgents");
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  writeServiceApiTokenFile();
   const p = plistPath();
   writeFileSync(p, buildPlist(), "utf8");
   try { sh(`launchctl unload "${p}" 2>/dev/null`); } catch { /* not loaded */ }
   sh(`launchctl load -w "${p}"`);
+  writeServiceInstallState();
 }
 function startLaunchd(): void { sh(`launchctl load -w "${plistPath()}"`); }
 function stopLaunchd(): void { try { sh(`launchctl unload "${plistPath()}"`); } catch { /* not loaded */ } }
@@ -166,10 +376,14 @@ function uninstallLaunchd(): void {
 // ── Windows (Task Scheduler) ──
 function installWindows(): void {
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  writeServiceApiTokenFile();
   const script = windowsServiceScriptPath();
   writeFileSync(script, buildWindowsServiceScript(), "utf8");
+  writeFileSync(windowsTaskXmlPath(), `\uFEFF${buildWindowsTaskXml(script)}`, "utf16le");
+  try { stopWindows(); } catch { /* not running */ }
   schtasks(buildWindowsSchtasksCreateArgs(script));
   schtasks(["/run", "/tn", TASK]);
+  writeServiceInstallState();
 }
 function startWindows(): void { schtasks(["/run", "/tn", TASK]); }
 function stopWindows(): void { try { schtasks(["/end", "/tn", TASK]); } catch { /* not running */ } }
@@ -177,6 +391,11 @@ function statusWindows(): string { try { return schtasks(["/query", "/tn", TASK]
 function uninstallWindows(): void {
   try { schtasks(["/delete", "/tn", TASK, "/f"]); } catch { /* absent */ }
   if (existsSync(windowsServiceScriptPath())) unlinkSync(windowsServiceScriptPath());
+  if (existsSync(windowsTaskXmlPath())) unlinkSync(windowsTaskXmlPath());
+}
+
+function serviceDiagnosticsSummary(): string {
+  return `logs: ${serviceLogPath()}`;
 }
 
 // ── Linux (systemd user unit) ──
@@ -193,10 +412,12 @@ export function buildUnit(): string {
   const log = logPath();
   const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   const codexHome = systemdEnvironmentAssignment("CODEX_HOME", process.env.CODEX_HOME?.trim());
+  const opencodexHome = systemdEnvironmentAssignment("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim());
   const envLines = [
     systemdEnvironmentAssignment("OCX_SERVICE", "1"),
     systemdEnvironmentAssignment("PATH", path),
     codexHome,
+    opencodexHome,
   ].filter((line): line is string => Boolean(line)).join("\n");
   return `[Unit]
 Description=OpenCodex Proxy Server
@@ -205,7 +426,7 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=${systemdQuote(bun)} ${systemdQuote(cli)} start
+ExecStart=${systemdQuote("/bin/sh")} -lc ${systemdQuote(buildServiceShellCommand(bun, cli))}
 Restart=on-failure
 RestartSec=5
 ${envLines}
@@ -218,16 +439,20 @@ WantedBy=default.target
 }
 
 function isSystemd(): boolean {
-  try { execSync("systemctl --version", { stdio: "pipe" }); return true; } catch { return false; }
+  try { execSync("systemctl --version", { stdio: "pipe" }); } catch { return false; }
+  try { execSync("systemctl --user show-environment", { stdio: "pipe" }); return true; } catch { return false; }
 }
 
 function installSystemd(): void {
   const dir = unitDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  writeServiceApiTokenFile();
   writeFileSync(unitPath(), buildUnit(), "utf8");
   sh("systemctl --user daemon-reload");
-  sh(`systemctl --user enable --now ${TASK}`);
+  sh(`systemctl --user enable ${TASK}`);
+  sh(`systemctl --user restart ${TASK}`);
+  writeServiceInstallState();
 }
 function startSystemd(): void { sh(`systemctl --user start ${TASK}`); }
 function stopSystemd(): void { try { sh(`systemctl --user stop ${TASK}`); } catch { /* not running */ } }
@@ -253,7 +478,7 @@ function platformOps(): ServiceOps | null {
       console.error("Docker detected. Run 'ocx start' directly instead of using the service manager.");
       process.exit(1);
     }
-    if (!isSystemd()) {
+    if (!isSystemd() && !existsSync(unitPath())) {
       console.error("systemd not found. Run 'ocx start' under your process supervisor.");
       process.exit(1);
     }
@@ -262,11 +487,35 @@ function platformOps(): ServiceOps | null {
   return null;
 }
 
+type TrackedProxyCleanupResult = "none" | "stale" | "stopped";
+
+function stopTrackedProxyIfRunning(): TrackedProxyCleanupResult {
+  const pid = readPid();
+  if (!pid) return "none";
+  if (!isProcessAlive(pid)) {
+    removePid(pid);
+    return "stale";
+  }
+  killProxy(pid);
+  removePid(pid);
+  return "stopped";
+}
+
+function stopTrackedProxyForServiceCommand(): TrackedProxyCleanupResult {
+  try {
+    return stopTrackedProxyIfRunning();
+  } catch (err) {
+    console.error(`⚠️  Failed to stop proxy: ${err instanceof Error ? err.message : String(err)}`);
+    return "none";
+  }
+}
+
 /**
  * If a service is installed, stop it so the process manager doesn't respawn after `ocx stop`.
  * Returns true if a service was found and stopped.
  */
 export function stopServiceIfInstalled(): boolean {
+  assertServiceEnvironmentMatchesInstall();
   if (process.platform === "darwin") {
     if (existsSync(plistPath())) {
       try { stopLaunchd(); return true; } catch { return false; }
@@ -288,6 +537,7 @@ export function stopServiceIfInstalled(): boolean {
  * manager.
  */
 export function uninstallServiceIfInstalled(): boolean {
+  assertServiceEnvironmentMatchesInstall();
   if (process.platform === "darwin") {
     if (existsSync(plistPath())) {
       try { uninstallLaunchd(); return true; } catch { return false; }
@@ -297,8 +547,10 @@ export function uninstallServiceIfInstalled(): boolean {
       const q = schtasks(["/query", "/tn", TASK]);
       if (q.includes(TASK)) { uninstallWindows(); return true; }
     } catch { /* task not found */ }
-  } else if (process.platform === "linux" && isSystemd() && existsSync(unitPath())) {
-    try { uninstallSystemd(); return true; } catch { return false; }
+  } else if (process.platform === "linux" && existsSync(unitPath())) {
+    try { uninstallSystemd(); return true; } catch {
+      try { unlinkSync(unitPath()); return true; } catch { return false; }
+    }
   }
   return false;
 }
@@ -309,21 +561,22 @@ export function isServiceInstalled(): boolean {
 }
 
 export function serviceStatusSummary(): string {
+  const diagnostics = serviceDiagnosticsSummary();
   if (process.platform === "darwin") {
-    if (!existsSync(plistPath())) return "not installed";
+    if (!existsSync(plistPath())) return `not installed (${diagnostics})`;
     const status = statusLaunchd();
-    return status ? "installed (launchd)" : "installed, not loaded";
+    return status ? `installed (launchd; ${diagnostics})` : `installed, not loaded (${diagnostics})`;
   }
   if (process.platform === "win32") {
     const status = statusWindows();
-    return status ? "installed (Task Scheduler)" : "not installed";
+    return status ? `installed (Task Scheduler; ${diagnostics})` : `not installed (${diagnostics})`;
   }
   if (process.platform === "linux") {
     if (existsSync("/.dockerenv")) return "unsupported in Docker";
     if (!isSystemd()) return "unsupported: systemd not found";
-    if (!existsSync(unitPath())) return "not installed";
+    if (!existsSync(unitPath())) return `not installed (${diagnostics})`;
     const status = statusSystemd();
-    return status ? "installed (systemd user)" : "installed, not running";
+    return status ? `installed (systemd user; ${diagnostics})` : `installed, not running (${diagnostics})`;
   }
   return `unsupported on ${process.platform}`;
 }
@@ -336,6 +589,8 @@ export function serviceCommand(sub?: string): void {
   }
   switch (sub) {
     case "install":
+      assertServiceEnvironmentMatchesInstall();
+      assertServiceAuthEnvironment();
       ops.install();
       console.log("✅ opencodex service installed + started (auto-starts on login, auto-restarts on crash).");
       if (process.platform === "linux") console.log("   For auto-start on boot: loginctl enable-linger $USER");
@@ -345,23 +600,33 @@ export function serviceCommand(sub?: string): void {
       console.log("✅ service started.");
       break;
     case "stop":
+      assertServiceEnvironmentMatchesInstall();
       ops.stop();
+      stopTrackedProxyForServiceCommand();
       restoreNativeCodex();
       console.log("✅ service stopped + native Codex restored.");
       break;
     case "status": {
       const s = ops.status();
       console.log(s ? `✅ running:\n${s}` : "❌ service not installed/running.");
+      console.log(`Diagnostics: ${serviceDiagnosticsSummary()}`);
       break;
     }
     case "uninstall":
     case "remove":
+      assertServiceEnvironmentMatchesInstall();
+      ops.stop();
+      stopTrackedProxyForServiceCommand();
       ops.uninstall();
       restoreNativeCodex();
+      for (const path of serviceStatePaths()) {
+        try { if (existsSync(path)) unlinkSync(path); } catch { /* best-effort */ }
+      }
+      try { if (existsSync(serviceApiTokenFilePath())) unlinkSync(serviceApiTokenFilePath()); } catch { /* best-effort */ }
       console.log("✅ service uninstalled + native Codex restored.");
       break;
     default:
-      console.error("Usage: ocx service <install|start|stop|status|uninstall>");
+      console.error("Usage: ocx service <install|start|stop|status|uninstall|remove>");
       process.exit(1);
   }
 }

package/src/types.ts

@@ -123,6 +123,20 @@ export function namespacedToolName(namespace: string | undefined, name: string):
   return namespace ? `${namespace}__${name}` : name;
 }
 
+export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
+  const wireName = namespacedToolName(tool.namespace, tool.name);
+  return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];
+}
+
+export function toolAllowedByChoice(tool: Pick<OcxTool, "namespace" | "name">, allowedTools: ReadonlySet<string>): boolean {
+  return toolChoiceAliases(tool).some(name => allowedTools.has(name));
+}
+
+export function resolveToolChoiceWireName(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined, name: string): string {
+  const match = tools?.find(tool => toolChoiceAliases(tool).includes(name));
+  return match ? namespacedToolName(match.namespace, match.name) : name;
+}
+
 /**
  * Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
  * id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
@@ -135,12 +149,23 @@ export function modelInList(list: string[] | undefined, modelId: string): boolea
   return colon > 0 && list.includes(modelId.slice(0, colon));
 }
 
+export type OcxToolChoice =
+  | "auto"
+  | "none"
+  | "required"
+  | { name: string }
+  | { allowedTools: string[]; mode: "auto" | "required" };
+
+export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is { allowedTools: string[]; mode: "auto" | "required" } {
+  return typeof value === "object" && value !== null && "allowedTools" in value;
+}
+
 export interface OcxRequestOptions {
   maxOutputTokens?: number;
   temperature?: number;
   topP?: number;
   stopSequences?: string[];
-  toolChoice?: "auto" | "none" | "required" | { name: string };
+  toolChoice?: OcxToolChoice;
   reasoning?: string;
   hideThinkingSummary?: boolean;
   serviceTier?: string;

package/src/update.ts

@@ -22,36 +22,43 @@ function currentVersion(): string {
   }
 }
 
+function updateTag(current: string): string {
+  const tagIndex = process.argv.indexOf("--tag");
+  if (tagIndex !== -1 && process.argv[tagIndex + 1]) return process.argv[tagIndex + 1];
+  return current.includes("-preview.") ? "preview" : "latest";
+}
+
 /** Latest published version from the registry (best-effort; null if npm isn't available). */
-function latestVersion(): string | null {
-  const r = spawnSync("npm", ["view", PKG, "version"], { encoding: "utf8", timeout: 12000, windowsHide: true });
+function latestVersion(tag: string): string | null {
+  const r = spawnSync("npm", ["view", `${PKG}@${tag}`, "version"], { encoding: "utf8", timeout: 12000, windowsHide: true });
   return r.status === 0 ? r.stdout.trim() : null;
 }
 
 /**
- * `ocx update` — self-update opencodex to the latest published version, using the same package
- * manager it was installed with (bun or npm global). A source checkout is told to `git pull` instead.
+ * `ocx update` fallback for source checkouts and Bun global installs. npm global installs are updated
+ * in the Node bin launcher before Bun starts, so Windows does not replace the running Bun binary.
  */
 export async function runUpdate(): Promise<void> {
   const installer = detectInstall();
   const current = currentVersion();
-  console.log(`opencodex v${current} (installed via ${installer})`);
+  const tag = updateTag(current);
+  console.log(`opencodex v${current} (installed via ${installer}, tag ${tag})`);
 
   if (installer === "source") {
     console.log("Running from a source checkout — update with:  git pull && bun install");
     return;
   }
 
-  const latest = latestVersion();
+  const latest = latestVersion(tag);
   if (latest && latest === current) {
-    console.log(`Already on the latest version (v${latest}).`);
+    console.log(`Already on the latest ${tag} version (v${latest}).`);
     return;
   }
 
   const bin = installer === "bun" ? "bun" : "npm";
   const cmdArgs = installer === "bun"
-    ? ["add", "-g", `${PKG}@latest`]
-    : ["install", "-g", `${PKG}@latest`];
+    ? ["add", "-g", `${PKG}@${tag}`]
+    : ["install", "-g", `${PKG}@${tag}`];
   console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);
 
   const r = spawnSync(bin, cmdArgs, { stdio: "inherit", timeout: 180000, windowsHide: true });