@iislee/opencodex 2.31.0 → 2.35.0

package/src/cli/doctor.ts

@@ -10,11 +10,14 @@
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { getConfigDir, getConfigPath, readConfigDiagnostics, readPid, resolveEnvValue } from "../config";
+import { getConfigDir, getConfigPath, readConfigDiagnostics, resolveEnvValue } from "../config";
+import { readPid } from "../config/process-state";
 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";
@@ -41,7 +44,7 @@ import {
   resolveEffectiveUserIdentity,
 } from "../codex/user-identity";
 import { collectProjectCodexConfigWarnings, formatProjectCodexConfigWarningsForDoctor } from "../codex/project-config-warnings";
-import { collectStartupHealth, startupHealthSummary } from "../codex/autostart-health";
+import { collectStartupHealth, formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import {
   displayCodexRuntimePath,
   loadLastEffortClamp,
@@ -57,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 {
@@ -136,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.
@@ -146,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 {
@@ -934,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.
@@ -982,7 +1062,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const startup = collectStartupHealth(doctorConfig);
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
-  console.log(`       routing=${startup.routingKind}, service=${startup.serviceViable ? "viable" : startup.serviceInstalled ? "installed-but-unhealthy" : "absent"}, shim=${startup.shimHealthy ? "healthy" : startup.shimInstalled ? "stale" : "absent"}`);
+  console.log(`       ${formatStartupRoutingDetail(startup)}`);
 
   console.log("\nCodex runtime selection");
   {
@@ -1019,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({
@@ -1072,10 +1166,10 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log(`  ${probe.ok ? "ok " : "-- "} ${WHAM_USAGE_URL}`);
   console.log(`       ${detail}, ${probe.durationMs}ms, ${probe.authenticated ? "authenticated" : "unauthenticated"}`);
 
-  // Design B upgrade visibility: threads still tagged opencodex are invisible to the native
-  // Codex app until the one-time migration lands. Read-only probe (readonly sqlite, 100ms
-  // busy timeout) — reports state, never mutates.
-  console.log("\nCodex history migration");
+  // Design B upgrade visibility: only the backup manifest authorizes restoring provider
+  // metadata. Bare routed rows have unknown provenance and remain unchanged. This read-only
+  // probe reports manifest work and database readability; it never mutates.
+  console.log("\nCodex history metadata restore");
   // The history failure messages point here; make the visit worthwhile by
   // probing the coordinator namespace the locks live in. The probe exercises
   // identity, runtime-root, and permission checks without taking any lock or
@@ -1096,11 +1190,17 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   for (const line of formatCoordinatorDoctorLines(inspectCodexCoordinator())) console.log(line);
   const pending = countPendingOpencodexHistory();
   if (pending.failed) {
-    console.log("  --     state DB locked or unreadable (Codex app open?) — migration state unknown");
+    if (pending.failureReason === "busy") {
+      console.log("  --     history database, backup manifest, or rollout file is busy — exact metadata restore is pending");
+    } else if (pending.failureReason === "permission") {
+      console.log("  --     state DB or backup manifest access was denied — restore state unknown");
+    } else {
+      console.log("  --     backup manifest or restore target failed integrity checks — manual review required");
+    }
   } else if (pending.pendingRows === 0 && pending.backupEntries === 0) {
-    console.log("  ok     no legacy opencodex-tagged threads pending");
+    console.log("  ok     no manifest-backed provider metadata pending; untracked routed history is unchanged");
   } else {
-    console.log(`  --     ${pending.pendingRows} thread(s) still tagged opencodex, ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"}`);
+    console.log(`  --     ${pending.backupEntries} backup manifest entr${pending.backupEntries === 1 ? "y" : "ies"} pending exact metadata restore`);
   }
 
   console.log("\nProject Codex configs");
@@ -1141,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
@@ -1148,7 +1254,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const { collectCodexAppServerCatalogState } = await import("../codex/app-server-processes");
   const catalogState = collectCodexAppServerCatalogState();
   if (catalogState.state === "stale") {
-    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`)`);
+    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`; on Windows the desktop app may need \`ocx sync --restart-desktop-app\`)`);
   } else if (catalogState.state === "unknown") {
     console.log("  [WARN] Could not verify whether the running Codex app-server's model catalog is current (start time or catalog unreadable). Action: if the model list looks stale, restart Codex");
   } else if (catalogState.state === "fresh") {
@@ -1185,8 +1291,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
       }
     }
   }
-  if (pending.failed || pending.pendingRows > 0 || pending.backupEntries > 0) {
-    hints.push("Legacy chat threads are still tagged opencodex (or the DB was locked). The running proxy retries the migration automatically; to force it now, close the Codex app and run 'ocx sync'.");
+  if (pending.failed && pending.failureReason === "busy") {
+    hints.push("Backed-up history metadata is pending or its state is unreadable. The running proxy retries exact restoration automatically; to force it now, close the Codex app and run 'ocx sync'. Untracked routed history is not relabeled.");
+  } else if (pending.failed && pending.failureReason === "permission") {
+    hints.push("Backed-up history metadata could not be inspected because access was denied. Fix access to the reported Codex history paths, then run 'ocx sync'; repeated retries do not repair permissions.");
+  } else if (pending.failed) {
+    hints.push("The history manifest or its target is invalid or changed. Preserve both, inspect the manifest/database/rollout identity, and do not repeatedly run 'ocx sync' until the mismatch is understood. Untracked routed history is not relabeled.");
+  } else if (pending.backupEntries > 0) {
+    hints.push("Backed-up history metadata is pending. The running proxy retries exact restoration automatically; to force it now, close the Codex app and run 'ocx sync'. Untracked routed history is not relabeled.");
   }
   if (dual.dualInstall && !dual.effectiveIsWindowsMount) {
     hints.push(`Codex is installed on BOTH WSL and Windows. Each side keeps its own ~/.codex (logins, config, catalog are separate); ocx here manages the Linux one. To share a single home, set CODEX_HOME=${dual.windowsCodexHomes[0] ?? `${dual.automountRoot}/c/Users/<you>/.codex`} in WSL (drvfs file locking is less reliable).`);

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";
@@ -24,8 +31,8 @@ Usage:
   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)
-  ocx recover-history --legacy-openai
-                               Explicitly recover pre-backup syncResumeHistory rows
+  ocx recover-history --legacy-openai --yes
+                               Force all user-message opencodex rows to OpenAI (legacy recovery)
   ocx uninstall               Remove service/shim/config and restore native Codex (alias: remove)
   ocx service [sub]           Run as a background service (default: install/update/start)
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
@@ -49,21 +56,25 @@ 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
   ocx models <sub>            Live/custom models, visibility, context, and shadow calls
+  ocx alias <sub>             Short names for providers and models (list, set, rm, defaults)
   ocx combo <sub>             Combo failover/round-robin routing
   ocx agent <sub>             Subagents, 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 <7d|30d|all>]  Alias of ocx observe usage
-  ocx storage [--json]        Alias of ocx observe storage
+  ocx usage [--range <today|1d|7d|30d|all>] [--provider <name>] [--model <id>]
+                              Token and estimated-cost report (alias of ocx observe usage)
+  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
-  ocx export --client <id>    Print a client config wired to the running proxy (11 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (12 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates

package/src/cli/index.ts

@@ -12,6 +12,9 @@ import {
   codexAutoStartEnabled,
   getConfigDir,
   loadConfig,
+  saveConfig,
+} from "../config";
+import {
   readPid,
   readPidFileValue,
   readRuntimePort,
@@ -19,11 +22,11 @@ import {
   removePidIfValueIs,
   removeRuntimePort,
   removeRuntimePortIfPidIs,
-  saveConfig,
   writePid,
   writeRuntimePort,
-} from "../config";
-import { collectStatus } from "./status";
+} from "../config/process-state";
+import { collectStatus, unusedProxyWarningLines } from "./status";
+import { takeFlag } from "./runtime-api";
 
 import {
   discoverStableProxyForRestart,
@@ -43,8 +46,8 @@ 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 { startupHealthSummary } from "../codex/autostart-health";
+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";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
@@ -221,6 +224,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) {
@@ -828,8 +836,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);
   }
@@ -846,6 +858,18 @@ 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,
+  })) {
+    console.log(`   ${line}`);
+  }
   if (!(status.json.proxy.pid || status.json.proxy.health.ok)) {
     console.log("   ↳ Not running — Codex/Claude requests will fail with connection errors.");
     // The service summary a few lines below already tells a registered-but-not-serving
@@ -865,6 +889,7 @@ async function handleStatus() {
   console.log(`   Default provider: ${status.json.defaultProvider}`);
   console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}`);
   console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}`);
+  console.log(`   ${formatStartupRoutingDetail(status.json.startup)}`);
   console.log(`   Service: ${status.json.service.summary}`);
   console.log(`   ${status.json.codexShim.summary}`);
   console.log(`   Codex runtime: ${status.json.codexRuntime.path}`);
@@ -905,8 +930,13 @@ async function handleStatus() {
 
 async function handleRecoverHistory() {
   if (args[1] !== "--legacy-openai") {
-    console.error("Usage: ocx recover-history --legacy-openai");
-    console.error("Only use this if an older syncResumeHistory build already remapped OpenAI Codex App history to opencodex before backup support existed.");
+    console.error("Usage: ocx recover-history --legacy-openai --yes");
+    console.error("This force-relabels every user-message opencodex row to OpenAI, including legitimate dedicated-provider history. Back up first and use it only for pre-backup legacy recovery.");
+    process.exit(1);
+  }
+  console.error("WARNING: this force-relabels every user-message opencodex row to OpenAI, normalizes exec to cli, and includes legitimate dedicated-provider history.");
+  if (args.length !== 3 || args[2] !== "--yes") {
+    console.error("Re-run with explicit confirmation: ocx recover-history --legacy-openai --yes");
     process.exit(1);
   }
   // Manifest-independent legacy ejection, serialized like every other history

package/src/cli/init.ts

@@ -165,6 +165,7 @@ export async function runInit(): Promise<void> {
       port,
       providers: { [providerName]: providerConfig },
       defaultProvider: providerName,
+      modelDiscovery: { newModelPolicy: "off" },
     };
 
     saveConfig(config);

package/src/cli/inspect.ts

@@ -0,0 +1,230 @@
+/**
+ * `ocx system-surface` — the remaining routes that had no CLI caller at all (wp7).
+ *
+ * These are grouped by what an operator is trying to do, not by which server module owns them:
+ * inspecting effective configuration, reading the generated client-config snippet, toggling the
+ * native client integrations, checking request pacing and routing analytics, and reading the
+ * Codex system prompt.
+ *
+ * One route here is deliberately READ-ONLY forever. `POST /api/github/star` spends the operator's
+ * GitHub identity, and no CLI flag can carry that consent — the server requires a real dashboard
+ * session for it. So `star` reads status and says what it cannot do, rather than offering a
+ * `--yes` that would be a lie.
+ */
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx inspect config [--json]
+  ocx inspect catalog [--json]
+  ocx inspect routing-analytics [--json]
+  ocx inspect pacing [--name <provider>] [--json]
+  ocx inspect key-providers [--json]
+  ocx inspect codex-prompt [--text] [--json]
+  ocx inspect client-config --client <id> [--json]
+  ocx inspect star [--json]
+  ocx inspect windows-tray [--json]
+  ocx integration native [list] [--json]
+  ocx integration native <claude|claude-desktop|codex|grok> <on|off> [--json]
+  ocx agent request-user-input [on|off] [--json]`;
+
+/** A read that takes no arguments beyond `--json`. */
+async function read(path: string, argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest(path, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+const NATIVE_CLIENTS = ["claude", "claude-desktop", "codex", "grok"] as const;
+
+interface NativeClientRow {
+  clientId?: string;
+  state?: string;
+  installed?: boolean;
+  desiredEnabled?: boolean;
+  configPath?: string;
+  disableBlocked?: unknown;
+}
+
+/**
+ * The shared depth-1 flattener renders an array as "N item(s)", so a bare
+ * `integration native list` printed `clients: 4 item(s)` -- the per-client state the operator
+ * asked for was in the payload and discarded before the terminal. Same defect class wp4 fixed
+ * for the account and key tables.
+ */
+function nativeLines(payload: unknown): string[] {
+  const clients = (payload as { clients?: NativeClientRow[] } | null)?.clients;
+  if (!Array.isArray(clients) || clients.length === 0) return ["No native client integrations reported."];
+  const lines = ["CLIENT           STATE      INSTALLED  DESIRED  CONFIG"];
+  for (const row of clients) {
+    lines.push([
+      (row.clientId ?? "?").padEnd(16),
+      (row.state ?? "?").padEnd(10),
+      (row.installed === true ? "yes" : row.installed === false ? "no" : "?").padEnd(10),
+      (row.desiredEnabled === true ? "on" : row.desiredEnabled === false ? "off" : "?").padEnd(8),
+      row.configPath ?? "",
+    ].join(" ").trimEnd());
+    // A blocked disable is the reason a toggle did not take effect, so it is never silent.
+    if (row.disableBlocked !== null && row.disableBlocked !== undefined) {
+      lines.push(`  disable blocked: ${typeof row.disableBlocked === "string" ? row.disableBlocked : JSON.stringify(row.disableBlocked)}`);
+    }
+  }
+  return lines;
+}
+
+async function nativeIntegration(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const action = argv[0] && !argv[0].startsWith("-") ? argv[0] : "list";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+
+  if (action === "list") {
+    const args = [...rest];
+    const wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/native-integrations", {}, deps);
+    printData(result, wantsJson, nativeLines(result));
+    return;
+  }
+
+  if (!(NATIVE_CLIENTS as readonly string[]).includes(action)) {
+    throw new CliUsageError(`unknown native client ${action}; expected one of ${NATIVE_CLIENTS.join(", ")}`, USAGE);
+  }
+
+  const args = [...rest];
+  const wantsJson = takeFlag(args, "--json");
+  const state = args.shift();
+  rejectArgs(args, USAGE);
+  if (state !== "on" && state !== "off") {
+    throw new CliUsageError(`expected on or off after ${action}`, USAGE);
+  }
+
+  // Toggling rewrites the client's own config file, which is why each client has its own route
+  // rather than one route with a client parameter.
+  const result = await runtimeRequest(`/api/native-integrations/${action}`, {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ enabled: state === "on" }),
+  }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+/**
+ * Exported unwrapped so `ocx agent request-user-input` can call it INSIDE its own
+ * `runCliAction`. Wrapping an already-wrapped handler reports one failure twice: the inner
+ * wrapper prints the error and returns a code, and the outer one prints again on the rethrow.
+ */
+export async function requestUserInputAction(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const state = args.shift();
+  rejectArgs(args, USAGE);
+
+  const path = "/api/codex-auth/features/default-mode-request-user-input";
+  // No argument means show. A read must not write the value it is reporting.
+  if (state === undefined) {
+    const result = await runtimeRequest(path, {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  if (state !== "on" && state !== "off") throw new CliUsageError("expected on or off", USAGE);
+
+  const result = await runtimeRequest(path, {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ enabled: state === "on" }),
+  }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function clientConfig(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const client = takeOption(args, "--client");
+  rejectArgs(args, USAGE);
+  if (!client) throw new CliUsageError("--client is required", USAGE);
+  // The valid client list is not duplicated here: the route answers 400 naming every accepted id,
+  // which is more useful than a local list that can drift out of date.
+  const result = await runtimeRequest(`/api/client-config?client=${encodeURIComponent(client)}`, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function pacing(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const name = takeOption(args, "--name");
+  rejectArgs(args, USAGE);
+  const suffix = name ? `?name=${encodeURIComponent(name)}` : "";
+  const result = await runtimeRequest(`/api/provider-request-pacing${suffix}`, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function codexPrompt(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const asText = takeFlag(args, "--text");
+  rejectArgs(args, USAGE);
+  if (asText && wantsJson) throw new CliUsageError("--text and --json cannot be combined", USAGE);
+  if (asText) {
+    // The /text variant answers the prompt body itself, so it is printed verbatim rather than
+    // flattened through the summary renderer.
+    const result = await runtimeRequest<unknown>("/api/codex-prompt/text", {}, deps);
+    console.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+    return;
+  }
+  const result = await runtimeRequest("/api/codex-prompt", {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function star(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<Record<string, unknown>>("/api/github/star", {}, deps);
+  if (wantsJson) {
+    printData(result, true);
+    return;
+  }
+  printData(result, false, summaryLines(result));
+  // Said plainly, because the natural next question is "then star it", and the answer is that no
+  // CLI invocation can: the POST requires a dashboard session precisely so an agent cannot spend
+  // the operator's identity on their behalf.
+  console.log("Starring is not available from the CLI: it uses your GitHub identity, so only you can do it from the dashboard.");
+}
+
+export async function handleInspectCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const hasSub = argv[0] !== undefined && !argv[0].startsWith("-");
+    const sub = hasSub ? argv[0]! : "config";
+    const rest = hasSub ? argv.slice(1) : argv;
+    if (sub === "config") await read("/api/config", rest, deps);
+    else if (sub === "catalog") await read("/api/catalog", rest, deps);
+    else if (sub === "routing-analytics") await read("/api/routing-analytics", rest, deps);
+    else if (sub === "key-providers") await read("/api/key-providers", rest, deps);
+    else if (sub === "windows-tray") await read("/api/windows-tray", rest, deps);
+    else if (sub === "pacing") await pacing(rest, deps);
+    else if (sub === "client-config") await clientConfig(rest, deps);
+    else if (sub === "codex-prompt") await codexPrompt(rest, deps);
+    else if (sub === "star") await star(rest, deps);
+    else throw new CliUsageError(`unknown inspect command ${sub}`, USAGE);
+  });
+}
+
+export async function handleIntegrationCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub, ...rest] = argv;
+    if (sub === "native" || sub === undefined) await nativeIntegration(sub === undefined ? [] : rest, deps);
+    else throw new CliUsageError(`unknown integration command ${sub}`, USAGE);
+  });
+}
+
+export const INSPECT_USAGE = USAGE;