fix(cli): tell a client-role listener apart from a missing management route

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}.`]);
 }
 

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);

src/server/proxy-liveness.ts

@@ -21,6 +21,12 @@ export interface HealthzIdentity {
   uptime?: unknown;
   pid?: unknown;
   port?: unknown;
+  /**
+   * Which listener answered: the standalone/hub server omits it, and the connected-client
+   * machine listener reports `"client"` (src/client/machine-listener.ts). It is the only
+   * on-the-wire way to tell those two apart, because both bind `config.port ?? 10100`.
+   */
+  role?: unknown;
   restartCapability?: unknown;
   providerReloadCapability?: unknown;
   guiPairCapability?: unknown;
@@ -78,6 +84,16 @@ export interface LiveProxy {
    * healthz body predates the field.
    */
   version?: string;
+  /**
+   * Role the live listener reported on `/healthz`, when it reported one: `"client"` for the
+   * connected-client machine listener, absent for a standalone or hub proxy.
+   *
+   * Liveness deliberately still ACCEPTS a client-role listener — see `isOpencodexHealthz`.
+   * The role is carried so a caller that needs a management plane (src/cli/runtime-api.ts)
+   * can refuse one, while `stop` and orphan cleanup keep finding the process they must act
+   * on. Absent for a proxy whose healthz body predates the field.
+   */
+  role?: string;
 }
 
 /**
@@ -101,6 +117,13 @@ export function probeHostname(hostname: string | undefined): string {
  * `service: "opencodex"` marker, plus the legacy `{status, version, uptime}` trio so a
  * still-running pre-identity proxy (e.g. right after `ocx update`) is not mistaken for a
  * foreign server and shadow-started over.
+ *
+ * The connected-client machine listener answers with the same `service: "opencodex"` marker
+ * and an extra `role: "client"`, and it is accepted here on purpose. Liveness answers "is one
+ * of our processes listening on this port", which is exactly what `ocx stop`, orphan cleanup,
+ * and duplicate-start avoidance need: rejecting the client role would make those paths blind to
+ * a real opencodex process and let them shadow-start over it. Callers that additionally need a
+ * management plane discriminate on `LiveProxy.role` instead of narrowing this predicate.
  */
 export function isOpencodexHealthz(body: HealthzIdentity | null): boolean {
   if (!body) return false;
@@ -114,7 +137,7 @@ export async function proxyIdentityAt(
   port: number,
   opts: { hostname?: string; expectedPid?: number } = {},
   io: LivenessIo = {},
-): Promise<{ pid: number | null; version?: string } | null> {
+): Promise<{ pid: number | null; version?: string; role?: string } | null> {
   const fetchFn = io.fetchFn ?? directLocalHttpFetch;
   const sleepFn = io.sleepFn ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
   const nowFn = io.nowFn ?? Date.now;
@@ -139,7 +162,14 @@ export async function proxyIdentityAt(
       if (opts.expectedPid !== undefined && pid !== null && pid !== opts.expectedPid) return null;
       // Guarded the same way `pid` is: a non-string version is absent, not coerced.
       const version = typeof body?.version === "string" ? body.version : undefined;
-      return version === undefined ? { pid } : { pid, version };
+      // Same guard for the role, for the same reason: absent on a standalone/hub proxy and on
+      // a legacy body, and never coerced from a non-string.
+      const role = typeof body?.role === "string" ? body.role : undefined;
+      return {
+        pid,
+        ...(version === undefined ? {} : { version }),
+        ...(role === undefined ? {} : { role }),
+      };
     } catch {
       // Transport failure (timeout / refused) — retry while budget remains; a proxy that
       // has only just begun listening can miss a single short probe (#764).
@@ -203,6 +233,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
           hostname: runtime.hostname,
           source: "runtime",
           ...(identity.version === undefined ? {} : { version: identity.version }),
+          ...(identity.role === undefined ? {} : { role: identity.role }),
         };
       }
     }
@@ -226,6 +257,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
         hostname: record.hostname,
         source: "runtime",
         ...(identity.version === undefined ? {} : { version: identity.version }),
+        ...(identity.role === undefined ? {} : { role: identity.role }),
       };
     }
   }
@@ -241,6 +273,7 @@ export async function findLiveProxy(io: LivenessIo = {}): Promise<LiveProxy | nu
       hostname: config.hostname,
       source: "config",
       ...(identity.version === undefined ? {} : { version: identity.version }),
+      ...(identity.role === undefined ? {} : { role: identity.role }),
     };
   }
   return null;

structure/config.md

@@ -370,6 +370,24 @@ Usage consumers preserve positive incomplete-history metadata as specified in [u
 `dropCodexSafetyBuffering` is an optional boolean, default false. Invalid API candidates reject;
 malformed persisted values stay disabled. It controls only the allowlisted client-output hints
 described in [Responses transport](transports/responses.md), not upstream policy or model selection.
+
+## Management-backed CLI commands need a management plane
+
+`src/cli/runtime-api.ts` is the single client every headless management subcommand calls through, so
+it owns the refusal as well as the request. `runtimeBaseUrl` resolves the live listener through
+`findLiveProxy`, and when that listener reports the client role — see
+[the client role owns no management plane](gui-and-management-api.md#the-client-role-owns-no-management-plane)
+— it refuses with `RuntimeApiError` status 503 instead of dialing it. The message names the port,
+states that the listener serves only the machine routes, points custom-model and other management
+edits at the hub the machine is connected to, and gives the on-machine alternative: edit
+`customModels` in `config.json`, then run `ocx sync`. The status is also the honest exit code, since
+`runCliAction` maps 404 to exit 4 and would otherwise report a missing record.
+
+A 404 body carrying both `method` and `path` is rendered as the route that listener does not serve,
+so any not-served-here answer stays legible rather than printing a bare token. `ocx models edit` in
+`src/cli/models-runtime.ts` narrows the opposite case: only a 404 without those keys is the
+management handler's own unknown-id answer, and it names the id and `ocx models list-custom`.
+
 ## Paginated history writer boundary
 
 `src/codex/history-provider.ts` refuses external writes to paginated or migration-capable history. `src/codex/inject.ts` checks affected rows and manifest-owned restore targets before and after config/profile/journal changes, including successful journal and fallback restores, and compensates detected migration. Failed config restore stops later catalog/history work and rolls back a coordinated remove transition. See the [history writer contract](codex-home.md#paginated-history-writer-boundary) for guarantees and concurrent-writer limits.

structure/gui-and-management-api.md

@@ -188,6 +188,23 @@ it. The matching CLI is `ocx account priority <provider> <id|main> [<value>]`, r
 when the value is omitted. Ordering invariants live in
 [`openai-tiers.md`](providers/openai-tiers.md).
 
+## The client role owns no management plane
+
+A connected client machine runs `src/client/machine-listener.ts` instead of the standalone server.
+It binds the address the standalone proxy would (`port ?? config.port ?? 10100`) and serves
+`GET /healthz`, `/readyz`, the packaged GUI/SPA routes, and `/api/machine/*`. Every other `/api/*`
+and `/v1/*` path is refused before dispatch with a JSON 404 naming the method and path. There is no
+second management port on such a machine: management rides the same listener a standalone or hub
+install runs, so a connected client has no `/api/*` management surface at all.
+
+The discriminator is `role` on `/healthz` and `/readyz`. The machine listener reports
+`role: "client"`; the standalone and hub server omit the field. `src/server/proxy-liveness.ts` parses
+it into `HealthzIdentity.role` and carries it on `LiveProxy.role`. `isOpencodexHealthz` still accepts
+a client-role body: liveness answers "is one of our processes listening here", which is what `ocx stop`,
+orphan cleanup, and duplicate-start avoidance need, and narrowing it would make them blind to a real
+opencodex process and let them shadow-start over it. Refusing the client role belongs to the caller
+that needs a management plane, which is the [CLI management client](config.md#management-backed-cli-commands-need-a-management-plane).
+
 ## Sidebar stop button
 
 The dashboard sidebar includes a stop button that calls `POST /api/stop`. The button shows a