@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/cli/advisor.ts

@@ -3,18 +3,20 @@ import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, tak
 
 const USAGE = `Usage:
   ocx advisor status [--json]
+  ocx advisor activity [--json]
   ocx advisor on [--ack-context-sharing] [--json]
   ocx advisor off [--json]
   ocx advisor consent [--revoke] [--json]
-  ocx advisor set [--model <model>] [--effort <effort>] [--policy <manual|preflight>] [--timeout-ms <ms>] [--json]`;
+  ocx advisor set [--model <model>] [--effort <effort>] [--policy <manual|preflight|adaptive>] [--max-consultations <1-3>] [--timeout-ms <ms>] [--json]`;
 
-const VALUED_FLAGS = new Set(["--model", "--effort", "--policy", "--timeout-ms"]);
+const VALUED_FLAGS = new Set(["--model", "--effort", "--policy", "--timeout-ms", "--max-consultations"]);
 
 interface SetOptions {
   model?: string;
   effort?: string;
   policy?: string;
   timeoutMs?: string;
+  maxConsultations?: string;
 }
 
 function parseSetArgs(args: string[]): SetOptions {
@@ -30,10 +32,11 @@ function parseSetArgs(args: string[]): SetOptions {
     if (arg === "--model") options.model = value;
     else if (arg === "--effort") options.effort = value;
     else if (arg === "--policy") options.policy = value;
+    else if (arg === "--max-consultations") options.maxConsultations = value;
     else options.timeoutMs = value;
   }
   if (Object.keys(options).length === 0) {
-    throw new CliUsageError("advisor set requires at least one of --model, --effort, --policy, --timeout-ms", USAGE);
+    throw new CliUsageError("advisor set requires a model, effort, policy, task limit, or timeout option", USAGE);
   }
   return options;
 }
@@ -125,6 +128,11 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   if (options.model !== undefined) patch.model = options.model;
   if (options.effort !== undefined) patch.effort = options.effort;
   if (options.policy !== undefined) patch.policy = options.policy;
+  if (options.maxConsultations !== undefined) {
+    const limit = Number(options.maxConsultations);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 3) throw new CliUsageError("--max-consultations must be an integer between 1 and 3", USAGE);
+    patch.maxConsultationsPerTask = limit;
+  }
   if (options.timeoutMs !== undefined) {
     const parsed = Number(options.timeoutMs);
     if (!Number.isFinite(parsed)) throw new CliUsageError("--timeout-ms must be a number", USAGE);
@@ -140,6 +148,12 @@ export async function handleAdvisorCommand(argv: string[], deps: RuntimeApiDeps
   return runCliAction(async () => {
     const [sub = "status", ...rest] = argv;
     if (sub === "status") await status(rest, deps);
+    else if (sub === "activity") {
+      const args = [...rest];
+      const wantsJson = takeFlag(args, "--json");
+      rejectArgs(args, USAGE);
+      printData(await runtimeRequest("/api/advisor/activity", {}, deps), wantsJson);
+    }
     else if (sub === "on") await setEnabled(true, rest, deps);
     else if (sub === "off") await setEnabled(false, rest, deps);
     else if (sub === "consent") await consent(rest, deps);

package/src/cli/capabilities-accounts.ts

@@ -2,6 +2,14 @@ import type { Capability } from "./capability-types";
 
 /** Account pool operations and physical native-login profiles have separate owners. */
 export const ACCOUNT_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["account", "preserve-signed-in"], summary: "Prefer other Codex identities and reserve the native sign-in as fallback.",
+    usage: "ocx account preserve-signed-in openai [on|off|status] [--apply-to-bound] [--json]",
+    routes: [{ method: "GET", path: "/api/codex-auth/preserve-signed-in" }, { method: "PUT", path: "/api/codex-auth/preserve-signed-in" }],
+    flags: [{ name: "--apply-to-bound", value: "boolean", summary: "With on, release protected bindings and pins for the next request." }, { name: "--json", value: "boolean", summary: "Emit affected entries, next unbound choice and pin/binding semantics." }],
+    mutates: true, json: "payload",
+    details: ["Default/status reads. Custom priorities are preserved. Bound threads and manual pins remain unless explicitly released. Exact-account models override the preference. Fallback can spend signed-in quota; linked pause excludes it instead."],
+  },
   {
     command: ["logout"],
     summary: "Remove the active stored OAuth credential for a provider locally.",
@@ -157,11 +165,22 @@ export const ACCOUNT_CAPABILITIES: readonly Capability[] = [
     usage: "ocx account pool <provider> [--enabled <on|off>] [--threshold <0-100>] [--strategy <name>] [--sticky <1-100>] [--quota-window <five-hour|weekly|max-utilization>] [--json]",
     summary: "Read or edit the selected runtime's supported pool policy fields.",
     routes: [{"method":"GET","path":"/api/pool/settings"},{"method":"PUT","path":"/api/pool/settings"}],
-    flags: [{"name":"--enabled","value":"string","summary":"Stored pool preference; unsupported for Codex. Not equivalent to threshold0."},{"name":"--threshold","value":"number","summary":"Auto-switch threshold0–100."},{"name":"--strategy","value":"string","summary":"Use a strategy supported by this provider kind; reset-first is Codex, least-loaded is Kiro."},{"name":"--sticky","value":"number","summary":"Sticky limit1–100."},{"name":"--quota-window","value":"string","summary":"Anthropic only: five-hour, weekly or max-utilization."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
+    flags: [{"name":"--enabled","value":"string","summary":"Stored pool preference; unsupported for Codex. Not equivalent to threshold0."},{"name":"--threshold","value":"number","summary":"Auto-switch threshold0–100."},{"name":"--strategy","value":"string","summary":"Use a strategy supported by this provider kind; reset-first is Codex or generic OAuth, least-loaded is Kiro."},{"name":"--sticky","value":"number","summary":"Sticky limit1–100."},{"name":"--quota-window","value":"string","summary":"Anthropic only: five-hour, weekly or max-utilization."},{"name":"--json","value":"boolean","summary":"Emit the validated task result as one JSON document."}],
     mutates: true,
     json: "envelope",
     details: ["Reads the target supported-field list before a narrow PUT. Null/unsupported, stored/effective and generic inert policy stay distinct; disabling does not promise that reactive429 rotation stops.","No local classification/defaults are round-tripped into the live target; supported-field reads are not CAS."],
   },
+  {
+    command: ["account", "use-remaining"],
+    usage: "ocx account use-remaining openai <id|alias|main> <on|off|status> [--json]",
+    summary: "Choose whether one Codex account keeps using its remaining included quota.",
+    routes: [{ method: "GET", path: "/api/codex-auth/accounts" },
+      { method: "GET", path: "/api/codex-auth/accounts/use-remaining" }, { method: "PUT", path: "/api/codex-auth/accounts/use-remaining" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the validated account policy." }],
+    mutates: true, json: "envelope",
+    details: ["On disables proactive usage switching for the selected account and raises main-account protection to 100%. Off restores the configured thresholds.",
+      "This is a persistent preference, not account selection. Pause, reauthentication, cooldown, entitlement and paid-credit policy still apply."],
+  },
   {
     command: ["account","credits"],
     usage: "ocx account credits openai <id|alias|main> <on|off> [--json]; ocx account credits openai --all <on|off> [--json]",

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

@@ -30,6 +30,7 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
     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." }],
@@ -40,6 +41,8 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
       "`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.",
     ],
   },
 
@@ -295,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." },
     ],

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",