@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/registry.ts

@@ -144,18 +144,19 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Port: ocx link port [--json]",
       "Issue: ocx link issue --alias <alias> --tunnel-port <port> [--json]",
       "Status: ocx link status [--json]",
-      "Revoke: ocx link revoke --link-id <id> [--json]",
+      "Revoke: ocx link revoke --link-id <id> [--force --yes] [--json]",
       "Issue, status, and revoke use the running proxy's loopback management API and admin token.",
     ],
   },
   {
     name: "remote-workspace",
-    usage: "ocx remote-workspace <pair|agent|status>",
-    summary: "Pair this OCX-only computer with a hub and run its remote workspace executor.",
+    usage: "ocx remote-workspace <pair|agent|status|hub>",
+    summary: "Manage this workspace executor or inspect the selected Hub.",
     details: [
       "Pair: ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--toolchain-root <absolute-directory>] [--executor-helper <absolute-file>] [--name <device-name>]",
       "Agent: ocx remote-workspace agent",
       "Status: ocx remote-workspace status [--json]",
+      "Hub: ocx remote-workspace hub <status|runtimes|sessions> [--json]",
       "Codex, Claude Code, Pi, provider logins, and API keys remain on the hub; only workspace tools execute here.",
     ],
   },
@@ -282,10 +283,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "  list                  List configured and available providers",
       "  add <name>            Add a provider (registry or custom)",
       "  edit <name>           Edit live provider fields",
+      "  pacing <name>         Read/edit live request pacing rules",
+      "  snapshot              Read a non-secret provider editor baseline",
+      "  apply                 Apply edited providers with baseline conflict checks",
       "  test <name>           Test the provider's upstream model endpoint",
       "  remove <name>         Remove a configured provider",
       "  show <name>           Show provider config details",
       "  set-default <name>    Change the default provider",
+      "  add/remove/set-default support --live; live removal also requires --yes.",
       "  selected <name>       Show or set the provider model allowlist",
       "  quota                 Show provider quota reports",
       "  resets                Show recently detected quota resets",
@@ -299,6 +304,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "  ocx provider add anthropic --api-key <key>",
       "  ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1",
       "  ocx provider show anthropic --json",
+      "  ocx provider pacing anthropic --json",
+      "  ocx provider snapshot --json",
       "  ocx provider set-default anthropic",
       "  ocx provider edit xai --xai-chat on   # opt Grok 4.5/4.6 into Chat Completions",
       "  ocx provider edit xai --xai-chat off  # use Responses again",
@@ -320,6 +327,11 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.",
       "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
       "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+      "pool <provider>          Read/edit runtime-supported pool policy.",
+      "credits openai ...       Explicit paid-credit-after-limit policy; separate from displaying balances.",
+      "quota-activation openai  Enable/disable one account reset-window refresh policy.",
+      "anthropic-reset-grants   Read grant status only; consumption remains in the dashboard.",
+      "login supports explicit browser/add-account options only for applicable flows; human verification remains required.",
       "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
       "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
       "grok-reset-coupons [<id>] [--consume --yes] Inspect or redeem Grok reset coupons.",
@@ -340,6 +352,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "List models and manage custom (manually registered) models.",
     details: [
       "List available models from static config with no subcommand (liveModels may add more at runtime).",
+      "add/remove support --live for the selected proxy; live or JSON removal requires --yes.",
+      "Local add/remove JSON reports saved state and opportunistic sync; no proxy keeps the save successful/pending.",
+      "display-name <provider/raw-model> --set <label> or --clear changes an exact upstream model label.",
+      "order status/set/reset manages routed picker order; reset native-inclusive saved order before replacement.",
       "add: register a model the provider catalog does not advertise yet.",
       "  --display-name <name>     Human label (no slashes).",
       "  --context-window <tokens> e.g. 200000.",
@@ -357,12 +373,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "companion",
-    usage: "ocx companion <show|set|reset> ...",
-    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    usage: "ocx companion <show|set|reset|usage|timeline> ...",
+    summary: "Inspect companion settings, filtered usage and timeline, or change preferences.",
     details: [
       "ocx companion and ocx companion show read settings; use --json for machine-readable output.",
       "ocx companion set accepts one or more key=value assignments; values are parsed as JSON when possible.",
       "ocx companion reset restores the default settings.",
+      "ocx companion usage reads today and 30-day totals with saved model/provider filters; unavailable ranges return partial output and exit 1.",
+      "ocx companion timeline reads buckets; --model selects models and --hide-provider excludes providers.",
     ],
   },
   {
@@ -373,8 +391,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "route",
-    usage: "ocx route combo <list|show|set|remove> ...",
-    summary: "Manage routing features; combo is currently the supported routing resource.",
+    usage: "ocx route <combo|policy> <subcommand>",
+    summary: "Manage combo routing and routing profiles.",
   },
   {
     name: "effort",
@@ -407,10 +425,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "`inspect star` reads the repository star status only. Starring uses your GitHub identity and is available from the dashboard alone.",
     ],
   },
-  { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Read or follow request logs (alias of ocx observe logs)." },
+  { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl|--events]", summary: "Read or follow request logs." },
   {
     name: "usage",
-    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]",
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
     summary: "Report token usage and estimated cost (alias of ocx observe usage).",
   },
   {
@@ -425,14 +443,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
   {
     name: "access",
-    usage: "ocx access <key|endpoints|models|test> ...",
+    usage: "ocx access <key|endpoints|models|test|audio> ...",
     summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
     details: [
       "Key rotation start uses POST /api/keys/rotate and returns the replacement secret once.",
       "Commit uses POST /api/keys/rotate/commit; abort uses DELETE /api/keys/rotate with the returned rotation id.",
+      "key rename changes a masked key's name without clearing its scopes.",
+      "test --api-key-stdin uses one supplied data key; it never substitutes management or enrolled credentials.",
+      "audio transcribe/live-check use explicit piped key input and may use provider quota; authorize the operation first.",
     ],
   },
-  { name: "api-key", usage: "ocx api-key <list|create|rotate|remove> ...", summary: "Alias of ocx access key." },
+  { name: "api-key", usage: "ocx api-key <list|get|create|set|rename|rotate|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "api",
     usage: "ocx api <protocols|explain|policy> ...",
@@ -468,14 +489,18 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "Manage supported client integrations, and the native client toggles.",
     details: [
       "`native` shows or flips the native Claude/Claude Desktop/Codex/Grok toggles; the other subcommands manage the reversible file integrations.",
+      "client preview shows a proposed change; enable/disable/restore accept an optional --plan-fingerprint.",
+      "client history remove requires --yes; client sync --client aside refreshes managed Aside profiles.",
+      "native cursor status/local-installer are reads; installer lookup does not install anything.",
     ],
   },
   {
     name: "system",
-    usage: "ocx system <status|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...",
+    usage: "ocx system <status|health|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...",
     summary: "Manage headless runtime settings, startup, sync, diagnostics, OpenCodex updates, and read-only Codex CLI inspection.",
     details: [
       "system update manages OpenCodex itself.",
+      "system health reads authenticated service and spend-ledger diagnostics; root health remains liveness.",
       "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]",
@@ -484,9 +509,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "config",
-    usage: "ocx config <show|get|set|unset|validate|export|import> ...",
+    usage: "ocx config [show|get|set|unset|validate|export|import] ...",
     summary: "Inspect and safely modify validated OpenCodex configuration.",
-    details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
+    details: [
+      "show is the default: ocx config [show] [--json] [--source]. Flags alone also display the local configuration without a running proxy.",
+      "--json may precede an explicit action without changing which action runs.",
+      "--source is only supported for show and includes diagnostic source, error, and warning fields.",
+      "Secrets are masked by show/get. Import requires --yes and validates before writing.",
+    ],
   },
   {
     name: "claude",
@@ -511,6 +541,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "  ocx claude desktop default <family> <route|none>",
       "  ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
       "  ocx claude desktop import <path> [--apply]         Validate and import JSON",
+      "  ocx claude desktop profile show [--json]           Read the running proxy's profile",
+      "  ocx claude desktop profile import <file|-> [--json] Save the running profile without applying",
       "Families: opus, fable, sonnet, haiku. New routes start in opus.",
       "`none` is valid only when that family is empty.",
       "Legacy apply flags remain supported: --static, --hybrid, --discovery-only.",
@@ -527,7 +559,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "and `providers.opencodex` blocks injected through OpenCode's inline runtime layer",
       "(`OPENCODE_CONFIG_CONTENT`). Any existing inline config in the environment is preserved",
       "and only `provider.opencodex` and `providers.opencodex` are overwritten for this launch.",
-      "Only the V2 block (`providers.opencodex`) carries the reasoning-effort variants.",
+      "V1 receives reasoning-effort variant maps; V2 receives native variant arrays for the same declared choices and defaults.",
       "Global/project opencode.json may be read to warn about an existing provider.opencodex or",
       "providers.opencodex override; on-disk files are never modified.",
       "Routed models appear in the model picker as opencodex/<provider>/<model>.",
@@ -560,8 +592,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "Connect ZCode (Z.ai desktop client) to the proxy via its managed provider.",
     details: [
       "Alias of ocx integration client <sub> --client zcode.",
-      "enable writes the managed provider.opencodex block into ~/.zcode/v2/config.json; disable removes only that block.",
-      "ZCode 3.14 moved its providers to ~/.zcode/v2/provider_config.json; where that file exists, enable is refused because the write cannot reach the client.",
+      "enable manages ~/.zcode/v2/provider_config.json with schemaVersion 1; if the store is absent, it writes the legacy provider.opencodex block into ~/.zcode/v2/config.json.",
+      "A surviving owned legacy block prevents switching stores. Run `ocx zcode disable` before enabling the current store. Unknown store schemas are refused.",
       "ZCode reads its config at startup — restart ZCode after enable/disable.",
       "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
     ],
@@ -569,7 +601,13 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   {
     name: "restart",
     usage: "ocx restart",
-    summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
+    summary: "Request a graceful restart of the verified running proxy, preserving routing.",
+    details: [
+      "If no proxy is running, use the normal `ocx ensure` start policy, including the Codex autostart setting.",
+      "Unverifiable running targets are refused without a stop/start fallback.",
+      "Restarting an older proxy from this newer CLI requires standalone macOS/Linux proxies; supervised, shared, foreground, or unverifiable targets are refused.",
+      "For a service-managed update, run `ocx service restart`; for a desktop-managed update, restart through the OpenCodex desktop app.",
+    ],
   },
   {
     name: "v2",
@@ -628,8 +666,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "lab",
-    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
-    summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
+    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog|production-signals|public|automation|run> [options] [--json]",
+    summary: "Inspect local Compatibility Lab evidence and explicitly control automation.",
     details: [
       "status                Projection availability, schema versions, and row counts.",
       "verdicts              Paginated derived compatibility verdicts with filters.",
@@ -638,6 +676,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "events                Event history; event <id> returns one safe typed event.",
       "artifacts             Artifact metadata only (no content download).",
       "catalog               Packaged protocol/live scenario catalog metadata.",
+      "production-signals    Local passive routing evidence for a subject.",
+      "public                Preview/export local evidence; verify/import a bundle.",
+      "automation            Read status/runs or explicitly enable/disable local policy.",
+      "run                   Explicit manual scenario; live probes can consume quota.",
       "Reads never rebuild the projection, trigger probes, or require the proxy.",
     ],
   },

package/src/cli/remote-workspace-hub.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { REMOTE_WORKSPACE_CAPABILITIES, isRemoteWorkspaceToolName } from "../remote-control/workspace-tools";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, RuntimeApiError, printData, rejectArgs, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+export const REMOTE_WORKSPACE_HUB_USAGE = "Usage: ocx remote-workspace hub [status|runtimes|sessions] [--json]";
+const UNAVAILABLE = "Remote Workspace requires Hub mode and OCX_REMOTE_WORKSPACE_ENABLED=1. Run this command on the intended Hub.";
+const identity = z.string().min(1);
+const capabilities = z.array(z.enum(REMOTE_WORKSPACE_CAPABILITIES));
+const root = z.object({ id: identity, label: z.string() });
+const device = z.object({
+  id: identity, name: z.string(), platform: z.string(), capabilities, roots: z.array(root),
+  online: z.boolean(), createdAt: z.string(), lastSeenAt: z.string().nullable(),
+});
+const availability = z.object({ available: z.boolean(), version: z.string().optional(), reason: z.string().optional() });
+const runtimes = z.object({ codex: availability, claude: availability, pi: availability });
+const event = z.object({ sequence: z.number().int().nonnegative(), at: z.string(),
+  type: z.enum(["status", "assistant", "tool", "error"]), text: z.string() });
+const session = z.object({
+  id: identity, profile: z.enum(["codex", "claude", "pi"]), accessMode: z.enum(["read-only", "workspace"]),
+  deviceId: identity, deviceName: z.string(), rootId: identity, rootLabel: z.string(), capabilities,
+  tools: z.array(z.custom<string>(isRemoteWorkspaceToolName)), threadId: z.string().nullable(),
+  resumable: z.boolean(), status: z.enum(["starting", "ready", "running", "waiting_for_executor", "failed", "stopped"]),
+  createdAt: z.string(), updatedAt: z.string(), events: z.array(event),
+});
+const sessions = z.array(session);
+const status = z.object({ available: z.literal(true), devices: z.array(device), runtimes, sessions });
+const unavailable = z.object({ available: z.literal(false), reason: z.string(),
+  devices: z.array(z.unknown()).length(0), runtimes: z.object({}).strict(), sessions: z.array(z.unknown()).length(0) });
+
+/** Hub observations use management admission; executor pairing and session writes remain separate. */
+export async function handleRemoteWorkspaceHubCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const wantsJson = takeFlag(args, "--json");
+    const action = args.shift() ?? "status";
+    rejectArgs(args, REMOTE_WORKSPACE_HUB_USAGE);
+    if (!["status", "runtimes", "sessions"].includes(action)) {
+      throw new CliUsageError("Expected Hub status, runtimes or sessions", REMOTE_WORKSPACE_HUB_USAGE);
+    }
+    const path = `/api/remote-workspace${action === "status" ? "" : `/${action}`}`;
+    let raw: unknown;
+    try {
+      raw = await runtimeRequest(path, { redirect: "error" }, deps);
+    } catch (error) {
+      // The inner owner can refuse after activation changed; the outer owner uses a 200 observation.
+      if (error instanceof RuntimeApiError && error.status === 409) {
+        console.error(`Error: ${UNAVAILABLE}`);
+        return 5;
+      }
+      throw error;
+    }
+    if (unavailable.safeParse(raw).success) {
+      printData({ available: false, reason: UNAVAILABLE, devices: [], runtimes: {}, sessions: [] }, wantsJson, [UNAVAILABLE]);
+      return 1;
+    }
+    if (action === "status") {
+      const parsed = status.safeParse(raw);
+      if (!parsed.success) throw new Error("Invalid Hub observation");
+      const data = parsed.data;
+      printData(data, wantsJson, [
+        `Remote Workspace Hub: ${data.devices.length} device(s), ${data.sessions.length} session(s).`,
+        ...data.devices.map(row => `${row.id}  ${row.name}: ${row.online ? "online" : "offline"} (${row.roots.length} workspace root(s))`),
+        ...(data.devices.length ? [] : ["No paired devices. Pair a device from the Hub dashboard."]),
+        ...Object.entries(data.runtimes).map(([name, row]) => `${name}: ${row.available ? "available" : "unavailable"}${row.version ? ` (${row.version})` : ""}`),
+      ]);
+      return 0;
+    }
+    if (action === "runtimes") {
+      const parsed = z.object({ runtimes }).safeParse(raw);
+      if (!parsed.success) throw new Error("Invalid runtime observation");
+      printData(parsed.data, wantsJson, Object.entries(parsed.data.runtimes).map(([name, row]) =>
+        `${name}: ${row.available ? "available" : "unavailable"}${row.version ? ` (${row.version})` : ""}${row.reason ? ` — ${row.reason}` : ""}`));
+      return 0;
+    }
+    const parsed = z.object({ sessions }).safeParse(raw);
+    if (!parsed.success) throw new Error("Invalid session observation");
+    printData(parsed.data, wantsJson, parsed.data.sessions.length
+      ? parsed.data.sessions.map(row => `${row.id}  ${row.profile}: ${row.status} (${row.deviceName} / ${row.rootLabel}, ${row.accessMode})`)
+      : ["No Remote Workspace sessions. Create a session from the Hub dashboard."]);
+    return 0;
+  });
+}

package/src/cli/remote-workspace.ts

@@ -22,7 +22,8 @@ import {
 export const REMOTE_WORKSPACE_USAGE = `Usage:
   ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--root <absolute-path> ...] [--toolchain-root <absolute-directory> ...] [--executor-helper <absolute-file>] [--name <device-name>] [--json]
   ocx remote-workspace agent
-  ocx remote-workspace status [--json]`;
+  ocx remote-workspace status [--json]
+  ocx remote-workspace hub [status|runtimes|sessions] [--json]`;
 
 export interface RemoteWorkspaceCliDeps extends RuntimeApiDeps {
   store?: RemoteWorkspaceDeviceStateStore;
@@ -76,6 +77,10 @@ function publicStatus(state: RemoteWorkspaceDeviceState | null): Record<string,
 export async function runRemoteWorkspaceCommand(rawArgs: string[], deps: RemoteWorkspaceCliDeps = {}): Promise<number> {
   const args = [...rawArgs];
   const command = args.shift();
+  if (command === "hub") {
+    const { handleRemoteWorkspaceHubCommand } = await import("./remote-workspace-hub");
+    return handleRemoteWorkspaceHubCommand(args, deps);
+  }
   const store = deps.store ?? new RemoteWorkspaceDeviceFileStore();
   if (command === "status") {
     const wantsJson = takeJsonFlag(args);

package/src/cli/restart-failure.ts

@@ -0,0 +1,27 @@
+import type { ProxyRestartResult } from "./tray-proxy";
+
+export const INCOMPLETE_INSTALL_RECOVERY = "If the installer already exited or failed, run `ocx status`, stop any running proxy through its owner (`ocx stop`, or its service or desktop app), then reinstall with the same package manager and start it again (see https://opencodex.me/troubleshooting/update-failed/).";
+
+export function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: false }>): void {
+  if (result.phase === "identity") {
+    console.error("Refusing to restart because the running proxy identity could not be attested. Run `ocx status` to inspect the intended proxy.");
+  } else if (result.phase === "request") {
+    const code = result.error instanceof Error ? result.error.message : "";
+    if (code === "restart_capability_unsupported") {
+      console.error("The running proxy predates process-bound restart support; no unsafe fallback was attempted.");
+      console.error("   After confirming this home owns the proxy, run `ocx stop` and then `ocx start` once.");
+    } else if (code === "restart_version_skew") {
+      console.error("This CLI is older than the running proxy (or versions cannot be compared). Use the newer installation's ocx to restart; check `which -a ocx` and run `ocx status`. No changes were made.");
+    } else if (code === "update_restart_home_unverified") {
+      console.error("The proxy home or lifecycle ownership could not be verified. Run `ocx status`; if a service owns the proxy, use its installation's `ocx service restart`, otherwise use the owning app or supervisor. No changes were made.");
+    } else if (code === "restart_package_tree_unsettled") {
+      console.error(`The proxy's package files are unsettled. Wait for the install to finish, then run \`ocx restart\`. ${INCOMPLETE_INSTALL_RECOVERY}`);
+    } else {
+      console.error("Proxy restart request could not be confirmed; no fallback stop/start was attempted. Run `ocx status` to inspect ownership and runtime state.");
+    }
+  } else if (result.phase === "replacement") {
+    console.error("Proxy restart was accepted, but no identity-verified replacement became healthy in time. Run `ocx status` to inspect the replacement.");
+  } else {
+    console.error("Proxy was not running and the fallback start did not become healthy. Run `ocx status` to inspect startup state.");
+  }
+}

package/src/cli/root.ts

@@ -15,6 +15,7 @@ import { parseStopApproval } from "./stop-approval";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 import { findCommand } from "./registry";
 import { printUnknownCommand } from "./help-recovery";
+import { noteCredentialArgv, redactSecretArgs } from "./secret-args";
 
 export interface CliHead {
   kind: "version" | "help" | "ready" | "resolve" | "command";
@@ -78,7 +79,13 @@ export function parseCliHead(argv: string[]): CliHead {
   return { kind: "command", command, args };
 }
 
+export function uninstallArgsError(command: string | undefined, args: string[]): string | undefined {
+  if ((command !== "uninstall" && command !== "remove") || args.length <= 1) return undefined;
+  return `ocx ${command} does not accept arguments (got: ${redactSecretArgs(args.slice(1)).join(" ")}). No changes were made. See: ocx help ${command}`;
+}
+
 export async function runCli(argv: string[]): Promise<CliHead> {
+  noteCredentialArgv(argv);
   const head = parseCliHead(argv);
   switch (head.kind) {
     case "version":
@@ -129,6 +136,11 @@ export async function runCli(argv: string[]): Promise<CliHead> {
         console.error("Usage: ocx stop [--json [--expect-pid <pid> --expect-port <port> --expect-hostname <host> --expect-config-home <home> --expect-cli-version <version> --expect-compatibility-token <hex>]]");
         process.exit(64);
       }
+      const uninstallError = uninstallArgsError(head.command, head.args);
+      if (uninstallError) {
+        console.error(uninstallError);
+        process.exit(2);
+      }
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
   }

package/src/cli/route-policy-write.ts

@@ -0,0 +1,137 @@
+/** Explicit create/replace/delete for routing profiles; contextual validation stays server-owned. */
+import { isValidPolicyId } from "../routing/profile";
+import { printCatalogResult, runCatalogAction } from "./catalog-command-result";
+import { readJsonInput, serializeManagementJson } from "./json-input";
+import { CliUsageError, runtimeBaseUrl, runtimeRequest, takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx route policy create <id> --file <profile.json|-> [--json]
+  ocx route policy update <id> --file <profile.json|-> --expected-revision <revision> [--json]
+  ocx route policy remove <id> --yes [--json]`;
+const ERRORS: Readonly<Record<string, string>> = {
+  profile_exists: "Routing profile already exists. Use show and review an explicit update.",
+  profile_revision_conflict: "Routing profile changed. Read show again and review the changes before updating with its revision.",
+  unknown_profile: "Routing profile was not found on the selected target.",
+  invalid_profile: "The target refused the profile. Check its candidates, alias and policy settings against the target configuration.",
+  missing_profile_id: "A routing profile id is required.",
+  invalid_profile_mode: "The target refused the routing profile operation.",
+  alias_reference_conflict: "The alias change conflicts with existing model references. Resolve the conflicting mappings first.",
+  invalid_shadow_call_target: "The alias change would create an invalid shadow-call target. Inspect its routing references first.",
+};
+const PROFILE_KEYS = ["alias", "candidates", "require", "optimize", "limits", "unknownEvidence", "compatibility"];
+const REQUIRE_KEYS = ["minContextWindow", "minQuotaHeadroom", "tools", "imageInput", "structuredOutput", "reasoningEffort", "serviceTier", "localOnly", "remoteAllowed", "encryptedCodexTasks"];
+const WEIGHT_KEYS = ["latency", "health", "cost", "quota"];
+const UNKNOWN_KEYS = ["capability", "health", "quota", "cost"];
+const COMPATIBILITY_KEYS = ["requiredSuites", "minStatus", "maxEvidenceAgeMs", "unknownEvidence", "degradedEvidence"];
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+function only(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  return record(value) && Object.keys(value).every(key => keys.includes(key));
+}
+function text(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0; }
+function nonnegative(value: unknown): value is number { return typeof value === "number" && Number.isFinite(value) && value >= 0; }
+function evidence(value: unknown): boolean { return value === "allow" || value === "penalize" || value === "exclude"; }
+function optionalFields(value: Record<string, unknown>, validators: Record<string, (value: unknown) => boolean>): boolean {
+  return Object.entries(validators).every(([key, accepts]) => !Object.hasOwn(value, key) || accepts(value[key]));
+}
+
+/** Shape/ownership only: do not invent a provider configuration to run contextual validators. */
+function editableProfile(value: unknown): value is Record<string, unknown> {
+  if (!only(value, PROFILE_KEYS) || !Array.isArray(value.candidates) || !value.candidates.length
+    || !value.candidates.every(candidate => only(candidate, ["provider", "model"]) && text(candidate.provider) && text(candidate.model))) return false;
+  if (Object.hasOwn(value, "alias") && typeof value.alias !== "string") return false;
+  if (Object.hasOwn(value, "require")) {
+    const required = value.require;
+    if (!only(required, REQUIRE_KEYS) || !optionalFields(required, {
+      minContextWindow: n => Number.isSafeInteger(n) && (n as number) > 0,
+      minQuotaHeadroom: n => nonnegative(n) && n <= 1,
+      reasoningEffort: n => typeof n === "string", serviceTier: n => typeof n === "string",
+    })) return false;
+    for (const key of ["tools", "imageInput", "structuredOutput", "localOnly", "remoteAllowed", "encryptedCodexTasks"]) {
+      if (Object.hasOwn(required, key) && typeof required[key] !== "boolean") return false;
+    }
+  }
+  if (Object.hasOwn(value, "optimize") && (!only(value.optimize, WEIGHT_KEYS) || !Object.values(value.optimize).every(nonnegative))) return false;
+  if (Object.hasOwn(value, "limits") && (!only(value.limits, ["maxEstimatedCostUsd", "onUnknownCost"])
+    || !optionalFields(value.limits, { maxEstimatedCostUsd: nonnegative, onUnknownCost: n => n === "allow" || n === "exclude" }))) return false;
+  if (Object.hasOwn(value, "unknownEvidence") && (!only(value.unknownEvidence, UNKNOWN_KEYS) || !Object.values(value.unknownEvidence).every(evidence))) return false;
+  if (Object.hasOwn(value, "compatibility")) {
+    const compatibility = value.compatibility;
+    if (!only(compatibility, COMPATIBILITY_KEYS) || !optionalFields(compatibility, {
+      requiredSuites: n => Array.isArray(n) && n.every(suite => only(suite, ["suiteId", "evidenceLayer"])
+        && text(suite.suiteId) && ["protocol_conformance", "live_route_compatibility"].includes(suite.evidenceLayer as string)),
+      minStatus: n => n === "PROBED" || n === "VERIFIED",
+      maxEvidenceAgeMs: n => Number.isSafeInteger(n) && (n as number) >= 0,
+      unknownEvidence: evidence, degradedEvidence: evidence,
+    })) return false;
+  }
+  return true;
+}
+
+function invalidResult(): never { throw new Error("Invalid routing profile result"); }
+
+function projectProfile(value: unknown, id: string, model: unknown): Record<string, unknown> {
+  if (!only(value, [...PROFILE_KEYS, "id", "model", "revision"]) || value.id !== id
+    || !text(value.revision) || !text(model) || value.model !== model
+    || (value.alias !== null && !text(value.alias))) invalidResult();
+  const { id: _id, model: _model, revision: _revision, alias, ...editable } = value;
+  const input = { ...editable, ...(alias === null ? {} : { alias }) };
+  if (!editableProfile(input) || model !== (alias ?? `policy/${id}`)
+    || !record(value.require) || !record(value.limits)
+    || !record(value.optimize) || !WEIGHT_KEYS.every(key => Object.hasOwn(value.optimize as object, key))
+    || !record(value.unknownEvidence) || !UNKNOWN_KEYS.every(key => Object.hasOwn(value.unknownEvidence as object, key))) invalidResult();
+  if (value.compatibility !== undefined && (!record(value.compatibility)
+    || !Array.isArray(value.compatibility.requiredSuites) || !evidence(value.compatibility.unknownEvidence)
+    || !evidence(value.compatibility.degradedEvidence))) invalidResult();
+  // Every nested field was admitted above; rebuild the envelope rather than echoing server metadata.
+  return { id, model, revision: value.revision, alias, ...editable };
+}
+
+function printResult(value: unknown, id: string, remove: boolean, wantsJson: boolean): number {
+  if (!only(value, remove ? ["success", "id", "catalogRefresh"] : ["success", "id", "model", "profile", "catalogRefresh"])
+    || value.success !== true || value.id !== id) invalidResult();
+  const data: Record<string, unknown> = { success: true, id };
+  const lines = [remove ? `Removed routing profile: ${id}` : `Saved routing profile: ${id}`];
+  if (!remove) {
+    data.profile = projectProfile(value.profile, id, value.model);
+    data.model = value.model;
+    lines.push(`Model: ${value.model}`, `Revision: ${(data.profile as Record<string, unknown>).revision}`);
+  }
+  return printCatalogResult(data, value.catalogRefresh, wantsJson, lines);
+}
+
+export async function handleRoutePolicyWriteCommand(
+  sub: "create" | "update" | "remove", argv: string[], deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const id = args.shift();
+    if (!id || !isValidPolicyId(id)) throw new CliUsageError("A valid exact routing profile id is required (letters, numbers, dot, underscore or hyphen; max 64).", USAGE);
+    const wantsJson = takeFlag(args, "--json");
+    const yes = takeFlag(args, "--yes");
+    const file = takeOptionWithSyntax(args, "--file")?.value;
+    const revision = takeOptionWithSyntax(args, "--expected-revision")?.value;
+    if (args.length) throw new CliUsageError("Unknown, repeated or unexpected routing profile arguments.", USAGE);
+    if (sub === "remove") {
+      if (!yes || file !== undefined || revision !== undefined) throw new CliUsageError("Removal requires --yes and does not accept a file or revision.", USAGE);
+    } else {
+      if (yes || !file?.trim()) throw new CliUsageError("Creation and update require --file and do not accept --yes.", USAGE);
+      if (sub === "update" ? !revision?.trim() : revision !== undefined) throw new CliUsageError("Update requires an explicit nonblank --expected-revision; create does not accept it.", USAGE);
+    }
+    let body: string | undefined;
+    if (sub !== "remove") {
+      const profile = await readJsonInput(file!, deps);
+      if (!editableProfile(profile)) throw new CliUsageError("Profile file must contain only editable routing fields with valid nested types; omit id, model and revision.", USAGE);
+      body = serializeManagementJson({ id, mode: sub, profile, ...(sub === "update" ? { expectedRevision: revision } : {}) });
+    }
+    const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    const result = await runtimeRequest(sub === "remove" ? `/api/routing-profiles?id=${encodeURIComponent(id)}` : "/api/routing-profiles", {
+      method: sub === "remove" ? "DELETE" : "PUT", redirect: "error",
+      ...(body !== undefined ? { headers: { "content-type": "application/json" }, body } : {}),
+    }, pinned);
+    return printResult(result, id, sub === "remove", wantsJson);
+  }, ERRORS);
+}

package/src/cli/route-policy.ts

@@ -11,6 +11,9 @@ import {
 } from "./runtime-api";
 
 const USAGE = `Usage:
+  ocx route policy create <id> --file <FILE|-> [--json]
+  ocx route policy update <id> --file <FILE|-> --expected-revision <revision> [--json]
+  ocx route policy remove <id> --yes [--json]
   ocx route policy list [--json]
   ocx route policy show <id> [--json]
   ocx route policy dry-run <id> [--model-context <tokens>] [--tools]
@@ -83,6 +86,11 @@ async function dryRun(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleRoutePolicyCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const [write, ...rest] = argv;
+  if (write === "create" || write === "update" || write === "remove") {
+    const { handleRoutePolicyWriteCommand } = await import("./route-policy-write");
+    return handleRoutePolicyWriteCommand(write, rest, deps);
+  }
   return runCliAction(async () => {
     const [sub, ...rest] = argv;
     if (!sub) throw new CliUsageError("route policy requires a subcommand (list, show, dry-run, evaluate)", USAGE);