@yansigit/opencodex 2.36.1-dev.20260829.48 → 2.36.1

package/src/cli/dispatch.ts

@@ -9,6 +9,7 @@
  * never needs to import the entry module back (no cycle).
  */
 import { CLI_COMMANDS } from "./registry";
+import { isValidProviderName } from "../config/provider-name";
 import type { CliHead } from "./root";
 import type { ReadyArgs } from "./ready";
 import type { LiveProxy } from "../server/proxy-liveness";
@@ -21,6 +22,7 @@ import { restoreNativeCodexAsync } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
 import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
+import { isJsonOption, takeFlag } from "./runtime-api";
 
 export interface CliDispatchDeps {
   args: string[];
@@ -69,33 +71,37 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   restore: async deps => {
-    const restoreJson = deps.args[1] === "--json";
-    if (deps.args[1] === "back") {
+    const restoreArgs = deps.args.slice(1);
+    const restoreJson = takeFlag(restoreArgs, "--json");
+    if (restoreArgs[0] === "back") {
       // Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
       // lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
       // this only re-runs the same inject (config + catalog + history) `ocx start` does.
+      // takeFlag above makes `ocx restore --json back` restore-back, not eject.
+      const { skippedRestoreEnvelope } = await import("../codex/inject");
+      const emitBack = (success: boolean, message: string, code: number): number => {
+        if (restoreJson) console.log(JSON.stringify(skippedRestoreEnvelope(success, message)));
+        else if (code === 0) console.log(message);
+        else console.error(message);
+        return code;
+      };
       const live = await deps.findLiveProxy();
       if (!live) {
-        console.error("No running proxy found. Run 'ocx start' — it injects opencodex automatically.");
-        return 1;
+        return emitBack(false, "No running proxy found. Run 'ocx start' — it injects opencodex automatically.", 1);
       }
       const desired = setIntegrationEnabled("codex", true);
       if (!desired.ok) {
-        console.error(`Codex desired state was not saved (${desired.reason}).`);
-        return desired.reason === "conflict" ? 2 : 1;
+        return emitBack(false, `Codex desired state was not saved (${desired.reason}).`, desired.reason === "conflict" ? 2 : 1);
       }
       const synced = await syncModelsToCodex(live.port);
       if (synced.status === "skipped") {
-        console.error("Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.");
-        return 2;
+        return emitBack(false, "Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.", 2);
       }
       if (!synced.ok) {
-        console.error("Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.");
-        return 1;
+        return emitBack(false, "Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.", 1);
       }
       const target = collectOrcaCodexHomeDiagnostic();
-      console.log(`Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`);
-      return 0;
+      return emitBack(true, `Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`, 0);
     }
     const desired = setIntegrationEnabled("codex", false);
     if (!desired.ok) {
@@ -172,14 +178,35 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   doctor: async deps => {
     const doctorArgs = deps.args.slice(1);
-    const { RECOVER_ZERO_BYTE_COORDINATOR_FLAG, runDoctor } = await import("./doctor");
+    // `--json` was silently ignored here: runDoctor scans for its own flags and prints human
+    // output regardless, so a caller that asked for JSON got prose and exit 0 -- and the skill
+    // recipes recommended exactly that invocation. Refusing it is worse than supporting it and
+    // better than lying about it.
+    //
+    // Not implemented rather than deferred silently: runDoctor has no report collection at all
+    // (a module-level failure bit plus ~90 direct console emissions), and this runner appends
+    // the Codex Log Guard's human output after it returns, so emitting a JSON document here
+    // would interleave prose with JSON on one stdout -- unparseable, which is worse than the
+    // ignored flag. The structured-report refactor is tracked as its own work-phase.
+    if (doctorArgs.some(isJsonOption)) {
+      console.error("ocx doctor does not support --json yet. Run `ocx doctor` for the human report, or use `ocx status --json` and `ocx ready --json` for machine-readable health.");
+      return 2;
+    }
+    const { RECOVER_ZERO_BYTE_COORDINATOR_FLAG, runDoctor, doctorFailed } = await import("./doctor");
     await runDoctor(doctorArgs);
     if (!doctorArgs.includes("--fix-codex-runtime") && !doctorArgs.includes(RECOVER_ZERO_BYTE_COORDINATOR_FLAG)) {
       console.log("");
       const { printCodexLogGuardDoctor } = await import("./codex-log-guard-doctor");
       printCodexLogGuardDoctor();
     }
-    return 0;
+    // A diagnostic that always exits 0 cannot gate a script. `runDoctor` reports by direct
+    // console.log with no checks collection, and signals its own special-flag failures
+    // through process.exitCode, so honour both: an explicit exitCode wins, otherwise a
+    // FAIL-level check fails the command. This is a BREAKING change for pipelines that ran
+    // `ocx doctor` and ignored the result; a diagnostic that cannot fail is worse.
+    const explicit = Number(process.exitCode ?? 0);
+    if (explicit !== 0) return explicit;
+    return doctorFailed() ? 1 : 0;
   },
   debug: async deps => {
     const { handleDebugCommand } = await import("./debug");
@@ -196,10 +223,61 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   logout: async deps => {
+    // Argv is parsed BEFORE any store access, which is the whole point of this shape.
+    // Previously `args[1]` was taken as the provider name with no parsing, so
+    // `ocx logout --json` called removeCredential("--json"), printed "Logged out of
+    // --json." and exited 0 -- a silent false success, the worst outcome for a caller
+    // that can only see the exit code.
+    //
+    // That is not merely a wasted call. `normalizeAuthStore` copies every top-level key
+    // it finds, so a hand-edited, legacy, or corrupted auth.json containing a `--json`
+    // key would have its active account deleted -- and the key dropped entirely if that
+    // was its last account. A flag must never reach the store as a provider name.
+    const logoutArgs = deps.args.slice(1);
+    const wantsJson = logoutArgs.includes("--json");
+    // Any leading dash is an option, not a provider. Matching only `--` left the same defect
+    // one dash shorter: `ocx logout -j` treated `-j` as the provider name and, with a `-j` key
+    // present in the store, deleted it and exited 0.
+    const isOption = (arg: string): boolean => arg.startsWith("-");
+    const positionals = logoutArgs.filter(arg => !isOption(arg));
+    const unknownFlags = logoutArgs.filter(arg => isOption(arg) && arg !== "--json");
+    const name = (positionals[0] ?? "").trim().toLowerCase();
+
+    // Usage failures exit 2 and touch nothing. A missing provider is a usage error; a
+    // provider that simply has no credential is a not-found (4) further down, because the
+    // vocabulary distinguishes "you called this wrong" from "the thing is not there".
+    //
+    // The shape check is `isValidProviderName`, not another dash test. Rejecting a leading
+    // ASCII `-` fixed `-j` and still let `logout —json` through with a Unicode dash, which is
+    // the same defect a third time: each patch named one spelling instead of the class. The
+    // canonical validator states the rule positively -- start and end alphanumeric, internal
+    // `._-` allowed -- so `github-copilot` and `google-antigravity` pass while every dash
+    // variant, empty string, and reserved name fails. Anything that is not a possible
+    // provider id cannot reach the store at all.
+    const malformedName = Boolean(name) && !isValidProviderName(name);
+    if (unknownFlags.length > 0 || positionals.length > 1 || !name || malformedName) {
+      const problem = unknownFlags.length > 0
+        ? `unknown option ${unknownFlags[0]}`
+        : positionals.length > 1 ? "too many arguments"
+        : malformedName ? `not a valid provider name: ${name}`
+        : "missing provider";
+      console.error(`Usage: ocx logout <provider> [--json]  (${problem})`);
+      return 2;
+    }
+
+    // The disposition comes from inside the store mutation, not from a read-then-remove
+    // preflight. `mutateStore` serializes writes, so a preflight leaves a window where a
+    // concurrent logout removes the same account and BOTH callers exit 0 claiming a removal --
+    // a false success again, just a narrower one than the flag bug above.
     const { removeCredential } = await import("../oauth/store");
-    const name = (deps.args[1] ?? "").trim().toLowerCase();
-    await removeCredential(name);
-    console.log(`Logged out of ${name || "(none)"}.`);
+    const outcome = await removeCredential(name);
+    if (outcome === "not-found") {
+      if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: false, provider: name, removed: false, reason: "not_found" }, null, 2));
+      else console.error(`No stored credential for '${name}'.`);
+      return 4;
+    }
+    if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: true, provider: name, removed: true }, null, 2));
+    else console.log(`Logged out of ${name}.`);
     return 0;
   },
   sync: async deps => {
@@ -270,18 +348,76 @@ const commandRunners: Record<string, CommandRunner> = {
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
     const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
+    const { readCodexCatalogPathForHome } = await import("../codex/catalog/parsing");
+    const { existsSync } = await import("node:fs");
     const owningCodexHome = getCodexHome();
     const desiredDisabled = !shouldSyncCodexOnStart(deps.loadConfig());
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
       invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
+    const cacheJson = cacheArgs.includes("--json");
+    const jsonSafeLog = cacheJson
+      ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
+      : console;
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
     if (invalidated.kind === "completed" && invalidated.value) {
-      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
-      if (restartDesktopApp) await handleDesktopAppRestart(console);
-    } else if (desiredDisabled) {
-      console.log("Codex integration is OFF; cache sync skipped (no catalog or cache write).");
+      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: jsonSafeLog });
+      if (restartDesktopApp) await handleDesktopAppRestart(jsonSafeLog);
+    } else if (desiredDisabled && !cacheJson) {
+      // Worth saying in the human path, because it explains why nothing was written.
+      // Under --json this belongs on the envelope, not as a second stdout line.
+      console.log("Codex integration is OFF; no catalog or cache write resulted.");
     }
-    return 0;
+    // `completed` with a falsy value means the cache was NOT rewritten. Previously every
+    // outcome exited 0, so a script could not tell a refreshed cache from a skipped one.
+    //
+    // Losing the catalog write lock to another process is a skip, not a failure:
+    // serialization working as designed is the expected outcome under concurrency, and a
+    // proxy startup holding the permit would otherwise make a perfectly healthy
+    // `ocx sync-cache` exit 1 and fail the pipeline that called it -- intermittently, so it
+    // would read as a flake rather than a bug. `codex-retained-root-serialization.test.ts`
+    // pins exactly that: contended lock, no cache write, exit 0.
+    //
+    // `desiredDisabled` is deliberately NOT part of the success test, which is the subtle
+    // part. This call passes `allowWhenDesiredDisabled: true`, so the OFF gate inside the
+    // refresh never fires and the work is genuinely attempted -- an explicit `ocx sync-cache`
+    // means the user asked for it regardless of the toggle. Treating OFF as automatic success
+    // would report exit 0 and `skipped: true` for a refresh that actually failed.
+    //
+    // But `invalidateCodexModelsCacheWithPermit` returns a bare boolean for four different
+    // situations -- wrote it, no catalog file exists, the OFF gate fired, or it threw -- so
+    // `false` alone cannot be read as failure either. `!existsSync(catalogPath)` is a
+    // legitimate nothing-to-do: with no catalog there is no cache to derive, which is the
+    // normal state of a fully native home and the case
+    // `codex-composed-acceptance.test.ts` pins at exit 0. It is checked here rather than by
+    // widening that function's return type, because its boolean is consumed by a dozen
+    // management routes that have no use for the distinction.
+    const wrote = invalidated.kind === "completed" && Boolean(invalidated.value);
+    const contended = invalidated.kind === "unavailable" && invalidated.reason === "busy";
+    const noCatalog = !wrote && !existsSync(readCodexCatalogPathForHome(owningCodexHome));
+    const ok = wrote || contended || noCatalog;
+    if (cacheJson) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        ok,
+        wrote,
+        skipped: contended || noCatalog,
+        outcome: invalidated.kind,
+        // `outcome` alone cannot separate a contended lock from a hard serialization
+        // failure -- both are `unavailable`. Carry the reason so a caller can.
+        reason: invalidated.kind === "unavailable" ? invalidated.reason : undefined,
+        // Which of the two benign skips this was, so `skipped: true` is never opaque.
+        skippedReason: contended ? "contended" : noCatalog ? "no_catalog" : undefined,
+        desiredDisabled,
+        codexHome: owningCodexHome,
+      }, null, 2));
+    } else if (contended) {
+      console.log("Another process owns the catalog write; cache sync skipped.");
+    } else if (noCatalog) {
+      console.log("No Codex catalog to derive a cache from; nothing to sync.");
+    } else if (!ok) {
+      console.error(`Cache refresh did not complete (${invalidated.kind}). The Codex model cache was not rewritten.`);
+    }
+    return ok ? 0 : 1;
   },
   gui: async deps => {
     const config = deps.loadConfig();
@@ -315,8 +451,12 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   tray: async deps => {
     const { windowsTrayCommand } = await import("../tray/windows");
+    // windowsTrayCommand reports failure through process.exitCode (tray/windows.ts sets
+    // it for bad usage and for a failed install/start/stop/uninstall) and returns void,
+    // so a literal 0 here made `ocx tray install` print an error and exit 0 (#2697).
+    process.exitCode = 0;
     await windowsTrayCommand(deps.args.slice(1));
-    return 0;
+    return Number(process.exitCode ?? 0);
   },
   "codex-shim": async deps => {
     const { codexShimStatus, diagnoseCodexShim, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
@@ -395,6 +535,10 @@ const commandRunners: Record<string, CommandRunner> = {
     await deps.handleProxyRestart(deps.handleRestartStartWhenStopped);
     return Number(process.exitCode ?? 0);
   },
+  capabilities: async deps => {
+    const { runCapabilities } = await import("./capabilities-command");
+    return await runCapabilities(deps.args.slice(1));
+  },
   health: async deps => {
     const healthArgs = deps.args.slice(1);
     const wantsHealthJson = healthArgs.includes("--json");
@@ -418,8 +562,15 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   provider: async deps => {
     const { handleProviderCommand } = await import("./provider");
+    // Reset first, like the service runner below: reading process.exitCode only
+    // reports THIS command's outcome if nothing earlier in the process set it.
+    process.exitCode = 0;
     await handleProviderCommand(deps.args.slice(1));
-    return 0;
+    // handleProviderCommand reports failure through process.exitCode, which it sets
+    // from handleProviderRuntimeCommand. Returning a literal 0 here made index.ts
+    // call process.exit(0) and erase it, so `ocx provider quota` against a stopped
+    // proxy printed an error and still exited 0 (#2697).
+    return Number(process.exitCode ?? 0);
   },
   account: async deps => {
     const { cmdAccount } = await import("./account");
@@ -427,8 +578,11 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   models: async deps => {
     const { handleModels } = await import("./models");
+    process.exitCode = 0;
     await handleModels(deps.args.slice(1));
-    return 0;
+    // Same as the provider runner above: handleModels sets process.exitCode from
+    // handleModelsRuntimeCommand, and a literal 0 discarded it (#2697).
+    return Number(process.exitCode ?? 0);
   },
   alias: async deps => {
     const { handleAliasCommand } = await import("./alias");
@@ -459,6 +613,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleObserveCommand } = await import("./observe");
     return await handleObserveCommand(deps.args.slice(1));
   },
+  inspect: async deps => {
+    const { handleInspectCommand } = await import("./inspect");
+    return await handleInspectCommand(deps.args.slice(1));
+  },
   logs: async deps => {
     const { handleObserveCommand } = await import("./observe");
     return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
@@ -468,8 +626,12 @@ const commandRunners: Record<string, CommandRunner> = {
     return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
   },
   storage: async deps => {
-    const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+    // `ocx storage` used to be a pure alias of `observe storage`, which reached only the report
+    // route. wp7 gave it cleanup, trash, and policy subcommands, so it dispatches to its own
+    // module -- with `report` as the default subcommand, so a bare `ocx storage` still prints
+    // the same thing it printed before.
+    const { handleStorageCommand } = await import("./storage");
+    return await handleStorageCommand(deps.args.slice(1));
   },
   memory: async deps => {
     const { handleObserveCommand } = await import("./observe");
@@ -496,6 +658,12 @@ const commandRunners: Record<string, CommandRunner> = {
     if (integration === "grok") {
       const { handleGrokCommand } = await import("./integrations");
       return await handleGrokCommand(deps.args.slice(2));
+    } else if (integration === "native") {
+      // The native client toggles are a separate server surface from the reversible file
+      // integrations `client` manages, so they get their own subcommand rather than being
+      // folded into one that means something else.
+      const { handleIntegrationCommand } = await import("./inspect");
+      return await handleIntegrationCommand(deps.args.slice(1));
     } else if (integration === "claude") {
       const { handleClaudeConfigCommand } = await import("./integrations");
       return await handleClaudeConfigCommand(deps.args.slice(2));

package/src/cli/doctor.ts

@@ -16,6 +16,8 @@ import { findLiveProxy, 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";
+import { tokenCollidesWithAdmin } from "../lib/admin-secrets";
+import { readInstalledServiceToken } from "../lib/service-secrets";
 import { PROXY_ENV_KEYS, proxyEnvPresent } from "../lib/proxy-env";
 import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
 import { readCodexTokens } from "../codex/auth-collision";
@@ -58,7 +60,35 @@ import {
 } from "../server/local-management-read-client";
 export { resolveCodexHomeDir } from "../codex/home";
 
-export type OAuthDoctorCheck = { level: "OK" | "WARN"; message: string };
+/**
+ * `FAIL` exists for a condition that makes the surface unusable rather than degraded.
+ * A review of the #2696 work pointed out that reporting a fully fenced management plane
+ * — every `/api/*` returning 503 — at the same level as a directory-permission note
+ * misleads the reader about severity.
+ *
+ * Doctor's own exit code still belongs to the uniform contract in wp3b (devlog 025);
+ * this type only fixes what the operator is told.
+ */
+export type OAuthDoctorCheck = { level: "OK" | "WARN" | "FAIL"; message: string };
+
+/**
+ * Whether any FAIL-level condition was seen during this `runDoctor` pass.
+ *
+ * Module-scoped and reset at the top of `runDoctor` rather than threaded through, because
+ * `runDoctor` reports by direct `console.log` across a dozen sections and has no checks
+ * collection to inspect. Reset matters for the test suite, which calls `runDoctor` several
+ * times in one process; a sticky flag would make the second call fail because the first did.
+ */
+let doctorSawFailure = false;
+
+function recordDoctorFailure(): void {
+  doctorSawFailure = true;
+}
+
+/** True when the last `runDoctor` pass saw a FAIL-level condition. */
+export function doctorFailed(): boolean {
+  return doctorSawFailure;
+}
 
 function pathIsWritable(path: string): boolean {
   try {
@@ -137,6 +167,50 @@ function describeDoctorHealth(entry: OAuthHealthEntry): string {
   }
 }
 
+/**
+ * Detect the management/data-plane credential collision behind #2696.
+ *
+ * The service exports the service token file as `OPENCODEX_API_AUTH_TOKEN` before
+ * starting the proxy. When that value is the admin token, the server treats the
+ * management credential as a data-plane admission secret and fences the ENTIRE
+ * management plane closed at boot: every `/api/*` returns 503, including on a loopback
+ * install that never needed a data-plane secret.
+ *
+ * `assertNotAdminToken` in src/service.ts now refuses to create this state, but an
+ * install made before that guard existed is already broken on disk, and the symptom
+ * (every management command failing) points nowhere. This is the check that names it.
+ *
+ * Observe-only, like the rest of doctor: it compares shapes and never prints, logs, or
+ * returns a credential value.
+ */
+export function dataPlaneCredentialCollisionCheck(
+  env: NodeJS.ProcessEnv = process.env,
+  installedServiceToken: string | null = readInstalledServiceToken(),
+): OAuthDoctorCheck {
+  const dataPlane = env.OPENCODEX_API_AUTH_TOKEN?.trim() || installedServiceToken?.trim() || "";
+  if (!dataPlane) {
+    return { level: "OK", message: "No data-plane token is set, so it cannot collide with the management token." };
+  }
+  // Same comparison as assertNotAdminToken: minted prefix or configuredAdminToken
+  // (env or admin-api-token file). The file token is the one the service wrapper
+  // actually exports; inspecting only the doctor process env reported OK on every
+  // already-broken install (#2696).
+  if (!tokenCollidesWithAdmin(dataPlane, env)) {
+    return { level: "OK", message: "Data-plane and management credentials are distinct." };
+  }
+  return {
+    // Not a degradation: while this holds, every /api/* returns 503 and no ocx
+    // management command can work at all.
+    level: "FAIL",
+    message:
+      "The data-plane secret (OPENCODEX_API_AUTH_TOKEN or the service token file) holds the "
+      + "management (admin) token, so the proxy fences the whole management API closed and "
+      + "every ocx management command fails with 503. "
+      + "Action: unset OPENCODEX_API_AUTH_TOKEN, replace the service token file with a distinct "
+      + "data-plane key, then re-run `ocx service install` and restart the proxy",
+  };
+}
+
 /**
  * OAuth reliability checks for `ocx doctor`. Observe-only: never mutates
  * credentials, locks, or networking. Every WARN includes a recovery Action.
@@ -147,6 +221,8 @@ export async function collectOAuthDoctorChecks(
 ): Promise<OAuthDoctorCheck[]> {
   const checks: OAuthDoctorCheck[] = [];
 
+  checks.push(dataPlaneCredentialCollisionCheck());
+
   if (isOAuthCredentialStorageWritable()) {
     checks.push({ level: "OK", message: "OAuth credential storage directory is writable for atomic auth.json updates." });
   } else {
@@ -935,6 +1011,9 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   }
 
   console.log("opencodex doctor\n");
+  // Reset per pass: the suite drives runDoctor several times in one process, and a sticky
+  // flag would fail the second call because the first saw a problem.
+  doctorSawFailure = false;
 
   // Ordering note: the memory/runtime section renders after "Running proxy
   // process proxy env" below; helpers live above runDoctor for testability.
@@ -1020,6 +1099,20 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
   });
 
+  // Mirrors `ocx status` through the same comparison rather than a second implementation:
+  // two diagnostics disagreeing about whether an install is stale is worse than one (#2701).
+  // No extra probe -- findLiveProxy already carried the version back.
+  {
+    const { packageVersion } = await import("./help");
+    const { computeVersionSkew } = await import("./version-skew");
+    const skew = computeVersionSkew(packageVersion(), live?.version);
+    if (skew.skewed && skew.warning) {
+      console.log(`!! ${skew.warning}`);
+    } else if (skew.proxyVersion !== null) {
+      console.log(`ok ocx ${skew.cliVersion} matches the running proxy`);
+    }
+  }
+
   const currentProxyEnv = collectProxyEnv();
   const configuredProxy = collectConfiguredProxy();
   const runningProxyEnv = collectRunningProxyEnv({
@@ -1148,6 +1241,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log("\nOAuth reliability");
   for (const check of await collectOAuthDoctorChecks()) {
     console.log(`  [${check.level}] ${check.message}`);
+    // A diagnostic that always exits 0 cannot gate anything, which defeats the point of
+    // running it from a script (#2697's sibling defect). FAIL is the level reserved for a
+    // surface that is unusable rather than degraded, so it -- and only it -- fails the
+    // command. WARN stays exit 0 on purpose: warning on a degraded-but-working install
+    // must not break a pipeline that is legitimately green.
+    if (check.level === "FAIL") recordDoctorFailure();
   }
 
   // #857: a running Codex app-server can keep an older in-memory catalog than

package/src/cli/help.ts

@@ -5,7 +5,14 @@ import { findCommand } from "./registry";
 
 const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
 
-function packageVersion(): string {
+/**
+ * Version of the `ocx` bundle this process is running from.
+ *
+ * Exported so `status`/`doctor` can compare it against the version the live proxy reports,
+ * which is how a stale `ocx` earlier on PATH becomes visible (#2701). Returns `"unknown"`
+ * rather than throwing; callers must treat that as "cannot compare", not as a mismatch.
+ */
+export function packageVersion(): string {
   const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
   const parsed = JSON.parse(raw) as { version?: unknown };
   return typeof parsed.version === "string" ? parsed.version : "unknown";
@@ -48,6 +55,7 @@ Usage:
   ocx restart                  Stop and restart the proxy
   ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|keep-native-v1|threads|mode-hint)
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
+  ocx capabilities [--json]    List declared capabilities and the API routes they drive
   ocx ready [--json] [--wait [--timeout <s>]]  Check post-sync readiness (exit 0 only when ready)
   ocx provider <sub>          Providers, connectivity, quota, and selected models
   ocx account <sub>           Accounts, login/reauth, key pools, and quota controls
@@ -56,11 +64,12 @@ Usage:
   ocx combo <sub>             Combo failover/round-robin routing
   ocx agent <sub>             Subagents, roles, injection, effort caps, and sidecars
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
+  ocx inspect <sub>           Effective config, catalog, analytics, pacing, client-config
   ocx route <sub>             Routing features (combo, policy)
   ocx logs [filters]          Alias of ocx observe logs
   ocx usage [--range <today|1d|7d|30d|all>] [--provider <name>] [--model <id>]
                               Token and estimated-cost report (alias of ocx observe usage)
-  ocx storage [--json]        Alias of ocx observe storage
+  ocx storage <sub>           Storage report, cleanup, trash, and the cleanup policy
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information

package/src/cli/index.ts

@@ -26,6 +26,7 @@ import {
   writeRuntimePort,
 } from "../config/process-state";
 import { collectStatus, unusedProxyWarningLines } from "./status";
+import { takeFlag } from "./runtime-api";
 
 import {
   discoverStableProxyForRestart,
@@ -45,7 +46,7 @@ import { runReady, type ReadyArgs } from "./ready";
 import { runCli } from "./root";
 import { ProxyOwnershipRefusedError, stopProxy } from "../lib/process-control";
 import { loadServiceTokenFromFile } from "../lib/service-secrets";
-import { diagnoseService, isServiceOwnershipError, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "../service";
+import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalled, uninstallServiceIfInstalled } from "../service";
 import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import { drainAndShutdown, isRecyclingForExit, startServer } from "../server";
 import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
@@ -229,6 +230,11 @@ async function handleStart(options: { block?: boolean } = {}) {
   // auth path reads OPENCODEX_API_AUTH_TOKEN from the environment.
   const serviceToken = loadServiceTokenFromFile(process.env);
   if (serviceToken) process.env.OPENCODEX_API_AUTH_TOKEN = serviceToken;
+  // The service wrapper (and WinSW via OCX_API_TOKEN_FILE) can still export a colliding
+  // token that install now refuses to write. Refuse it here too, before bind, so an
+  // 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 owner = await findProxyOwnerBeforeJournalRecovery();
   if (owner.live) {
@@ -836,8 +842,12 @@ async function handleUninstall() {
 
 async function handleStatus() {
   const statusArgs = args.slice(1);
-  const wantsJson = statusArgs.length === 1 && statusArgs[0] === "--json";
-  if (statusArgs.length > 1 || (statusArgs.length === 1 && !wantsJson)) {
+  // Order-independent: the previous form only honoured `--json` as the LONE argument, so
+  // `ocx status --json --anything` silently printed human output to a caller that asked
+  // for JSON. Take the flag out of argv, then reject whatever is left over -- which keeps
+  // the strict unknown-argument behaviour rather than trading one defect for another.
+  const wantsJson = takeFlag(statusArgs, "--json");
+  if (statusArgs.length > 0) {
     console.error("Usage: ocx status [--json]");
     process.exit(1);
   }
@@ -854,6 +864,12 @@ async function handleStatus() {
     console.log(`❌ Proxy: ${status.proxyLabel}`);
   }
   console.log(`   Health: ${status.healthLabel}`);
+  // Printed here, not only in --json: a stale ocx on PATH is exactly the situation where
+  // the operator is reading human output and wondering why the CLI disagrees with the
+  // dashboard. Adding the JSON field alone would satisfy a test and help nobody (#2701).
+  if (status.json.versionSkew.warning) {
+    console.log(`   ⚠️  ${status.json.versionSkew.warning}`);
+  }
   for (const line of unusedProxyWarningLines({
     proxyUp: Boolean(status.json.proxy.pid || status.json.proxy.health.ok),
     routingKind: status.json.startup.routingKind,