@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/cli/capabilities-agents-routing.ts

@@ -25,6 +25,27 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
       "queued means submitted, not processed. unknown must not be replayed; no automatic retry, daemon start or thread resume.",
       "Exit 0: queued; 1: not sent; 3: unknown; 64: invalid usage. No remote/Claude transport or skill installation."],
   },
+  {
+    command: ["advisor"],
+    summary: "Inspect and configure the advisor sidecar (expert consultation for routed workers).",
+    routes: [
+      { method: "GET", path: "/api/advisor/settings" },
+      { method: "GET", path: "/api/advisor/activity" },
+      { method: "PUT", path: "/api/advisor/settings" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit advisor settings as JSON." }],
+    mutates: true,
+    json: "payload",
+    details: [
+      "`status` (the default) reads the resolved settings; `on`/`off` toggle the sidecar; `consent` records or revokes context-sharing consent; `set` updates model, effort, policy, or timeout.",
+      "`on` does not grant consent. Without current consent it refuses and prints the disclosure. `on --ack-context-sharing` records consent v1 and enables. `consent --revoke` removes consent and stops task-context transfer.",
+      "The advisor model may be any routable model string: a bare native model, an explicit `provider/model`, or an account-qualified native model.",
+      "`policy: preflight` makes OpenCodex attempt one automatic consultation per task with a stable conversation identity once the task shows orientation evidence (an assistant tool call or a tool result after the latest user message). Without a stable identity, each eligible request may trigger another consultation. `policy: manual` consults only when the worker calls the synthetic `advisor` tool. Neither path sends task context without current context-sharing consent.",
+      "`policy: adaptive` adds evidence-based failed-repair consultation after the same validation fails, a file edit completes, and validation fails again. Automatic calls require a stable conversation identity. `set --max-consultations <1-3>` caps adaptive task attempts, including manual calls, in a durable 24-hour budget. No semantic stuck detection is claimed.",
+      "`activity` reads up to 100 recent consultation metadata records (trigger, status, models, requested and mapped effort, duration, reported tokens); no task or advice content is retained. Records are process-local and expire after 24 hours. Missing mapped effort means unreported, not successful application.",
+    ],
+  },
+
   {
     command: ["agent", "status"],
     usage: "ocx agent status [--json]",
@@ -277,10 +298,10 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["combo","set"],
-    usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--display-name <label|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--json]",
+    usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--json]",
     summary: "Create, update or rename a combo.",
     routes: [{"method":"GET","path":"/api/combos"},{"method":"PUT","path":"/api/combos"}],
-    flags: [{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."}],
+    flags: [{"name":"--allow-metered-targets","value":"string","summary":"on grants operator consent to metered targets only on a loopback-only proxy; off clears it."},{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."}],
     mutates: true,
     json: "payload",
     details: ["create and update are aliases of set. Existing fields are read before writing; --targets replaces targets.","force overrides valid client effort and may increase cost and latency.","Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks.","New file/flag conflicts refuse before transport. Partial edits preserve target metadata; explicit false/default values override server carry. Turning a native alias off may also require clearing its incompatible alias.","Read/merge/write uses one target and remains an upsert without revision CAS. Saved-but-incomplete catalog outcomes return nonzero with their receipt."],

package/src/cli/capabilities-base.ts

@@ -19,6 +19,15 @@ export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
  * A capability must not name a route the command does not actually fetch.
  */
 export const CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["codex-provider"],
+    bannerLines: ["ocx codex-provider <sub>    Confirm custom Codex provider routing: status|allow|revoke"],
+    summary: "Inspect, allow or revoke custom Codex provider routing consent.",
+    routes: [], flags: [{ name: "--yes", value: "boolean", summary: "Explicitly approve the named provider without an interactive prompt." }],
+    mutates: true, json: "none",
+    usage: "ocx codex-provider <status|allow <id> [--yes]|revoke <id>>",
+    details: ["Only local loopback routing for Responses providers using OpenAI authentication is supported. No custom credentials/headers, authless mode or client compaction. Unapproved providers are never changed."],
+  },
   {
     command: ["chatgpt"],
     summary: "Experimental ChatGPT app-server shim: launch, restore or status (macOS only).",
@@ -326,7 +335,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--range","value":"string","summary":"today | 1d | 7d | 30d | all; default 30d."},{"name":"--surface","value":"string","summary":"all | codex | claude | grok; default all."},{"name":"--since","value":"string","summary":"Inclusive epoch milliseconds or ISO datetime with timezone; requires --until."},{"name":"--until","value":"string","summary":"Inclusive end; requires --since. Custom bounds override --range."},{"name":"--provider","value":"string","summary":"Filter provider."},{"name":"--model","value":"string","summary":"Filter model."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--api-key-id","value":"string","summary":"Exact nonblank management key scope; connected clients refuse this before reading their enrolled key."},{"name":"--search","value":"string","summary":"Model-row substring view over model/provider/resolvedModel; top100 by tokens. Whole-report totals stay unchanged."}],
     mutates: false,
     json: "payload",
-    details: ["Alias of observe usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals."],
+    details: ["Alias of observe usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals.","Nested compare reads the named range and the previous equal window; --range all is refused."],
     usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
   },
   {
@@ -406,7 +415,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--provider","value":"string","summary":"Filter provider, including failover attempts."},{"name":"--model","value":"string","summary":"Filter model, including failover attempts."},{"name":"--status","value":"string","summary":"Filter status code."},{"name":"--conversation","value":"string","summary":"Filter conversation ID."},{"name":"--conversationId","value":"string","summary":"Alias of --conversation."},{"name":"--account","value":"string","summary":"Filter stable account log label."},{"name":"--limit","value":"number","summary":"Positive row limit; default 200."},{"name":"--follow","value":"boolean","summary":"Poll for new rows; add --jsonl to emit JSONL."},{"name":"-f","value":"boolean","summary":"Alias of --follow."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--jsonl","value":"boolean","summary":"Emit one row per JSON line; exclusive with --json."},{"name":"--events","value":"boolean","summary":"Versioned snapshot/append JSONL; requires --follow, conflicts with --json. Redundant --jsonl is accepted."}],
     mutates: false,
     json: "payload",
-    details: ["Follow uses the server cursor and a bounded ordered window, preserving same-ID amendments and repeated row occurrences. It never enables logging.","--events emits version1 snapshots/appends with cursor and limit for observed-window reconstruction. Legacy row JSONL cannot express removals or resets exactly; neither mode promises lossless history between polls.","Follow limit is1–2000, default200. Polling is serial and cancellable; SIGINT exits130 and SIGTERM143. Malformed/oversized/unavailable responses stop without a fabricated empty snapshot or retry.","Nested explain reads recorded decisions; rebuild-index and index-status touch the local derived index and retain separate declarations."],
+    details: ["Follow uses the server cursor and a bounded ordered window, preserving same-ID amendments and repeated row occurrences. It never enables logging.","--events emits version1 snapshots/appends with cursor and limit for observed-window reconstruction. Legacy row JSONL cannot express removals or resets exactly; neither mode promises lossless history between polls.","Follow limit is1–2000, default200. Polling is serial and cancellable; SIGINT exits130 and SIGTERM143. Malformed/oversized/unavailable responses stop without a fabricated empty snapshot or retry.","Nested history pages the derived index and get reads one canonical row; explain reads recorded decisions; rebuild-index and index-status touch the local derived index and retain separate declarations."],
     usage: "ocx logs [--provider <name>] [--model <id>] [--status <code>] [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]; ocx logs --follow --events [--limit <1-2000>]",
   },
   {
@@ -556,7 +565,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--json","value":"boolean","summary":"Emit the redacted provenance report as JSON."}],
     mutates: false,
     json: "envelope",
-    details: ["Proof-bound published-launcher context authenticates the configured candidate snapshot, not successful Codex execution; this check does not attest or admit a selected runtime.","On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed.","Makes no package-registry request.","Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state."],
+    details: ["Proof-bound published-launcher context authenticates the configured candidate snapshot, not successful Codex execution; the selection is attested only when the runtime resolver picks the same canonical path, and even then this check reports rather than admits a runtime.","On Windows this first slice performs no candidate or configuration filesystem I/O: only a proof-captured absolute environment candidate can receive lexical app-bundle or version-manager labels; every other Windows candidate fails closed.","Makes no package-registry request.","Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state."],
     usage: "ocx system codex-cli-update check [--json]",
   },
   {
@@ -569,14 +578,33 @@ export const CAPABILITIES: readonly Capability[] = [
     details: ["Opt-in Windows x64 local-volume inspection using held native file handles; refuses reparse points, active writers and unsupported layouts.","Without explicit paths, the proof-bound launcher snapshot identifies the selected candidate: the configured CODEX_CLI_PATH or the first codex on the captured PATH, with an OpenCodex wrapper resolving to its codex.opencodex-real backing. Discovery only proposes paths; the held-handle observation remains the authority.","Success binds observed file identities and bytes, not selected-runtime admission or installer ownership.","selectionAttested, managed and applyAllowed remain false. The digest is an observation, not a durable update permit.","Does not run the named Codex/npm/Node files, query a registry, install software, control processes or persist state."],
     usage: "ocx system codex-cli-update attest [--candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path>] [--json]",
   },
+  {
+    command: ["system", "codex-cli-update", "plan"],
+    summary: "Dry-run a Codex CLI update and print the plan id binding the decision's evidence.",
+    routes: [],
+    flags: [
+      { name: "--channel", value: "string", summary: "Registry channel to resolve. Only the stable latest channel is offered." },
+      { name: "--json", value: "boolean", summary: "Emit the plan as JSON." },
+    ],
+    mutates: false,
+    json: "envelope",
+    details: [
+      "Adds the three inputs check leaves out: an exact registry version with its sha512 integrity, a fail-closed process-table read, and a decision.",
+      "The registry evidence is pinned to the official npm registry with project/user npm configuration isolated, so a redirected .npmrc cannot supply the answer.",
+      "Installs nothing and mutates no application state; registry evidence is gathered under an isolated temporary npm root (npmrc, cwd, cache and logs) removed best-effort afterwards. A refusal is a normal dry-run answer and still exits 0.",
+      "The plan id is a digest of the evidence the decision rests on — ownership, the installed version, a digest of the canonical install root, the resolved target — not a stored job. There is no plan state on disk to expire, collide or clean up.",
+      "An unreadable process table refuses rather than reading as no live session.",
+    ],
+    usage: "ocx system codex-cli-update plan [--channel latest] [--json]",
+  },
   {
     command: ["system","codex-restart"],
-    summary: "Restart the Codex desktop app and app-servers.",
+    summary: "Restart the Codex app-servers, and the desktop app when its model picker predates the catalog.",
     routes: [{"method":"POST","path":"/api/system/codex-restart"}],
-    flags: [{"name":"--yes","value":"boolean","summary":"Required: fully quits and relaunches the operator's Codex desktop app, which may discard unsaved composer drafts, model-picker selections, and pending approval prompts; also restarts its app-servers."},{"name":"--json","value":"boolean","summary":"Emit the restart result as JSON."}],
+    flags: [{"name":"--yes","value":"boolean","summary":"Required: restarts the Codex app-servers, interrupting running turns, and fully quits and relaunches the operator's Codex desktop app when its model picker predates the current catalog or that cannot be determined, which may discard unsaved composer drafts, model-picker selections, and pending approval prompts."},{"name":"--json","value":"boolean","summary":"Emit the restart result as JSON."}],
     mutates: true,
     json: "payload",
-    details: ["`sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request.","Restarts the Codex desktop app as well as the app-servers, through the same module the CLI uses. When the proxy itself runs inside the Codex app it refuses instead, because restarting the app would kill the request.","--yes is mandatory because this interrupts a running editor session and may discard unsaved composer drafts, model-picker selections, and pending approval prompts; it must never happen because an agent guessed a subcommand."],
+    details: ["`sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog, cache, or changed configuration write, so it cannot restart a healthy install on request.","Restarts the app-servers through the same module the CLI uses. The desktop app is quit and relaunched when its model picker predates the current catalog or this request changes the `model_catalog_json` binding, because the picker is built at launch; otherwise it is left running and respawns its own app-server, keeping unsaved client state. An unreadable desktop or catalog state falls back to the full restart. When the proxy itself runs inside the Codex app the desktop restart is refused, because restarting the app would kill the request.","--yes is mandatory because this interrupts a running editor session and may discard unsaved composer drafts, model-picker selections, and pending approval prompts; it must never happen because an agent guessed a subcommand."],
     usage: "ocx system codex-restart --yes [--json]",
   },
   {
@@ -646,7 +674,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [],
     mutates: true,
     json: "none",
-    details: ["Needs a running proxy, first-party mode and macOS. The first time, macOS asks to trust a local certificate authority limited to claude.ai; when the server cannot show that prompt the command runs the trust step in this terminal.","Claude Desktop then reaches the network through opencodex; fully quit and reopen Desktop afterwards."],
+    details: ["Needs a running proxy, first-party mode and macOS or Windows. The first time, the OS asks to trust a local certificate authority limited to claude.ai; when the server cannot show that prompt the command runs the trust step in this terminal.","Claude Desktop then reaches the network through opencodex; fully quit and reopen Desktop afterwards."],
     usage: "ocx claude desktop picker on",
   },
   {
@@ -661,7 +689,7 @@ export const CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["claude","desktop","picker","trust"],
-    summary: "Run the macOS keychain step for picker mode in this terminal, then ask the server to finish enabling it.",
+    summary: "Run the OS certificate trust step for picker mode in this terminal, then ask the server to finish enabling it.",
     routes: [{"method":"GET","path":"/api/claude-desktop/picker"},{"method":"PUT","path":"/api/claude-desktop/picker"}],
     flags: [],
     mutates: true,
@@ -683,7 +711,7 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["integration","client"],
     summary: "Inspect and toggle file integrations and Aside profiles, read journals, and restore selected operations.",
     routes: [{"method":"GET","path":"/api/client-integrations"},{"method":"GET","path":"/api/client-integrations/{clientId}"},{"method":"GET","path":"/api/client-integrations/aside/profiles"},{"method":"GET","path":"/api/client-integrations/aside/profiles/{profileId}"},{"method":"GET","path":"/api/client-integrations/journal"},{"method":"GET","path":"/api/client-integrations/aside/profiles/journal"},{"method":"GET","path":"/api/client-integrations/aside/profiles/{profileId}/journal"},{"method":"PUT","path":"/api/client-integrations/{clientId}"},{"method":"PUT","path":"/api/client-integrations/aside/profiles"},{"method":"PUT","path":"/api/client-integrations/aside/profiles/{profileId}"},{"method":"POST","path":"/api/client-integrations/restore"},{"method":"POST","path":"/api/client-integrations/aside/profiles/{profileId}/restore"}],
-    flags: [{"name":"--client","value":"string","summary":"File integration ID; aside selects profiles."},{"name":"--profile","value":"number","summary":"Aside nonnegative integer account ID; requires --client aside."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--overwrite-conflict","value":"boolean","summary":"Explicitly permit replacing a conflicting block."},{"name":"--op","value":"string","summary":"Operation ID; --op-id is an alias."},{"name":"--confirm-drift","value":"boolean","summary":"Explicitly allow replacing edits made after the snapshot."}],
+    flags: [{"name":"--client","value":"string","summary":"File integration ID, including gentle-shell; aside selects profiles."},{"name":"--profile","value":"number","summary":"Aside nonnegative integer account ID; requires --client aside."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--overwrite-conflict","value":"boolean","summary":"Explicitly permit replacing a conflicting block."},{"name":"--op","value":"string","summary":"Operation ID; --op-id is an alias."},{"name":"--confirm-drift","value":"boolean","summary":"Explicitly allow replacing edits made after the snapshot."}],
     mutates: true,
     json: "payload",
     details: ["status/show/list reads all clients, one client or Aside profiles. history/journal reads rollback records; expired snapshots stay visible.","enable/disable requires --client; an omitted Aside --profile toggles all profiles. --overwrite-conflict applies only to enable.","restore requires --op (alias --op-id); --client requires --profile and only Aside supports that profile selector. --confirm-drift is an explicit user waiver, never auto-retried. Use client preview or restore --preview to inspect a change, history remove --op ID --yes to retire a journal row, and sync --client aside to refresh managed profiles."],
@@ -694,7 +722,7 @@ export const CAPABILITIES: readonly Capability[] = [
     summary: "Synchronize client catalogs, including Aside profiles through the running server's mutation owner.",
     routes: [{ method: "POST", path: "/api/client-integrations/aside/sync" }],
     flags: [
-      { name: "--restart-codex", value: "boolean", summary: "Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog or cache write, on macOS, Linux and Windows." },
+      { name: "--restart-codex", value: "boolean", summary: "Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog, cache, or changed configuration write, on macOS, Linux and Windows." },
       { name: "--restart-app-server-only", value: "boolean", summary: "Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given." },
       { name: "--restart-desktop-app", value: "boolean", summary: "Deprecated alias of --restart-codex." },
     ],
@@ -786,7 +814,7 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["api","policy"],
     summary: "Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.",
     routes: [{"method":"GET","path":"/api/protocols"},{"method":"PATCH","path":"/api/protocols/settings"}],
-    flags: [{"name":"--messages","value":"string","summary":"Open or close the Messages API: on or off. Off also turns the Claude integration off."},{"name":"--unrepresentable","value":"string","summary":"legacy keeps today's behavior; reject refuses a request its path cannot carry."},{"name":"--rollout","value":"string","summary":"One switch as name=on or name=off; repeatable. Every switch defaults off."},{"name":"--json","value":"boolean","summary":"Emit the resulting GET /api/protocols body."}],
+    flags: [{"name":"--messages","value":"string","summary":"Open or close the Messages API: on or off. Off also turns the Claude integration off."},{"name":"--unrepresentable","value":"string","summary":"legacy keeps today's behavior; reject refuses a request its path cannot carry."},{"name":"--rollout","value":"string","summary":"One switch as name=on or name=off; repeatable. Every switch defaults off except antigravityDirect."},{"name":"--json","value":"boolean","summary":"Emit the resulting GET /api/protocols body."}],
     mutates: true,
     json: "payload",
     details: ["A bare invocation reads and never writes.","A setting flag changes the operator's config; run it only when the operator asks for that change."],

package/src/cli/capabilities-observe-system.ts

@@ -16,6 +16,47 @@ export const OBSERVE_SYSTEM_CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["Follow uses the server cursor and a bounded ordered window, preserving same-ID amendments and repeated row occurrences. It never enables logging.","--events emits version1 snapshots/appends with cursor and limit for observed-window reconstruction. Legacy row JSONL cannot express removals or resets exactly; neither mode promises lossless history between polls.","Follow limit is1–2000, default200. Polling is serial and cancellable; SIGINT exits130 and SIGTERM143. Malformed/oversized/unavailable responses stop without a fabricated empty snapshot or retry."],
   },
+  {
+    command: ["logs", "history"],
+    summary: "Page the indexed request-history ledger with filters and a resumable cursor.",
+    usage: "ocx logs history [--provider <name>] [--model <id>] [--requested-model <id>] [--status <code>] [--conversation <id>] [--surface <name>] [--protocol <responses|chat|messages>] [--api-key-id <id>] [--profile <id>] [--fallback <true|false>] [--from <epoch-ms|ISO-datetime>] [--to <epoch-ms|ISO-datetime>] [--cursor <token>] [--limit <1-100>] [--json|--jsonl]",
+    routes: [{"method": "GET", "path": "/api/request-history"}],
+    flags: [
+      {"name": "--provider", "value": "string", "summary": "Filter provider, including failover attempts."},
+      {"name": "--model", "value": "string", "summary": "Filter served model, including failover attempts."},
+      {"name": "--requested-model", "value": "string", "summary": "Filter the model the client asked for."},
+      {"name": "--status", "value": "number", "summary": "HTTP status 100-599."},
+      {"name": "--conversation", "value": "string", "summary": "Conversation ID or stored hash."},
+      {"name": "--conversationId", "value": "string", "summary": "Alias of --conversation."},
+      {"name": "--surface", "value": "string", "summary": "Calling client surface recorded on the row."},
+      {"name": "--protocol", "value": "string", "summary": "Inbound wire: responses, chat or messages."},
+      {"name": "--api-key-id", "value": "string", "summary": "Exact management key id recorded on the row."},
+      {"name": "--profile", "value": "string", "summary": "Routing profile id."},
+      {"name": "--fallback", "value": "string", "summary": "true selects rows that failed over; false selects rows that did not."},
+      {"name": "--from", "value": "string", "summary": "Inclusive start as epoch milliseconds or ISO datetime with timezone."},
+      {"name": "--to", "value": "string", "summary": "Inclusive end as epoch milliseconds or ISO datetime with timezone."},
+      {"name": "--cursor", "value": "string", "summary": "Opaque nextCursor from a previous page."},
+      {"name": "--limit", "value": "number", "summary": "1-100 rows; default 50."},
+      {"name": "--json", "value": "boolean", "summary": "Emit the management payload, including hasMore, nextCursor and index."},
+      {"name": "--jsonl", "value": "boolean", "summary": "Matching rows only; hasMore and nextCursor go to stderr."},
+    ],
+    mutates: false, json: "payload",
+    details: [
+      "Pages the derived request-history index, not the recent /api/logs ring. Empty matches succeed. Also accepted after observe logs.",
+      "JSON is the management payload. JSONL emits entries only; resume with --cursor from stderr when hasMore is true.",
+    ],
+  },
+  {
+    command: ["logs", "get"],
+    summary: "Read one canonical request-history row by request ID.",
+    usage: "ocx logs get <request-id> [--json]",
+    routes: [{"method": "GET", "path": "/api/request-history/{id}"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the canonical row as JSON."}],
+    mutates: false, json: "payload",
+    details: [
+      "The request ID is URI-encoded. This is the stored row, not the route-decision view from logs explain. A missing id is a 404. Also accepted after observe logs.",
+    ],
+  },
   {
     command: ["logs", "explain"], summary: "Explain the recorded routing decision for one request.",
     usage: "ocx logs explain <request-id> [--json]",
@@ -43,12 +84,31 @@ export const OBSERVE_SYSTEM_CAPABILITIES: readonly Capability[] = [
   {
     command: ["observe","usage"],
     summary: "Read token and estimated-cost usage.",
-    usage: "ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
+    usage: "ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--since <epoch-ms|ISO-datetime>] [--until <epoch-ms|ISO-datetime>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--top <1-1000>] [--json]",
     routes: [{"method":"GET","path":"/api/usage"}],
-    flags: [{"name":"--range","value":"string","summary":"today | 1d | 7d | 30d | all; default 30d."},{"name":"--surface","value":"string","summary":"all | codex | claude | grok; default all."},{"name":"--since","value":"string","summary":"Inclusive epoch milliseconds or ISO datetime with timezone; requires --until."},{"name":"--until","value":"string","summary":"Inclusive end; requires --since. Custom bounds override --range."},{"name":"--provider","value":"string","summary":"Filter provider."},{"name":"--model","value":"string","summary":"Filter model."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--api-key-id","value":"string","summary":"Exact nonblank management key scope; connected clients refuse this before reading their enrolled key."},{"name":"--search","value":"string","summary":"Model-row substring view over model/provider/resolvedModel; top100 by tokens. Whole-report totals stay unchanged."}],
+    flags: [{"name":"--range","value":"string","summary":"today | 1d | 7d | 30d | all; default 30d."},{"name":"--surface","value":"string","summary":"all | codex | claude | grok; default all."},{"name":"--since","value":"string","summary":"Inclusive epoch milliseconds or ISO datetime with timezone; requires --until."},{"name":"--until","value":"string","summary":"Inclusive end; requires --since. Custom bounds override --range."},{"name":"--provider","value":"string","summary":"Filter provider."},{"name":"--model","value":"string","summary":"Filter model."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."},{"name":"--api-key-id","value":"string","summary":"Exact nonblank management key scope; connected clients refuse this before reading their enrolled key."},{"name":"--top","value":"number","summary":"1-1000 human model rows; default 10, or 100 with --search. Applied after search; ignored with --json. Totals unchanged."},{"name":"--search","value":"string","summary":"Model-row substring view over model/provider/resolvedModel; default top100 by tokens. Whole-report totals stay unchanged."}],
     mutates: false,
     json: "payload",
-    details: ["Also available as ocx usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows; modelView reports match/return counts without recomputing totals."],
+    details: ["Also available as ocx usage. Connected clients read only their enrolled-key Hub report through /v1/usage; caller --api-key-id is refused before key read/transport and never grants management authority.","Nonclient --api-key-id uses /api/usage and requires matching filter acknowledgment. An unknown acknowledged key is empty/matched:false, not404. Custom-window acknowledgment remains required.","--search filters only returned model rows after scope acknowledgment. Blank search selects the top100 model rows by default; modelView reports match/return counts without recomputing totals."],
+  },
+  {
+    command: ["usage", "compare"],
+    summary: "Compare a usage range with the previous equal window.",
+    usage: "ocx usage compare [--range <today|1d|7d|30d>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]",
+    routes: [{"method": "GET", "path": "/api/usage"}],
+    flags: [
+      {"name": "--range", "value": "string", "summary": "today | 1d | 7d | 30d; default 30d. all is refused."},
+      {"name": "--surface", "value": "string", "summary": "all | codex | claude | grok; default all."},
+      {"name": "--provider", "value": "string", "summary": "Filter provider."},
+      {"name": "--model", "value": "string", "summary": "Filter model."},
+      {"name": "--api-key-id", "value": "string", "summary": "Exact nonblank management key scope; connected clients refuse this."},
+      {"name": "--json", "value": "boolean", "summary": "Emit current, previous, delta and change percentages."},
+    ],
+    mutates: false, json: "envelope",
+    details: [
+      "Two sequential GET /api/usage reads: the named range at now, then the same range shifted back one equal window. Custom since/until must be acknowledged on both. --range all is refused.",
+      "Also accepted after observe usage. Default range is 30d. This is not an atomic snapshot.",
+    ],
   },
   {
     command: ["observe", "storage"], summary: "Read storage diagnostics.",

package/src/cli/capabilities-provider-models.ts

@@ -207,6 +207,17 @@ export const PROVIDER_MODEL_CAPABILITIES: readonly Capability[] = [
     flags: [{ name: "--enabled", value: "string", summary: "on or off; takes a value." }, { name: "--json", value: "boolean", summary: "Emit the settings receipt." }],
     details: ["At least a model or --enabled is required; - clears the model with an empty string. Enabling shadow calls can cause subsequent inference calls."],
   },
+  {
+    command: ["models", "auto-review", "status"], summary: "Read the global auto-review model and enabled state.",
+    usage: "ocx models auto-review status [--json]", routes: [{ method: "GET", path: "/api/auto-review-settings" }], mutates: false, json: "payload",
+    flags: [{ name: "--json", value: "boolean", summary: "Emit auto-review settings." }],
+  },
+  {
+    command: ["models", "auto-review", "set"], summary: "Set the global auto-review model or enabled state.",
+    usage: "ocx models auto-review set [model|-] [--enabled <on|off>] [--json]", routes: [{ method: "PUT", path: "/api/auto-review-settings" }], mutates: true, json: "payload",
+    flags: [{ name: "--enabled", value: "string", summary: "on or off; takes a value." }, { name: "--json", value: "boolean", summary: "Emit the settings receipt." }],
+    details: ["At least a model or --enabled is required; - clears the model with an empty string. Human output points to ocx sync when a catalog refresh can be retried and asks operators to resolve a failed refresh before syncing."],
+  },
   {
     command: ["alias", "list"], summary: "Read provider and model aliases.",
     usage: "ocx alias list [--json]", routes: [{ method: "GET", path: "/api/aliases" }], mutates: false, json: "payload",

package/src/cli/chatgpt-command.ts

@@ -20,7 +20,7 @@ const USAGE = `Usage (experimental, macOS only):
 
 function run(command: string, args: string[]) {
   const result = spawnSync(command, args, { encoding: "utf8", timeout: 5000 });
-  return { ok: result.status === 0, output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() };
+  return { ok: result.status === 0, status: result.status, output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() };
 }
 
 /**
@@ -42,11 +42,12 @@ function chatgptDesktopIssueInFile(): string | null {
  * desktop restart adapter does. "ChatGPT" is a display name another app can share, so quitting,
  * relaunching and the binary path all key on this verified bundle rather than on the name.
  */
-function discoverApp(): DesktopAppInstall | null {
+function discoverApp(): DesktopAppInstall | null | undefined {
   try {
     return darwinDesktopAppAdapter.discover(darwinDefaultExec);
   } catch {
-    return null;
+    // An inspection error is not evidence that the app is uninstalled.
+    return undefined;
   }
 }
 
@@ -55,14 +56,20 @@ function discoverApp(): DesktopAppInstall | null {
  * `-a` keeps ancestors in the match: when ocx runs inside a ChatGPT/Codex session the app is
  * one of this process's ancestors, and plain `pgrep -x` would report it as not running.
  */
-function appState(install: DesktopAppInstall, launcher: string): { running: boolean; shim: boolean } {
+function appState(install: DesktopAppInstall, launcher: string): { running: boolean | null; shim: boolean | null } {
   const shell = join(install.root, "Contents", "MacOS", "ChatGPT");
   // Only this user's processes: another account's ChatGPT can neither be quit nor relaunched here.
   const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
   const pids = run("pgrep", [...(uid === undefined ? [] : ["-U", String(uid)]), "-a", "-x", "ChatGPT"]);
-  if (!pids.ok) return { running: false, shim: false };
-  for (const pid of pids.output.split(/\s+/).filter(value => /^\d+$/.test(value))) {
+  // pgrep exit 1 means no match; timeout, signal, or command errors are unknown.
+  if (!pids.ok) return pids.status === 1
+    ? { running: false, shim: false } : { running: null, shim: null };
+  const candidates = pids.output.split(/\s+/).filter(value => /^\d+$/.test(value));
+  if (candidates.length === 0) return { running: null, shim: null };
+  let unreadable = false;
+  for (const pid of candidates) {
     const command = run("ps", ["eww", "-o", "command=", "-p", pid]);
+    if (!command.ok || !command.output) unreadable = true;
     if (command.ok && (command.output === shell || command.output.startsWith(`${shell} `))) {
       const marker = `CODEX_CLI_PATH=${launcher}`;
       const start = command.output.indexOf(marker);
@@ -70,20 +77,24 @@ function appState(install: DesktopAppInstall, launcher: string): { running: bool
         && (start + marker.length === command.output.length || command.output[start + marker.length] === " ") };
     }
   }
-  return { running: false, shim: false };
+  return unreadable ? { running: null, shim: null } : { running: false, shim: false };
 }
 
 /** Adapted from #5947: open ignores new launch settings until the previous app exits. */
 async function quitApp(install: DesktopAppInstall, launcher: string): Promise<boolean> {
-  if (!appState(install, launcher).running) return true;
+  const initial = appState(install, launcher).running;
+  if (initial === false) return true;
+  if (initial === null) return false;
   for (let attempt = 0; attempt < 3; attempt++) {
     run("/usr/bin/osascript", ["-e", `quit app id "${install.id}"`]);
     for (let poll = 0; poll < 20; poll++) {
-      if (!appState(install, launcher).running) return true;
+      const running = appState(install, launcher).running;
+      if (running === false) return true;
+      if (running === null) return false;
       await Bun.sleep(250);
     }
   }
-  return !appState(install, launcher).running;
+  return appState(install, launcher).running === false;
 }
 
 export async function handleChatgptCommand(args: string[], platform: NodeJS.Platform = process.platform): Promise<number> {
@@ -105,16 +116,21 @@ export async function handleChatgptCommand(args: string[], platform: NodeJS.Plat
     const launcher = chatgptShimLauncherPath();
     const install = discoverApp();
     if (sub === "status") {
-      const app = install ? appState(install, launcher) : { running: false, shim: false };
+      const app = install ? appState(install, launcher)
+        : install === undefined ? { running: null, shim: null } : { running: false, shim: false };
       const configIssue = config.chatgptDesktop?.appServerShim === true ? null : chatgptDesktopIssueInFile();
       const flag = config.chatgptDesktop?.appServerShim === true ? "on"
         : configIssue ? `off (config.json ${configIssue}; the whole chatgptDesktop block is ignored)` : "off";
       console.log(`app-server shim (experimental): ${flag}
 launcher: ${existsSync(launcher) ? "present" : "absent"}
-app: ${install ? (app.running ? "running" : "not running") : "not installed"}
-CODEX_CLI_PATH launcher: ${app.shim ? "yes" : "no"}`);
+app: ${install === undefined ? "unknown (app discovery failed)" : install ? (app.running === null ? "unknown (process inspection failed)" : app.running ? "running" : "not running") : "not installed"}
+CODEX_CLI_PATH launcher: ${app.shim === null ? "unknown" : app.shim ? "yes" : "no"}`);
       return 0;
     }
+    if (install === undefined) {
+      console.error("ChatGPT app discovery failed; no launcher was changed and no app was opened. Retry after resolving discovery.");
+      return 1;
+    }
     if (!install) {
       if (sub === "restore") rmSync(launcher, { force: true });
       console.error("ChatGPT (com.openai.codex) was not found; install or open it once, then retry.");
@@ -143,9 +159,14 @@ CODEX_CLI_PATH launcher: ${app.shim ? "yes" : "no"}`);
       console.error(`Refusing to ${sub === "launch" ? "launch the shim" : "restore ChatGPT"}: ${untrusted}.`);
       return 1;
     }
+    // Preflight before changing the launcher. quitApp rechecks at the action boundary.
+    if (appState(install, launcher).running === null) {
+      console.error("ChatGPT process inspection failed; no launcher was changed and no app was opened. Retry after resolving inspection.");
+      return 1;
+    }
     if (binary) writeChatgptShimLauncher(undefined, binary);
     if (!(await quitApp(install, launcher))) {
-      console.error("ChatGPT did not quit; quit it manually and retry.");
+      console.error("ChatGPT exit could not be confirmed; no new app was opened. Check the running app and retry.");
       return 1;
     }
     // Remove an inherited override too: restore must launch without CODEX_CLI_PATH.

package/src/cli/claude.ts

@@ -32,7 +32,8 @@ import { DEFAULT_CATALOG_PATH } from "../codex/paths";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { aliasForNative, aliasForRoute, legacyAliasForNative, legacyAliasForRoute } from "../claude/alias";
-import { desktop3pAlias } from "../claude/desktop-3p";
+import { desktop3pAlias, isRealDesktop3pModelId, resolveDesktop3pAlias } from "../claude/desktop-3p";
+import { desktopProfileWireAlias, legacyDesktopProfileWireAlias } from "../claude/desktop-profile";
 import { inspectDesktopFirstParty } from "../claude/desktop-first-party";
 import { isClaudeInterceptProxyUrl, type ClaudeInterceptSettingsState } from "../claude/intercept/settings";
 import { withoutSiblingMarker } from "../codex/sibling-start";
@@ -618,11 +619,47 @@ const MODEL_ENV_SLOT_NAMES = [
   "ANTHROPIC_SMALL_FAST_MODEL",
 ] as const;
 
-const DESKTOP_3P_ALIAS = /^claude-opus-4(?:-8)?-[a-z][0-9a-z]{2}$/;
+const DESKTOP_3P_ALIAS = /^claude-(?:opus-4(?:-8)?-[a-z][0-9a-z]{2}|(?:opus-4-8|fable-5)-p[0-9a-z]{3})(?:--fast)?$/;
+
+export function nativeClaudeModelIds(config: OcxConfig): string[] {
+  const assignments = config.claudeCode?.desktopProfile?.assignments ?? {};
+  const routes = Object.keys(assignments);
+  const realProfileIds = new Set(routes.filter(route => route.startsWith("anthropic/claude-"))
+    .map(route => route.slice("anthropic/".length)));
+  // A native CLI starts without the server registry. Persisted profile bindings still
+  // identify proxy selectors, even when an old provider declaration has the same spelling.
+  const proxyProfileIds = new Set(routes.filter(route => !route.startsWith("anthropic/claude-"))
+    .flatMap(route => {
+      const alias = assignments[route]!.alias;
+      const slash = route.indexOf("/");
+      return [alias, desktopProfileWireAlias(alias), legacyDesktopProfileWireAlias(alias),
+        desktop3pAlias(route.slice(0, slash), route.slice(slash + 1))];
+    }));
+  // The configured default is a genuine declaration too: the catalog seeds it for static
+  // providers, so it must be recognized here even without a server registry.
+  const anthropic = config.providers.anthropic;
+  const declaredIds = [
+    ...(anthropic?.defaultModel ? [anthropic.defaultModel] : []),
+    ...(anthropic?.models ?? []), ...(anthropic?.selectedModels ?? []), ...(anthropic?.retainModels ?? []),
+  ];
+  return [...new Set([
+    ...realProfileIds,
+    ...declaredIds
+      .filter(id => {
+        const base = id.endsWith("--fast") ? id.slice(0, -"--fast".length) : id;
+        return id.startsWith("claude-") && (realProfileIds.has(id)
+          || (!proxyProfileIds.has(id) && !proxyProfileIds.has(base)));
+      }),
+  ])];
+}
 
-export function isProxyOnlyModelId(value: string, providerNames: readonly string[] = []): boolean {
+export function isProxyOnlyModelId(value: string, providerNames: readonly string[] = [], realAnthropicIds: readonly string[] = []): boolean {
   const id = value.trim().replace(/\[1m\]$/, "");
   if (!id) return false;
+  if (isRealDesktop3pModelId(id)) return false;
+  const base = id.endsWith("--fast") ? id.slice(0, -"--fast".length) : id;
+  if (resolveDesktop3pAlias(id) || resolveDesktop3pAlias(base)) return true;
+  if (realAnthropicIds.includes(id)) return false;
   const aliasPrefixes = [CLAUDE_ALIAS_PREFIX_CURRENT, CLAUDE_ALIAS_PREFIX_CURRENT_V2, CLAUDE_ALIAS_PREFIX_V1, CLAUDE_ALIAS_PREFIX_V2];
   if (aliasPrefixes.some(prefix => id.startsWith(prefix)) || DESKTOP_3P_ALIAS.test(id)) {
     return true;
@@ -684,9 +721,10 @@ export function buildNativeClaudeEnv(
   // otherwise settings.env can replace the destination while retaining the credential.
   if (hasOwnedAdmission) delete env.CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST;
   const providerNames = Object.keys(config.providers);
+  const realAnthropicIds = nativeClaudeModelIds(config);
   for (const name of MODEL_ENV_SLOT_NAMES) {
     const value = env[name];
-    if (!value || !isProxyOnlyModelId(value, providerNames)) continue;
+    if (!value || !isProxyOnlyModelId(value, providerNames, realAnthropicIds)) continue;
     delete env[name];
     // The label opencodex paired with this slot names a proxy route the native session cannot use.
     const labelName = `${name}_NAME`;
@@ -702,11 +740,12 @@ export function nativeModelOverride(
   configuredModel: string | undefined,
   args: readonly string[],
   providerNames: readonly string[] = [],
+  realAnthropicIds: readonly string[] = [],
 ): { flag?: string[]; warning?: string } {
-  if (!pickedModel || !isProxyOnlyModelId(pickedModel, providerNames)) return {};
+  if (!pickedModel || !isProxyOnlyModelId(pickedModel, providerNames, realAnthropicIds)) return {};
   if (args.some(arg => arg === "--model" || arg.startsWith("--model="))) return {};
   const fallback = configuredModel?.trim();
-  if (fallback && !isProxyOnlyModelId(fallback, providerNames)) {
+  if (fallback && !isProxyOnlyModelId(fallback, providerNames, realAnthropicIds)) {
     return {
       flag: ["--model", fallback],
       warning: `ℹ️ The saved model (${pickedModel}) requires the proxy. This native session will use ${fallback}.`,
@@ -867,6 +906,7 @@ async function launchNativeClaude(config: OcxConfig, args: string[], notice: str
     config.claudeCode?.model,
     args,
     providerNames,
+    nativeClaudeModelIds(config),
   );
   if (override.warning) console.error(override.warning);
   const allowRootSkipPermissions = shouldAllowRootSkipPermissions(args);