@bitkyc08/opencodex 2.58.0 → 2.59.0

package/src/cli/doctor.ts

@@ -13,7 +13,7 @@ import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics } from "../config";
 import { readPid } from "../config/process-state";
 import { probeUncleanExitState } from "./status";
-import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { BUN_RUNTIME_SOURCES } from "../lib/bun-runtime";
 import type { BunRuntimeSource } from "../lib/bun-runtime";
 import { maskAccountId } from "../lib/privacy";
@@ -26,7 +26,11 @@ import { withNativeMainSharedClaim } from "../codex/native-main-claim";
 import { probeNativeProfileRecoveryState, resolveNativeProfileContext } from "../codex/native-profile-store";
 import { NativeProfileError } from "../codex/native-profile-types";
 import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHomeDirImpl, isWslRuntime, listWslWindowsCodexHomes, wslAutomountRoot, type CodexHomeDeps } from "../codex/home";
-import { scanCodexAgentRolesWithTomlModelFallback } from "../codex/subagent-model-fallback";
+import {
+  scanCodexAgentRolesWithTomlModelFallback,
+  scanOpencodexDerivedCodexAgentRolesWithoutModelPin,
+} from "../codex/subagent-model-fallback";
+import { readCatalog, readCodexCatalogPath, readConfiguredDefaultModel } from "../codex/catalog/parsing";
 import { diagnoseCodexShim, findCodexOnPath, isWindowsInteropDir, type CodexShimDiagnostic } from "../codex/shim";
 import { providerTableString, rootTomlString } from "../codex/injected-marker";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
@@ -1040,6 +1044,161 @@ export function chatgptPublicEndpointHint(
   return "ChatGPT-family requests use the public ChatGPT endpoint through this proxy, in both Pool and Direct modes. Eligible streaming turns dial the ChatGPT websocket transport (the same responses_websockets lane Codex CLI defaults to) and fall back to SSE over HTTP when a turn is not eligible - an unsupported Bun runtime, an oversized create frame, or a proxy route that cannot carry the socket - and local provider pacing can hold a request before it is dispatched at all. This hint classifies configuration only and measures nothing, so upstream queueing is one possible contributor to a slow first output: compare actual transport, pacing, network, and provider observations before concluding. service_tier=priority is a request preference: this backend can echo service_tier \"default\" even on turns it scheduled as priority (#2558), so the echoed response tier in request logs stays an observation with confirmation \"assumed\" and cannot confirm or deny the granted tier.";
 }
 
+/**
+ * Bound for the doctor-side `/v1/models` read (#4646). A diagnostic must not hang on a proxy
+ * that is listening but wedged mid-gather; when the read does not land in time the on-disk
+ * catalog answers instead, and if that is unreadable too the verdict is "could not determine"
+ * rather than a guess.
+ */
+const EXPOSED_MODELS_TIMEOUT_MS = 8000;
+
+/**
+ * Whether Codex's pinned default model is one this proxy exposes (#4646).
+ *
+ * Three states, not two. Reporting "not exposed" when the exposed set could not be read would
+ * be a fabricated failure on exactly the installs least able to check it (proxy down, catalog
+ * never synced), so an unreadable set is its own verdict.
+ */
+export type DefaultModelExposureStatus = "not_configured" | "exposed" | "not_exposed" | "undeterminable";
+
+export interface DefaultModelExposure {
+  status: DefaultModelExposureStatus;
+  /** The configured pin, or null when Codex's config.toml has no root `model`. */
+  model: string | null;
+  /** Which surface answered; null when neither could be read. */
+  source: "proxy" | "catalog" | null;
+  detail: string;
+  action?: string;
+}
+
+/** Exactly the catalog's own `RawEntry` shape, so an on-disk row needs no conversion. */
+type CatalogVisibilityRow = Record<string, unknown>;
+
+export interface DefaultModelExposureDeps {
+  readConfiguredModelFn?: () => string | null;
+  /** The live proxy doctor already resolved, or null/absent when none is running. */
+  live?: LiveProxy | null;
+  fetchFn?: typeof fetch;
+  readCatalogModelsFn?: () => readonly CatalogVisibilityRow[] | null;
+}
+
+/**
+ * Ids the running proxy advertises, or null when the read did not produce a usable answer.
+ *
+ * Null is deliberately indistinguishable across transport failure, a non-200, and a malformed
+ * body, because every one of them means the same thing to the caller: this surface did not
+ * answer, ask the next one. The 401 case is real rather than theoretical — `/v1/models` requires
+ * data-plane admission on a non-loopback bind (`isApiAuthRequired`), and doctor deliberately
+ * holds no data-plane key, so a remote-bound proxy always falls through to the catalog.
+ */
+async function fetchExposedModelIds(live: LiveProxy, fetchFn: typeof fetch): Promise<Set<string> | null> {
+  try {
+    const res = await fetchFn(`http://${probeHostname(live.hostname)}:${live.port}/v1/models`, {
+      signal: AbortSignal.timeout(EXPOSED_MODELS_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const body = await res.json() as { data?: unknown };
+    if (!Array.isArray(body?.data)) return null;
+    const ids = new Set<string>();
+    for (const row of body.data) {
+      const id = (row as { id?: unknown } | null)?.id;
+      if (typeof id === "string" && id.length > 0) ids.add(id);
+    }
+    return ids;
+  } catch {
+    return null;
+  }
+}
+
+/** Picker-visible catalog slugs, or null when the catalog is absent or unparseable. */
+function catalogExposedModelIds(rows: readonly CatalogVisibilityRow[] | null): Set<string> | null {
+  if (rows === null) return null;
+  const ids = new Set<string>();
+  for (const row of rows) {
+    // `visibility: "hide"` rows are retained on purpose (see the native-toggle contract in
+    // structure/catalog.md); they are exactly the rows a pin must not resolve to.
+    if (!row || row.visibility !== "list") continue;
+    const slug = row.slug;
+    if (typeof slug === "string" && slug.length > 0) ids.add(slug);
+  }
+  return ids;
+}
+
+function defaultCatalogModels(): readonly CatalogVisibilityRow[] | null {
+  const models = readCatalog(readCodexCatalogPath())?.models;
+  return Array.isArray(models) ? models : null;
+}
+
+/**
+ * Compare Codex's root `model` pin against the models this install actually exposes (#4646).
+ *
+ * The exposed set is read, never recomputed. Reproducing the live assembly in the CLI would mean
+ * duplicating an entitlements snapshot, a provider gather and account-selector expansion, and the
+ * duplicate would drift — the same failure `formatStartupRoutingDetail` and `computeVersionSkew`
+ * were extracted to prevent. So the running proxy answers when there is one, the on-disk catalog
+ * answers otherwise, and neither is reconstructed here.
+ *
+ * Both surfaces are consulted before any negative verdict. They name a routed row through the
+ * same `<provider>/<id>` slug space, but they are built by different code at different times, so
+ * requiring both to disagree is what keeps an encoding or staleness difference from being
+ * reported to the operator as a broken pin.
+ */
+export async function collectDefaultModelExposure(
+  deps: DefaultModelExposureDeps = {},
+): Promise<DefaultModelExposure> {
+  const configured = (deps.readConfiguredModelFn ?? readConfiguredDefaultModel)();
+  const model = typeof configured === "string" ? configured.trim() : "";
+  if (!model) {
+    return {
+      status: "not_configured",
+      model: null,
+      source: null,
+      detail: "Codex config.toml pins no root `model`, so Codex picks from the exposed catalog",
+    };
+  }
+
+  const live = deps.live ?? null;
+  const proxyIds = live ? await fetchExposedModelIds(live, deps.fetchFn ?? fetch) : null;
+  const catalogIds = catalogExposedModelIds((deps.readCatalogModelsFn ?? defaultCatalogModels)());
+  if (proxyIds === null && catalogIds === null) {
+    return {
+      status: "undeterminable",
+      model,
+      source: null,
+      detail: `could not read the exposed model set, so Codex \`model = "${model}"\` was not checked`,
+      action: "Start the proxy with 'ocx start', or run 'ocx sync' to write the Codex catalog, then re-run 'ocx doctor'",
+    };
+  }
+
+  const source = proxyIds !== null ? "proxy" as const : "catalog" as const;
+  // `source` reports which surface produced the verdict, so a match names the surface that
+  // matched rather than the one we happened to read first.
+  const matched = proxyIds?.has(model) === true
+    ? "proxy" as const
+    : catalogIds?.has(model) === true ? "catalog" as const : null;
+  if (matched !== null) {
+    return {
+      status: "exposed",
+      model,
+      source: matched,
+      detail: `Codex \`model = "${model}"\` is exposed by this install`,
+    };
+  }
+  // Name only the surfaces that actually answered: claiming a check that did not happen is the
+  // same defect as claiming an exposure verdict we could not reach.
+  const checked = [
+    ...(proxyIds !== null ? ["the running proxy's /v1/models"] : []),
+    ...(catalogIds !== null ? ["the on-disk Codex catalog"] : []),
+  ].join(" and ");
+  return {
+    status: "not_exposed",
+    model,
+    source,
+    detail: `Codex \`model = "${model}"\` is NOT exposed by this install (checked ${checked}), so every new Codex session starts on a model this proxy does not serve`,
+    action: "Expose that model (enable it in the dashboard or drop it from 'disabledModels') and run 'ocx sync', or pin an exposed id as 'model' in CODEX_HOME/config.toml",
+  };
+}
+
 export async function runDoctor(args: string[] = []): Promise<void> {
   if (args.includes("--fix-codex-runtime")) {
     const resolved = resolveCodexRuntime();
@@ -1325,6 +1484,26 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     console.log(line);
   }
 
+  // Adjacent to the section above because both read Codex's config.toml, and an operator
+  // debugging "Codex config" wants the pinned model checked in the same place.
+  console.log("\nCodex default model exposure");
+  const defaultModelExposure = await collectDefaultModelExposure({ live });
+  if (defaultModelExposure.status === "not_exposed") {
+    console.log(`  !!     ${defaultModelExposure.detail}`);
+    console.log(`         Action: ${defaultModelExposure.action}`);
+  } else if (defaultModelExposure.status === "undeterminable") {
+    // Not `!!`: nothing is known to be wrong. The one thing this must never do is report an
+    // unread set as a broken pin.
+    console.log(`  --     ${defaultModelExposure.detail}`);
+    console.log(`         Action: ${defaultModelExposure.action}`);
+  } else {
+    console.log(`  ok     ${defaultModelExposure.detail}`);
+  }
+  // Deliberately no `recordDoctorFailure()` and no `process.exitCode` write. A pin that is not
+  // exposed is a degraded install, not an unusable one — the operator can still pick another
+  // model in the session — and the rule above reserves FAIL for an unusable surface so a warning
+  // cannot break a legitimately green pipeline.
+
   console.log("\nCodex agent role files");
   const tomlFallbackRoles = scanCodexAgentRolesWithTomlModelFallback(resolveCodexHomeDirImpl());
   if (tomlFallbackRoles.length === 0) {
@@ -1333,6 +1512,16 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     console.log(`  [WARN] ${tomlFallbackRoles.length} agent role file${tomlFallbackRoles.length === 1 ? "" : "s"} contain${tomlFallbackRoles.length === 1 ? "s" : ""} \`model_fallback\`: ${tomlFallbackRoles.join(", ")}`);
     console.log("        Codex >= 0.146 rejects that field as unknown and skips the whole role. Move the chains to opencodex config `subagentModelFallbackByModel` (keyed by primary model) and remove the field from the TOML files.");
   }
+  // opencodex does not write these files; the Codex desktop external-agent import does, and it
+  // drops the model pin on the way in. Observe-only: doctor never repairs or removes them.
+  const unpinnedDerivedRoles = scanOpencodexDerivedCodexAgentRolesWithoutModelPin(resolveCodexHomeDirImpl());
+  if (unpinnedDerivedRoles.length === 0) {
+    console.log("  ok     every opencodex-derived role file in $CODEX_HOME/agents/*.toml pins a model");
+  } else {
+    console.log(`  [WARN] ${unpinnedDerivedRoles.length} opencodex-derived role file${unpinnedDerivedRoles.length === 1 ? "" : "s"} without a \`model\` pin: ${unpinnedDerivedRoles.map(role => `${role}.toml`).join(", ")}`);
+    console.log("        Codex runs these roles on the parent model, so a spawn records one role and another model. The `ocx-route` directive in the file cannot pin them: it is honoured only on the Claude Code `/v1/messages` path and is inert on `/v1/responses`.");
+    console.log("        Add `model = \"<id>\"` to each file, or remove them. They usually come from the Codex desktop external-agent import of ~/.claude/agents/ocx-*.md; set `[desktop] external-agent-import-sync-item-types` with `SUBAGENTS = false` to stop it recreating them.");
+  }
 
   const dual = collectWslDualInstall();
   if (dual.wsl) {
@@ -1397,6 +1586,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     hints.push(`${row.detail}. Set ${row.envName} in the shell that starts the proxy, or store a literal key in config (value hidden here).`);
   }
   if (codexEnvKeyReadiness) hints.push(`${codexEnvKeyReadiness.detail}. ${codexEnvKeyReadiness.action}.`);
+  // Only the negative verdict becomes a hint. "Could not determine" is usually just a proxy that
+  // is not running, which `proxyDownRestartHint` already reports; repeating it here would put a
+  // second line in the hint list for one fact.
+  if (defaultModelExposure.status === "not_exposed") {
+    hints.push(`${defaultModelExposure.detail}. ${defaultModelExposure.action}.`);
+  }
   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

@@ -27,7 +27,8 @@ export function printUsage(): void {
 
 Usage:
   ocx setup                   Interactive setup (alias: init)
-  ocx start [--port <port>]   Start the proxy server (auto-syncs models to Codex)
+  ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]
+                              Start the proxy; SOCKS5 defaults to 127.0.0.1:10808
   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)
@@ -102,6 +103,8 @@ Examples:
   ocx init                    Set up provider and inject into Codex
   ocx start                   Start on default port (10100)
   ocx start --port 8080       Start on custom port
+  ocx start --socks5          Outbound via SOCKS5 at 127.0.0.1:10808 (saved)
+  ocx start --socks5-off      Clear a saved SOCKS5 outbound proxy
   ocx help service            Show service command help
   ocx help hub                Explain the hub topology, token file, and invites
   ocx sync                    Sync available models to Codex`);

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,10 @@ import {
 } from "./tray-proxy";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
-import { dispatchCommand , decideStartWithLiveOwner } from "./dispatch";
+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 +172,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 +267,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 +324,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 +361,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
@@ -927,8 +979,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/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);