@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/cli/index.ts

@@ -43,6 +43,7 @@ import {
   saveConfig,
 } from "../config";
 import {
+  isLikelyOcxProcess,
   readPid,
   readPidFileValue,
   readRuntimePort,
@@ -65,6 +66,7 @@ import {
 import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
 import { endpointsToProve, everyEndpointProvenDown, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
+import { parseStartOptions, StartArgsError } from "./start-args";
 
 import {
   discoverStableProxyForRestart,
@@ -76,9 +78,11 @@ import {
 } from "./tray-proxy";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
-import { dispatchCommand , decideStartWithLiveOwner } from "./dispatch";
+import { SpendLedgerOwnerError } from "../lib/spend-ledger-owner";
+import { redactUrlForLog } from "../lib/redact";
+import { dispatchCommand, decideBusyPreferredPort, decideStartWithLiveOwner } from "./dispatch";
 import { AuxiliaryListenerBindError, findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
-import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import { findLiveProxy, probeHostname, probePortOwner, START_OWNERSHIP_LIVENESS, type LiveProxy } from "../server/proxy-liveness";
 import { createReadinessGate } from "../server/readiness";
 import { isApiAuthRequired } from "../server/auth-cors";
 import { runReady, type ReadyArgs } from "./ready";
@@ -169,21 +173,13 @@ 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;
-  if (args.length !== 3 || args[1] !== "--port") {
-    console.error("Usage: ocx start [--port <port>]");
-    process.exit(1);
-  }
-  const portIdx = args.indexOf("--port");
-  if (portIdx === -1) return undefined;
-  const value = args[portIdx + 1];
-  const port = value && /^\d+$/.test(value) ? Number(value) : NaN;
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    console.error("Invalid port number");
+function parseStartCliOptions(): ReturnType<typeof parseStartOptions> {
+  try {
+    return parseStartOptions(args.slice(1));
+  } catch (error) {
+    console.error(error instanceof StartArgsError ? error.message : String(error));
     process.exit(1);
   }
-  return port;
 }
 
 async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
@@ -272,8 +268,41 @@ async function chooseListenPort(
       // ever a config collision.
       ...(reservedLoopbackPort !== undefined ? { reservedPort: reservedLoopbackPort } : {}),
     });
-    if (preferred > 0 && selected !== preferred) {
-      console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
+    if (selected !== preferred) {
+      // The hop used to be automatic, and that is how a bare `start` beside a healthy
+      // proxy produced a second one (#5004): nothing on this path ever asked who held the
+      // preferred port. Ask the holder itself — not this home's pid/runtime bookkeeping,
+      // which is exactly what was wrong when the duplicate happened — and give the
+      // question a budget that cannot mistake one lost probe for an empty port.
+      const holder = preferred > 0 && !hardPin
+        ? await probePortOwner(preferred, { hostname: config.hostname }, START_OWNERSHIP_LIVENESS)
+        : null;
+      const decision = decideBusyPreferredPort({
+        preferredPort: preferred,
+        selectedPort: selected,
+        hardPin,
+        holderIsOpencodex: holder !== null,
+        ocxService: process.env.OCX_SERVICE,
+      });
+      if (decision === "service-stay-out") {
+        // Same contract as the pre-bind owner check: the wrapper's retry loop terminates
+        // on a zero exit, and the port it was asked to serve is already served.
+        console.log(`Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}); service wrapper staying out of the way.`);
+        process.exit(0);
+      }
+      if (decision === "refuse-live-proxy") {
+        console.error(`⚠️  Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}). Use 'ocx stop' first.`);
+        process.exit(1);
+      }
+      if (decision === "refuse-unidentified-holder") {
+        console.error(`❌ Port ${preferred} is busy and its holder did not identify as opencodex.`);
+        console.error("   Starting on another port would leave Codex pointed at a proxy you did not ask for.");
+        console.error("   Stop whatever holds that port, or start on a free one with 'ocx start --port <port>'.");
+        process.exit(1);
+      }
+      if (preferred > 0) {
+        console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
+      }
     }
     if (shouldPersistSelectedPort(config.port, selected, preferred, options)) {
       config.port = selected;
@@ -296,7 +325,12 @@ async function findProxyOwnerBeforeJournalRecovery(
   const pidSnapshot = readPidFileValue();
   const hasRuntimeOwner = readRuntimePort() !== null;
   const shouldProbe = pidSnapshot !== null || hasRuntimeOwner || options.probeConfiguredPort === true;
-  const live = shouldProbe ? await findLiveProxy() : null;
+  // A negative answer here is acted on twice over: the caller walks past a proxy it was
+  // supposed to find, and the lines below delete this home's pid record and reconcile the
+  // journal. One 750ms probe is not enough evidence for either (#5004) — a transport
+  // failure is indistinguishable from an empty port, and the reported Windows duplicate
+  // came from exactly that answer on a proxy the previous command had just found healthy.
+  const live = shouldProbe ? await findLiveProxy(START_OWNERSHIP_LIVENESS) : null;
   if (live) return { live, pidSnapshot };
 
   // The probe established that the snapshotted owner is stale. Compare before
@@ -328,7 +362,26 @@ async function handleStart(options: { block?: boolean } = {}) {
   // 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();
+  const startOpts = parseStartCliOptions();
+  if (startOpts.socks5 !== undefined || startOpts.socks5Off) {
+    const proxyConfig = loadConfig();
+    if (startOpts.socks5Off) {
+      if (proxyConfig.proxy && !/^socks5h?:\/\//i.test(proxyConfig.proxy.trim())) {
+        console.error("Cannot use --socks5-off: config.proxy is not a SOCKS5 URL; it was left unchanged.");
+        process.exit(1);
+      }
+      if (proxyConfig.proxy) {
+        delete proxyConfig.proxy;
+        saveConfig(proxyConfig);
+        console.log("Cleared config.proxy (outbound SOCKS5 proxy off).");
+      }
+    } else {
+      proxyConfig.proxy = startOpts.socks5!;
+      saveConfig(proxyConfig);
+      console.log(`Outbound SOCKS5: ${redactUrlForLog(startOpts.socks5!)} (saved to config.proxy)`);
+    }
+  }
+  const requestedPort = startOpts.port;
   // Always probe the configured port, even when both state files are absent. A
   // fallback-port sibling overwrites the pid/runtime records when it starts and
   // removes them on its own shutdown, so their absence proves nothing about the
@@ -366,8 +419,8 @@ async function handleStart(options: { block?: boolean } = {}) {
     // to bake the service (observed: a probe on 10198 left the service pinned there).
     siblingStart = true;
     console.warn(
-      `Proxy already running on port ${owner.live.port}; starting a second instance on requested port ${requestedPort}. `
-      + `The new instance takes over this home's pid/runtime records and Codex config while it runs.`,
+      `Proxy already running on port ${owner.live.port}; requested a second instance on port ${requestedPort}. `
+      + `Startup continues only for an independent OPENCODEX_HOME; one state directory has one spend-ledger writer.`,
     );
   }
 
@@ -411,6 +464,10 @@ async function handleStart(options: { block?: boolean } = {}) {
       scheduleCatalogPrewarm();
       break;
     } catch (err) {
+      if (err instanceof SpendLedgerOwnerError) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+      }
       if (err instanceof AuxiliaryListenerBindError || !isAddrInUse(err) || attempt >= 2) throw err;
       if (requestedPort !== undefined) {
         console.log(`⚠️  Port ${port} was taken while starting; waiting to retry the same port...`);
@@ -927,8 +984,24 @@ async function handleStop() {
   // `inheritedTeardowns` is the inverse case: PREVIOUS stops that left obligations
   // unfinished. Snapshot them BEFORE this run claims anything, so this run's own receipt
   // is never mistaken for one it inherited.
+  //
+  // Ownership is decided by IDENTITY, not by bare liveness. A receipt records a number, and
+  // the OS reuses numbers: once the owner exits, an unrelated process can be handed its PID,
+  // and `isProcessAlive` alone then answers "that stop is still running" for as long as the
+  // new process lives. The receipt is filtered out, so no run ever recovers it, quarantines
+  // it or even mentions it — while both updater gates keep seeing an outstanding obligation
+  // and refuse. That is the permanent fail-closed reported in #4897: no proxy running, a
+  // dead owner, and `ocx update` aborting on `teardown-outstanding` every time.
+  //
+  // Requiring the live PID to be an opencodex process is the narrowing that costs the safety
+  // intent nothing: a stop that really is in flight is still left strictly alone, because its
+  // process is one of ours. Recognizing the receipt as abandoned only admits it to the
+  // recovery loop below, which still has to prove the recorded endpoint is down before
+  // anything is restored.
+  const teardownOwnerStillRunning = (ownerPid: number): boolean =>
+    isProcessAlive(ownerPid) && isLikelyOcxProcess(ownerPid);
   const inheritedTeardowns = listPendingTeardowns()
-    .filter(read => isPendingTeardownAbandoned(read, isProcessAlive));
+    .filter(read => isPendingTeardownAbandoned(read, teardownOwnerStillRunning));
   let teardownNonce: string | undefined;
   const claimTeardown = (endpoint: { hostname: string; port: number }, endpointSource: "exact" | "guessed") => {
     if (teardownNonce) return;

package/src/cli/models-runtime.ts

@@ -4,6 +4,7 @@ import {
   printData,
   rejectArgs,
   runCliAction,
+  RuntimeApiError,
   runtimeRequest,
   summaryLines,
   takeBooleanOption,
@@ -165,6 +166,22 @@ async function priceRequest(write: boolean, argv: string[], deps: RuntimeApiDeps
     [auto ? `${selector}: automatic pricing restored.` : `${selector}: manual pricing saved.`]);
 }
 
+/**
+ * True for the management handler's own unknown-id 404, and only that.
+ *
+ * Two different listeners answer 404 on this route. `src/server/management/model-routes.ts`
+ * means "no custom model with that id"; a listener that does not route the request at all
+ * reports `{error, method, path}` (src/client/machine-listener.ts), and runtime-api.ts already
+ * renders that shape as a routing statement. Narrowing on the absence of `method`/`path` keeps
+ * this rewrite from relabelling a not-served-here 404 as a missing record — the exact confusion
+ * #4662 was reported as.
+ */
+function unknownCustomModelId(body: unknown): boolean {
+  if (!body || typeof body !== "object") return false;
+  const record = body as Record<string, unknown>;
+  return record.method === undefined && record.path === undefined;
+}
+
 async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const id = args.shift()?.trim();
@@ -204,10 +221,22 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }
   if (defaultEffortRaw !== undefined) patch.defaultReasoningEffort = defaultEffortRaw === "-" ? null : defaultEffortRaw;
   if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);
-  const result = await runtimeRequest(`/api/custom-models/${encodeURIComponent(id)}`, {
-    method: "PUT",
-    body: JSON.stringify(patch),
-  }, deps);
+  let result: unknown;
+  try {
+    result = await runtimeRequest(`/api/custom-models/${encodeURIComponent(id)}`, {
+      method: "PUT",
+      body: JSON.stringify(patch),
+    }, deps);
+  } catch (error) {
+    if (error instanceof RuntimeApiError && error.status === 404 && unknownCustomModelId(error.body)) {
+      throw new RuntimeApiError(
+        `No custom model has id ${id}. Edits address the custom-model id, not the provider/model slug; list the ids with: ocx models list-custom`,
+        404,
+        error.body,
+      );
+    }
+    throw error;
+  }
   printData(result, wantsJson, [`Updated custom model ${id}.`]);
 }
 

package/src/cli/opencode.ts

@@ -41,7 +41,7 @@ import type {
 } from "../clients/config-export";
 import { filterCatalogVisibleModels, visibleNativeSlugs } from "../codex/catalog";
 import { commandInvocation } from "../lib/win-exec";
-import { configuredAdminToken } from "../lib/admin-secrets";
+import { configuredAdminToken, opencodeCatalogToken } from "../lib/admin-secrets";
 import { localManagementOrigin } from "../lib/local-destinations";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
@@ -684,7 +684,7 @@ export async function cmdOpencode(args: string[]): Promise<number> {
   try {
     const managementToken = configuredAdminToken();
     if (!managementToken) throw new Error("No local admin token is available; check the running proxy's home.");
-    proxyModels = await fetchOpencodeProxyModels(live, managementToken, {
+    proxyModels = await fetchOpencodeProxyModels(live, opencodeCatalogToken(managementToken), {
       managementOrigin: localManagementOrigin({ ...startupConfig, hostname: live.hostname }, live.port),
     });
   } catch (error) {

package/src/cli/provider.ts

@@ -139,7 +139,7 @@ function handleList(args: string[]): void {
 // provider add
 // ---------------------------------------------------------------------------
 
-const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
+const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
 
 async function handleAdd(args: string[]): Promise<void> {
   const name = args[0];
@@ -164,6 +164,7 @@ async function handleAdd(args: string[]): Promise<void> {
   const adapter = consumeFlagValue(restArgs, "--adapter");
   const baseUrl = consumeFlagValue(restArgs, "--base-url");
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
+  const googleToolSchemaPolicy = consumeFlagValue(restArgs, "--google-tool-schema-policy");
   const textOnly = consumeFlag(restArgs, "--text-only");
   const capabilityModel = consumeFlagValue(restArgs, "--model");
   rejectUnknownArgs(restArgs, ADD_USAGE);
@@ -228,6 +229,17 @@ async function handleAdd(args: string[]): Promise<void> {
     }
     provConfig.apiKeyTransport = apiKeyTransport;
   }
+  if (googleToolSchemaPolicy !== undefined) {
+    if (googleToolSchemaPolicy !== "compatible" && googleToolSchemaPolicy !== "reject-lossy") {
+      console.error('Error: --google-tool-schema-policy must be "compatible" or "reject-lossy".');
+      process.exit(1);
+    }
+    if (provConfig.adapter !== "google") {
+      console.error("Error: --google-tool-schema-policy requires the google adapter.");
+      process.exit(1);
+    }
+    provConfig.googleToolSchemaPolicy = googleToolSchemaPolicy;
+  }
 
   const existingProvider = config.providers[name];
   if (existingProvider?.modelCapabilities !== undefined && provConfig.modelCapabilities === undefined) {

package/src/cli/registry.ts

@@ -20,7 +20,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx setup",
     summary: "Interactive setup for providers and Codex config injection (alias of init).",
   },
-  { name: "start", usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
+  {
+    name: "start",
+    usage: "ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]",
+    summary: "Start the proxy server and sync models to Codex.",
+    details: [
+      "--socks5 [host:port]  Route outbound provider traffic through SOCKS5 (default 127.0.0.1:10808). Saved as config.proxy.",
+      "--socks5-off          Clear a saved SOCKS5 outbound proxy from config.proxy.",
+    ],
+  },
   { name: "stop", usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
   {
     name: "restore",
@@ -390,6 +398,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     details: [
       "system update manages OpenCodex itself.",
       "ocx system codex-cli-update check [--json]",
+      "ocx system codex-cli-update attest [--json]",
+      "ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]",
       "The Codex CLI inspection command makes no package-registry request, does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state.",
     ],
   },

package/src/cli/runtime-api.ts

@@ -42,10 +42,39 @@ export class RuntimeApiError extends Error {
   }
 }
 
+/**
+ * Refusal for a management request that resolved to a connected-client machine listener.
+ *
+ * A connected client runs `src/client/machine-listener.ts`, which binds the SAME address the
+ * standalone proxy would (`port ?? config.port ?? 10100`) and answers `/healthz` as opencodex.
+ * Liveness therefore finds it — correctly, it is our process — but it serves only
+ * `/api/machine/*` and returns a JSON 404 for every other `/api/*` path. Before this refusal
+ * every management-backed subcommand on such a machine died on that opaque 404:
+ * `{"error":"not_found","method":"PUT","path":"/api/custom-models/<id>"}`, one character away
+ * from the real handler's unknown-id `{"error":"not found"}` and indistinguishable from it
+ * (#4662). The role was already on the wire; only the parser was throwing it away.
+ *
+ * 503 rather than 404: the management plane is unavailable here, the resource is not missing,
+ * and `runCliAction` maps 404 to exit 4 ("no such thing") — the wrong answer to give a script.
+ */
+function clientRoleManagementRefusal(port: number): string {
+  return [
+    `The opencodex listener on port ${port} is running in the client role. It serves only the machine routes (/api/machine/*), so this machine has no management API to call.`,
+    "Custom-model edits and other management changes are made on the hub this machine is connected to: run the command there, or use the hub dashboard (the dashboard on this machine relays to it when the connection uses the relay transport).",
+    "To change this machine's own configuration instead: edit customModels in config.json, then run: ocx sync",
+  ].join("\n");
+}
+
 export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string> {
   if (deps.baseUrl) return deps.baseUrl.replace(/\/$/, "");
   const live = await (deps.findLiveProxy ?? findLiveProxy)();
   if (!live) throw new RuntimeApiError("Proxy is not running. Start it with: ocx start", 503, null);
+  // The role comes from the same identity-checked /healthz body liveness already parsed, so
+  // this costs no extra request. Only the client role is refused: an absent role is a
+  // standalone or hub proxy (or a legacy body that predates the field), and both serve /api/*.
+  if (live.role === "client") {
+    throw new RuntimeApiError(clientRoleManagementRefusal(live.port), 503, null);
+  }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
@@ -62,11 +91,26 @@ function stringField(record: Record<string, unknown>, key: string): string | und
  * is unavailable). Both were dropped here, so a fenced management plane was
  * indistinguishable from a generic failure and an operator had no way to tell a port
  * collision from an ACL refusal from a stopped proxy (#2698).
+ *
+ * A 404 body that carries both `method` and `path` is a different statement again: some
+ * opencodex listener answered, and it does not route that request at all. Only the
+ * connected-client machine listener emits that shape today (`json404` in
+ * src/client/machine-listener.ts), and printing its bare `not_found` token read as though the
+ * resource were missing — a real handler's unknown-id 404 says `not found`, one space apart
+ * (#4662). Name the route instead, so any listener that does not serve a path stays legible
+ * even if another one starts answering this way.
  */
 function responseMessage(body: unknown, status: number): string {
   if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400);
   if (!body || typeof body !== "object") return `Management request failed (${status})`;
   const record = body as Record<string, unknown>;
+  if (status === 404) {
+    const method = stringField(record, "method");
+    const path = stringField(record, "path");
+    if (method && path) {
+      return `This opencodex listener does not serve ${method.slice(0, 16)} ${path.slice(0, 200)}, so the request was refused before any handler ran (it is not a missing record). Check that the command is pointed at a proxy that serves the management API.`;
+    }
+  }
   let primary: string | undefined;
   for (const key of ["error", "message", "detail"]) {
     primary = stringField(record, key);

package/src/cli/start-args.ts

@@ -0,0 +1,94 @@
+export const START_USAGE = "Usage: ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]";
+export const START_USAGE_LINE = "ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]";
+export const DEFAULT_SOCKS5_PROXY = "socks5://127.0.0.1:10808";
+
+export class StartArgsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StartArgsError";
+  }
+}
+
+export type StartOptions = {
+  port?: number;
+  /** SOCKS5 URL to persist. */
+  socks5?: string;
+  socks5Off?: boolean;
+};
+
+export function isSocksProxyUrl(proxy: string): boolean {
+  return /^socks5h?:\/\//i.test(proxy.trim());
+}
+
+export function normalizeSocks5(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return DEFAULT_SOCKS5_PROXY;
+  if (isSocksProxyUrl(trimmed)) {
+    try {
+      const parsed = new URL(trimmed);
+      const port = Number(parsed.port);
+      if (!parsed.hostname || !parsed.port || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error("invalid host or port");
+      }
+      return trimmed;
+    } catch {
+      throw new StartArgsError("Invalid SOCKS5 address; expected socks5://host:port");
+    }
+  }
+  if (/^socks4a?:\/\//i.test(trimmed)) {
+    throw new StartArgsError("Only SOCKS5 proxy URLs are supported");
+  }
+  if (/^https?:\/\//i.test(trimmed)) {
+    throw new StartArgsError("SOCKS5 proxy must be socks5://host:port, not an HTTP URL");
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const port = Number(trimmed);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      throw new StartArgsError("Invalid SOCKS5 port number");
+    }
+    return `socks5://127.0.0.1:${port}`;
+  }
+  const hostPort = /^(\[[^\]]+\]|[^:]+):(\d+)$/.exec(trimmed);
+  if (hostPort) {
+    const port = Number(hostPort[2]);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      throw new StartArgsError("Invalid SOCKS5 port number");
+    }
+    return `socks5://${trimmed}`;
+  }
+  throw new StartArgsError("Invalid SOCKS5 address; expected socks5://host:port");
+}
+
+export function parseStartOptions(argv: string[]): StartOptions {
+  const options: StartOptions = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--port") {
+      const value = argv[++i];
+      const port = value && /^\d+$/.test(value) ? Number(value) : NaN;
+      if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new StartArgsError("Invalid port number");
+      }
+      options.port = port;
+      continue;
+    }
+    if (arg === "--socks5") {
+      if (options.socks5Off) throw new StartArgsError("--socks5 and --socks5-off cannot be used together");
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-")) {
+        options.socks5 = normalizeSocks5(next);
+        i += 1;
+      } else {
+        options.socks5 = DEFAULT_SOCKS5_PROXY;
+      }
+      continue;
+    }
+    if (arg === "--socks5-off") {
+      if (options.socks5 !== undefined) throw new StartArgsError("--socks5 and --socks5-off cannot be used together");
+      options.socks5Off = true;
+      continue;
+    }
+    throw new StartArgsError(START_USAGE);
+  }
+  return options;
+}

package/src/cli/system-command.ts

@@ -21,6 +21,8 @@ const USAGE = `Usage:
   ocx system codex-app-server [--json]
   ocx system codex-restart --yes [--json]
   ocx system codex-cli-update check [--json]
+  ocx system codex-cli-update attest [--json]
+  ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]
   ocx system update check [--channel <latest|preview>] [--json]
   ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]
   ocx system update status <job-id> [--json]

package/src/client/machine-api.ts

@@ -23,7 +23,7 @@ export interface MachineStatusV1 {
 export interface MachineApiDeps {
   sync: typeof syncConnectedClient;
   disconnect: typeof disconnectClient;
-  scheduleStandaloneRecycle: () => void;
+  scheduleStandaloneRecycle: (disconnectedTokenFingerprint: string) => void;
   hubReachability?: () => HubReachability;
   setHubReachability?: (value: HubReachability) => void;
 }
@@ -74,10 +74,11 @@ export async function handleMachineApi(
   injected: MachineApiDeps = defaultDeps,
 ): Promise<Response | null> {
   const deps = { ...defaultDeps, ...injected };
-  if (url.pathname === "/api/machine/status" && req.method === "GET") {
+  const readMethod = req.method === "GET" || req.method === "HEAD";
+  if (url.pathname === "/api/machine/status" && readMethod) {
     return Response.json(statusPayload(req, state, deps), { headers: { "Cache-Control": "no-store" } });
   }
-  if (url.pathname === "/api/machine/clients" && req.method === "GET") {
+  if (url.pathname === "/api/machine/clients" && readMethod) {
     return Response.json({
       selectedClients: [...state.selectedClients],
       journalOwner: journalOwner(),
@@ -103,7 +104,7 @@ export async function handleMachineApi(
       return Response.json({ success: false, error: message }, { status: 502 });
     }
   }
-  if (url.pathname === "/api/machine/shim" && req.method === "GET") {
+  if (url.pathname === "/api/machine/shim" && readMethod) {
     return Response.json(diagnoseCodexShim(), { headers: { "Cache-Control": "no-store" } });
   }
   if (url.pathname === "/api/machine/shim" && req.method === "POST") {
@@ -129,7 +130,7 @@ export async function handleMachineApi(
     }
     try {
       const result = await deps.disconnect(input.keepCatalog === undefined ? {} : { keepCatalog: input.keepCatalog });
-      deps.scheduleStandaloneRecycle();
+      deps.scheduleStandaloneRecycle(state.tokenFingerprint);
       return Response.json({ success: true, ...result }, { status: 202 });
     } catch (error) {
       return Response.json({ success: false, error: error instanceof Error ? error.message : "disconnect failed" }, { status: 409 });

package/src/client/machine-listener.ts

@@ -46,9 +46,14 @@ export function machineRouteAllowed(url: URL, req: Request, relayEnabled: boolea
   if (req.headers.get("upgrade")) return false;
   const path = url.pathname;
   if (req.method === "GET" && (path === "/healthz" || path === "/readyz" || path === "/" || path === "/opencodex-session")) return true;
-  if (req.method === "GET" && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
+  if ((req.method === "GET" || req.method === "HEAD") && (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim")) return true;
   if (req.method === "POST" && (path === "/api/machine/sync" || path === "/api/machine/shim" || path === "/api/machine/disconnect")) return true;
   if (relayEnabled && path.startsWith("/api/machine/hub-relay/")) return true;
+  // Known machine endpoints are admitted for every method so an unsupported
+  // method reaches the authenticated method restriction (403) instead of a
+  // bare 404 that hides the endpoint entirely.
+  if (path === "/api/machine/status" || path === "/api/machine/clients" || path === "/api/machine/shim"
+    || path === "/api/machine/sync" || path === "/api/machine/disconnect") return true;
   if (req.method !== "GET" || path.startsWith("/api/") || path.startsWith("/v1/")) return false;
   return GUI_SPA_PATHS.has(path)
     || path.startsWith("/integrations/")
@@ -70,8 +75,8 @@ export function startMachineListener(
   const machineApiDeps: MachineApiDeps = {
     sync: deps.machineApi?.sync ?? syncConnectedClient,
     disconnect: deps.machineApi?.disconnect ?? disconnectClient,
-    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (() => {
-      void import("./runtime").then(module => module.scheduleStandaloneRecycle());
+    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (tokenFingerprint => {
+      void import("./runtime").then(module => module.scheduleStandaloneRecycle(tokenFingerprint));
     }),
     hubReachability: deps.machineApi?.hubReachability ?? (() => hubReachability),
     setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),
@@ -111,6 +116,14 @@ export function startMachineListener(
         if (managementPrincipal(req, managementAuth, config) !== "gui-session") {
           return Response.json({ error: "opencodex machine GUI session required" }, { status: 401 });
         }
+        // A loopback dashboard session proves possession, not user presence: any local
+        // process can fetch the dashboard bootstrap and replay its token and CSRF value.
+        // Keep the connected listener useful for status/diagnostics, but never let that
+        // credentialless bootstrap authorize durable machine changes. Those operations
+        // remain available through the explicit CLI commands.
+        if (req.method !== "GET" && req.method !== "HEAD") {
+          return Response.json({ error: "opencodex machine changes require the local CLI" }, { status: 403 });
+        }
         return await handleMachineApi(req, url, connection, machineApiDeps) ?? json404(req);
       }
 

package/src/client/runtime.ts

@@ -4,6 +4,7 @@ import { loadConfig } from "../config";
 import { removePid, removeRuntimePort, writePid, writeRuntimePort } from "../config/process-state";
 import { installCrashGuards } from "../lib/crash-guard";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
+import { loadServiceTokenFromFile, serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { findAvailablePort } from "../server/ports";
 import { startMachineListener } from "./machine-listener";
 import { readClientConnectionState } from "./state";
@@ -17,7 +18,30 @@ function cleanup(): void {
   removeRuntimePort(process.pid);
 }
 
-export function scheduleStandaloneRecycle(): void {
+export function standaloneRecycleEnv(
+  env: NodeJS.ProcessEnv,
+  disconnectedTokenFingerprint: string,
+): NodeJS.ProcessEnv {
+  const childEnv = { ...env };
+  const admissionToken = childEnv.OPENCODEX_API_AUTH_TOKEN?.trim();
+  if (admissionToken && serviceApiTokenFingerprint(admissionToken) !== disconnectedTokenFingerprint) {
+    // A surviving env token shadows OCX_API_TOKEN_FILE entirely, so nothing below can
+    // reintroduce the disconnected token.
+    return childEnv;
+  }
+  if (admissionToken) delete childEnv.OPENCODEX_API_AUTH_TOKEN;
+  // The respawned `ocx start` loads OCX_API_TOKEN_FILE into OPENCODEX_API_AUTH_TOKEN when the
+  // env token is absent, so vet the file by content: drop the pointer when it is unreadable or
+  // holds the disconnected token, keep it when it holds a different operator credential.
+  if (!childEnv.OCX_API_TOKEN_FILE?.trim()) return childEnv;
+  const fileToken = loadServiceTokenFromFile(childEnv);
+  if (fileToken === null || serviceApiTokenFingerprint(fileToken) === disconnectedTokenFingerprint) {
+    delete childEnv.OCX_API_TOKEN_FILE;
+  }
+  return childEnv;
+}
+
+export function scheduleStandaloneRecycle(disconnectedTokenFingerprint: string): void {
   if (recycleScheduled) return;
   recycleScheduled = true;
   const timer = setTimeout(() => {
@@ -46,7 +70,7 @@ export function scheduleStandaloneRecycle(): void {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: { ...process.env },
+        env: standaloneRecycleEnv(process.env, disconnectedTokenFingerprint),
       });
       child.unref();
     }

package/src/clients/config-export/constants.ts

@@ -37,9 +37,8 @@ export const OPENCLAW_API_KEY_ENV_REF = `\${${OPENCLAW_API_KEY_ENV}}`;
 export const LOOPBACK_API_KEY_PLACEHOLDER = "opencodex-loopback";
 
 /**
- * Gajae's `apiKeyEnv` is env-name-only and fail-closed. Its sibling `apiKey`
- * falls back to treating the literal text as the token when the variable is
- * unset, which would silently ship a bogus credential — so we never emit it.
+ * Legacy name retained for existing consumers. Gajae exports now use the
+ * non-secret loopback placeholder and do not emit an environment reference.
  */
 export const GAJAE_API_KEY_ENV = "OPENCODEX_GAJAE_API_KEY";