@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/cli/ensure-desktop-cold-start.ts

@@ -10,8 +10,9 @@
  *
  * Rules, in order:
  * - A running Desktop app is the supervisor. Wait for its proxy; never start a competing one.
- * - A durable Desktop claim with no running app: start Desktop (hidden, as a login launch would)
- *   where that is possible, then wait. Elsewhere, fail with guidance. A missing Desktop process
+ * - A durable Desktop claim with no running app: start Desktop (hidden, by the path its own
+ *   login registration recorded — LaunchServices never picks the bundle) where that is
+ *   verifiable, then wait. Elsewhere, fail with guidance. A missing Desktop process
  *   never authorizes a CLI proxy by itself; handing ownership to the CLI stays an explicit
  *   `ocx service install` consent step.
  * - Ownership or the process list that cannot be read is not evidence of absence: refuse.
@@ -22,9 +23,9 @@
  */
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, linkSync, readdirSync, readFileSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { accessSync, constants, existsSync, linkSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, join, win32 } from "node:path";
+import { basename, dirname, join, posix, win32 } from "node:path";
 import { getConfigDir } from "../config/paths";
 import { resolveServiceOwnership } from "../service/state";
 
@@ -220,11 +221,63 @@ export function inspectDesktopProcess(options: DesktopProcessOptions = {}): Desk
   }
 }
 
-/** Start the macOS app hidden, the same way its login item does. */
-export function launchDesktopApp(options: { platform?: NodeJS.Platform; run?: Execute } = {}): boolean {
+const DESKTOP_BUNDLE_ID = "com.opencodex.desktop";
+const DESKTOP_PLIST_LABEL = "OpenCodex";
+
+/**
+ * The app bundle the consented installation itself registered as its Start-at-Login program —
+ * not whichever bundle LaunchServices would resolve for our identifier. `open -b` answers a
+ * mutable per-user registry: any planted bundle claiming {@link DESKTOP_BUNDLE_ID} could be
+ * selected and executed in the real app's place. The recorded claim, this app's own install-id
+ * store, and the login registration it wrote are the durable evidence of which installation
+ * that is; a claim whose registration is absent, malformed, stale or points off a Desktop
+ * executable refuses the launch instead of guessing.
+ */
+function consentedDesktopBundle(home: string, installId: string, run: Execute): string | null {
+  const localId = readFileSync(
+    join(home, "Library", "Application Support", DESKTOP_BUNDLE_ID, "install-id"), "utf8",
+  ).trim();
+  if (!localId || localId !== installId) return null;
+  const plistPath = realpathSync(join(home, "Library", "LaunchAgents", `${DESKTOP_PLIST_LABEL}.plist`));
+  const registration = JSON.parse(
+    run("/usr/bin/plutil", ["-convert", "json", "-o", "-", plistPath], 3_000),
+  ) as { Label?: unknown; ProgramArguments?: unknown; Program?: unknown };
+  const args = registration.ProgramArguments;
+  // The shapes auto-launch writes: [program] or [program, "--autostart"]; see the migration
+  // rules in desktop/src-tauri/src/login_registration.rs, which classify anything else Leave.
+  // This is a macOS plist path, regardless of the host running an injected launch probe.
+  if (registration.Label !== DESKTOP_PLIST_LABEL || !Array.isArray(args)
+    || (args.length !== 1 && args.length !== 2) || typeof args[0] !== "string" || !posix.isAbsolute(args[0])
+    || (args.length === 2 && args[1] !== "--autostart")
+    || (registration.Program !== undefined && registration.Program !== args[0])) return null;
+  const executable = realpathSync(args[0]);
+  if (!isDesktopExecutable(executable, "darwin") || !statSync(executable).isFile()) return null;
+  accessSync(executable, constants.X_OK);
+  const bundle = dirname(dirname(dirname(executable)));
+  if (!bundle.endsWith(".app")) return null;
+  const info = JSON.parse(
+    run("/usr/bin/plutil", ["-convert", "json", "-o", "-", join(bundle, "Contents", "Info.plist")], 3_000),
+  ) as { CFBundleIdentifier?: unknown; CFBundleExecutable?: unknown };
+  // `open` uses this selector, so checking only the registration and identifier would
+  // validate one binary while launching another. The registered path is already canonical.
+  if (info.CFBundleIdentifier !== DESKTOP_BUNDLE_ID || info.CFBundleExecutable !== "opencodex-desktop") return null;
+  return realpathSync(join(bundle, "Contents", "MacOS", info.CFBundleExecutable)) === executable ? bundle : null;
+}
+
+/** Start the consented macOS app hidden, by the path its own login registration recorded. */
+export function launchDesktopApp(options: {
+  platform?: NodeJS.Platform;
+  run?: Execute;
+  home?: string;
+  ownership?: () => ReturnType<typeof resolveServiceOwnership>;
+} = {}): boolean {
   if ((options.platform ?? process.platform) !== "darwin") return false;
   try {
-    (options.run ?? execute)("/usr/bin/open", ["-g", "-b", "com.opencodex.desktop", "--args", "--autostart"], 10_000);
+    const owner = (options.ownership ?? resolveServiceOwnership)();
+    if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return false;
+    const bundle = consentedDesktopBundle(options.home ?? homedir(), owner.ownership.installId, options.run ?? execute);
+    if (bundle === null) return false;
+    (options.run ?? execute)("/usr/bin/open", ["-g", bundle, "--args", "--autostart"], 10_000);
     return true;
   } catch { return false; }
 }

package/src/cli/help.ts

@@ -85,14 +85,14 @@ Usage:
   ocx inspect <sub>           Effective config, catalog, analytics, pacing, client-config
   ocx route <sub>             Routing features (combo, policy)
   ocx logs [filters]          Alias of ocx observe logs
-  ocx usage [--range <today|1d|7d|30d|all>] [--provider <name>] [--model <id>]
+  ocx usage [--range <today|1d|7d|30d|all>] [--provider <name>] [--model <id>] [--top <1-1000>]
                               Token and estimated-cost report (alias of ocx observe usage)
   ocx storage <sub>           Storage report, cleanup, trash, and the cleanup policy
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
   ocx api <sub>               Protocol paths: vocabulary, request-path preview, and policy
-  ocx export --client <id>    Print a client config wired to the running proxy (19 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (20 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
@@ -100,6 +100,7 @@ Usage:
   ocx advisor <status|on|off|set|consent>  Advisor sidecar settings and context-sharing consent
   ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
   ocx lab <sub>               Inspect Lab evidence and control local automation
+  ocx codex-provider <sub>    Confirm custom Codex provider routing: status|allow|revoke
   ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile

package/src/cli/index.ts

@@ -660,7 +660,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     }
     removePid(process.pid);
     removeRuntimePort(process.pid);
-    if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {
+    if (teardown.restoreNativeCodex) {
       try {
         if (!codexHomeIsAbsent(getCodexHome())) {
           const restored = restoreNativeCodex();

package/src/cli/integration-plan-dto.ts

@@ -27,6 +27,7 @@ export const FILE_INTEGRATION_CLIENTS = [
   "kilo",
   "droid",
   "qoder",
+  "gentle-shell",
 ] as const;
 
 export const INTEGRATION_REFUSAL_REASONS: ReadonlySet<string> = new Set<IntegrationRefusalReason>([

package/src/cli/log-history.ts

@@ -0,0 +1,172 @@
+/**
+ * Indexed request-history reads: page the derived ledger, or fetch one canonical row.
+ *
+ * Distinct from `ocx logs` (the recent ring) and `ocx logs explain` (route-decision).
+ */
+import { REQUEST_HISTORY_DEFAULT_PAGE_SIZE, REQUEST_HISTORY_MAX_PAGE_SIZE } from "../routing/history/indexer";
+import { parseUsageTimeWindow } from "../usage/time-range";
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runtimeRequest,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+type LogRow = Record<string, unknown>;
+
+export const LOG_HISTORY_USAGE = `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-${REQUEST_HISTORY_MAX_PAGE_SIZE}>] [--json|--jsonl]
+  ocx logs get <request-id> [--json]`;
+
+const GET_USAGE = "Usage: ocx logs get <request-id> [--json]";
+const PROTOCOLS = ["responses", "chat", "messages"] as const;
+
+function query(params: Record<string, string | number | boolean | undefined>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) search.set(key, String(value));
+  }
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : "";
+}
+
+function timestampOption(args: string[], flag: string): number | undefined {
+  const raw = takeOption(args, flag);
+  if (raw === undefined) return undefined;
+  try {
+    return parseUsageTimeWindow(raw, raw)!.since;
+  } catch (error) {
+    throw new CliUsageError(error instanceof Error ? `${flag}: ${error.message}` : `${flag} is invalid`, LOG_HISTORY_USAGE);
+  }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function formatCost(row: Record<string, unknown>): string {
+  const metrics = record(row.displayMetrics) ? row.displayMetrics : undefined;
+  const cost = metrics && record(metrics.cost) ? metrics.cost : undefined;
+  if (!cost || cost.kind !== "value" || !record(cost.estimate) || !record(cost.estimate.cost)) return "";
+  const total = cost.estimate.cost.total;
+  return typeof total === "number" && Number.isFinite(total) ? `~$${total.toFixed(4)}` : "";
+}
+
+function formatHistoryRow(row: LogRow, formatRow: (row: LogRow) => string): string {
+  const tokens = typeof row.totalTokens === "number" && Number.isFinite(row.totalTokens)
+    ? `${row.totalTokens}tok`
+    : "";
+  return [formatRow(row), tokens, formatCost(row)].filter(Boolean).join("  ");
+}
+
+function historyPage(raw: unknown): {
+  entries: Record<string, unknown>[];
+  nextCursor?: string;
+  hasMore: boolean;
+  index?: Record<string, unknown>;
+} {
+  if (!record(raw) || !Array.isArray(raw.entries) || typeof raw.hasMore !== "boolean") {
+    throw new Error("Invalid request-history page. Upgrade the proxy and retry.");
+  }
+  const entries = raw.entries;
+  if (!entries.every(record)) throw new Error("Invalid request-history page. Upgrade the proxy and retry.");
+  const nextCursor = typeof raw.nextCursor === "string" && raw.nextCursor.length > 0 ? raw.nextCursor : undefined;
+  const index = record(raw.index) ? raw.index : undefined;
+  return { entries, nextCursor, hasMore: raw.hasMore, index };
+}
+
+/** Page the derived request-history index through GET /api/request-history. */
+export async function handleLogHistoryCommand(
+  argv: string[],
+  deps: RuntimeApiDeps,
+  formatRow: (row: LogRow) => string,
+): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const wantsJsonl = takeFlag(args, "--jsonl");
+  const provider = takeOption(args, "--provider");
+  const model = takeOption(args, "--model");
+  const requestedModel = takeOption(args, "--requested-model");
+  const conversationId = takeOption(args, "--conversation") ?? takeOption(args, "--conversationId");
+  const surface = takeOption(args, "--surface");
+  const protocol = takeOption(args, "--protocol");
+  const apiKeyId = takeOption(args, "--api-key-id");
+  const profileId = takeOption(args, "--profile");
+  const fallbackRaw = takeOption(args, "--fallback");
+  const cursor = takeOption(args, "--cursor");
+  const status = takeIntegerOption(args, "--status", { min: 100 });
+  const limit = takeIntegerOption(args, "--limit", { min: 1 }) ?? REQUEST_HISTORY_DEFAULT_PAGE_SIZE;
+  const from = timestampOption(args, "--from");
+  const to = timestampOption(args, "--to");
+  rejectArgs(args, LOG_HISTORY_USAGE);
+  if (wantsJson && wantsJsonl) throw new CliUsageError("--json and --jsonl cannot be combined", LOG_HISTORY_USAGE);
+  if (status !== undefined && status > 599) throw new CliUsageError("--status must be an integer from 100 to 599", LOG_HISTORY_USAGE);
+  if (limit > REQUEST_HISTORY_MAX_PAGE_SIZE) {
+    throw new CliUsageError(`--limit must be between 1 and ${REQUEST_HISTORY_MAX_PAGE_SIZE}`, LOG_HISTORY_USAGE);
+  }
+  if (protocol !== undefined && !PROTOCOLS.includes(protocol as (typeof PROTOCOLS)[number])) {
+    throw new CliUsageError(`--protocol must be one of ${PROTOCOLS.join(", ")}`, LOG_HISTORY_USAGE);
+  }
+  let fallback: boolean | undefined;
+  if (fallbackRaw !== undefined) {
+    if (fallbackRaw !== "true" && fallbackRaw !== "false") {
+      throw new CliUsageError("--fallback must be true or false", LOG_HISTORY_USAGE);
+    }
+    fallback = fallbackRaw === "true";
+  }
+  if (from !== undefined && to !== undefined && from > to) {
+    throw new CliUsageError("--from must not be after --to", LOG_HISTORY_USAGE);
+  }
+  const data = await runtimeRequest(`/api/request-history${query({
+    provider, model, requestedModel, status, conversationId, surface,
+    inboundProtocol: protocol, apiKeyId, profileId, fallback, from, to, cursor, limit,
+  })}`, {}, deps);
+  const page = historyPage(data);
+  if (wantsJson) {
+    printData(data, true);
+    return;
+  }
+  if (wantsJsonl) {
+    for (const row of page.entries) console.log(JSON.stringify(row));
+    if (page.hasMore && page.nextCursor) console.error(`nextCursor=${page.nextCursor}`);
+    return;
+  }
+  const indexed = typeof page.index?.indexedRows === "number" ? page.index.indexedRows : undefined;
+  if (page.entries.length === 0) {
+    printData(data, false, [
+      "No request-history row matched the filters.",
+      ...(indexed !== undefined ? [`indexedRows=${indexed}`] : []),
+    ]);
+    return;
+  }
+  const footer = [
+    ...(indexed !== undefined ? [`indexedRows=${indexed}`] : []),
+    `hasMore=${page.hasMore}`,
+    ...(page.nextCursor ? [`nextCursor=${page.nextCursor}`] : []),
+  ];
+  printData(data, false, [...page.entries.map(row => formatHistoryRow(row, formatRow)), ...footer]);
+}
+
+/** Read one canonical request-history row through GET /api/request-history/{id}. */
+export async function handleLogGetCommand(
+  argv: string[],
+  deps: RuntimeApiDeps,
+  formatRow: (row: LogRow) => string,
+): Promise<void> {
+  const args = [...argv];
+  const requestId = args.shift();
+  const wantsJson = takeFlag(args, "--json");
+  if (!requestId) throw new CliUsageError("request id is required", GET_USAGE);
+  rejectArgs(args, GET_USAGE);
+  const result = await runtimeRequest(`/api/request-history/${encodeURIComponent(requestId)}`, {}, deps);
+  if (!record(result)) throw new Error("Invalid request-history row. Upgrade the proxy and retry.");
+  printData(result, wantsJson, wantsJson ? undefined : [formatHistoryRow(result, formatRow)]);
+}

package/src/cli/loopback-family.ts

@@ -0,0 +1,31 @@
+/** A failed connect cannot distinguish an absent loopback address from a slow owner. */
+export type LoopbackFamilyAvailability = "available" | "unavailable" | "unknown";
+
+function bindLoopback(hostname: string): { stop(): void } {
+  return Bun.listen({ hostname, port: 0, socket: { data(socket) { socket.end(); } } });
+}
+
+/**
+ * Ask the kernel whether the concrete local address can be bound, independently of
+ * routing/connect timeouts. Only address/family absence permits skipping discovery;
+ * permissions, resource exhaustion and other failures leave owner evidence unknown.
+ * The ephemeral listener is closed synchronously and never accepts client traffic.
+ */
+export function loopbackFamilyAvailability(
+  hostname: string,
+  bindFn: (hostname: string) => { stop(): void } = bindLoopback,
+): LoopbackFamilyAvailability {
+  const address = hostname === "[::1]" ? "::1" : hostname;
+  if (address !== "::1" && address !== "127.0.0.1") return "unknown";
+  let listener: { stop(): void };
+  try {
+    listener = bindFn(address);
+  } catch (error) {
+    const code = (error as { code?: unknown } | null)?.code;
+    return code === "EADDRNOTAVAIL" || code === "EAFNOSUPPORT"
+      || code === "EPROTONOSUPPORT"
+      ? "unavailable" : "unknown";
+  }
+  listener.stop();
+  return "available";
+}

package/src/cli/models-runtime-subcommands.ts

@@ -28,6 +28,7 @@ export const MODELS_RUNTIME_SUBCOMMANDS = [
   "new-arrivals",
   "context",
   "shadow",
+  "auto-review",
   "order",
   "display-name",
 ] as const;

package/src/cli/models-runtime.ts

@@ -21,7 +21,7 @@ import { redactSecretString } from "../lib/redact";
 import type { ProviderCostOverlay } from "../types";
 import { resolveMatchedPrice } from "../usage/cost";
 import { MAX_COST4_RATE } from "../usage/expected-prices";
-import { isValidCost4Rate } from "../usage/user-cost-overlays";
+import { isValidCost4Rate, validCost4 } from "../usage/user-cost-overlays";
 
 const USAGE = `Usage:
   ocx models display-name <provider/raw-model> (--set <text> | --clear) [--json]
@@ -48,6 +48,7 @@ const USAGE = `Usage:
   ocx models new-arrivals [--json]
 ${MODELS_CONTEXT_USAGE}
   ocx models shadow <status|set> [model|-] [--enabled <on|off>] [--json]
+  ocx models auto-review <status|set> [model|-] [--enabled <on|off>] [--json]
 
 Prices are USD per 1M tokens. Omitted cache rates default to 0.
 Price selectors use the exact upstream model ID after the first slash.`;
@@ -89,8 +90,8 @@ function priceRecord(value: unknown): value is Record<string, unknown> {
 const PRICE_RATE_KEYS = ["input", "output", "cacheRead", "cacheWrite"] as const;
 
 function validPriceCost(value: unknown): value is ProviderCostOverlay {
-  return priceRecord(value) && Object.keys(value).length === PRICE_RATE_KEYS.length
-    && PRICE_RATE_KEYS.every(key => Object.hasOwn(value, key) && isValidCost4Rate(value[key]));
+  return priceRecord(value) && validCost4(value)
+    && Object.keys(value).every(key => key === "promptLengthPricing" || (PRICE_RATE_KEYS as readonly string[]).includes(key));
 }
 
 async function price(write: boolean, argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -135,7 +136,9 @@ async function priceRequest(write: boolean, argv: string[], deps: RuntimeApiDeps
     }
     // The API map owns manual overrides; bundled defaults remain derived rather
     // than being persisted as overrides that would mask later catalog updates.
-    const effectiveCost = cost ?? resolveMatchedPrice(provider, modelId, undefined, [])?.cost4 ?? null;
+    const effectiveCost = cost
+      ? { input: cost.input, output: cost.output, cacheRead: cost.cacheRead, cacheWrite: cost.cacheWrite }
+      : resolveMatchedPrice(provider, modelId, undefined, [])?.cost4 ?? null;
     printData({ provider, modelId, cost, effectiveCost }, wantsJson, [
       effectiveCost === null ? `${selector}: automatic pricing (unknown)`
         : `${selector}: ${JSON.stringify(effectiveCost)} USD per 1M tokens${cost === null ? " (automatic estimate)" : ""}`,
@@ -161,17 +164,42 @@ async function priceRequest(write: boolean, argv: string[], deps: RuntimeApiDeps
     }
     return value;
   };
-  const cost: ProviderCostOverlay | null = auto ? null : {
+  // Validate every rate before any request, so a bad flag never reaches the management plane.
+  const rates: ProviderCostOverlay | undefined = auto ? undefined : {
     input: rate(input!, "--input"),
     output: rate(output!, "--output"),
     cacheRead: rate(cacheRead ?? "0", "--cache-read"),
     cacheWrite: rate(cacheWrite ?? "0", "--cache-write"),
   };
+  // A base-rate write replaces the whole row, so read the current row first and carry the
+  // stored prompt-length policy for exactly this model forward instead of silently deleting it.
+  let carriedPromptLengthPricing: ProviderCostOverlay["promptLengthPricing"];
+  if (rates) {
+    const current = await runtimeRequest<unknown>(path, {}, deps);
+    if (!priceRecord(current) || current.provider !== provider || !priceRecord(current.modelCosts)
+      || !Object.values(current.modelCosts).every(validPriceCost)) {
+      throw new Error("Invalid model price response");
+    }
+    if (Object.hasOwn(current.modelCosts, modelId)) {
+      carriedPromptLengthPricing = (current.modelCosts[modelId] as ProviderCostOverlay).promptLengthPricing;
+    }
+  }
+  const cost: ProviderCostOverlay | null = rates
+    ? { ...rates, ...(carriedPromptLengthPricing ? { promptLengthPricing: carriedPromptLengthPricing } : {}) }
+    : null;
   const result = await runtimeRequest(path, { method: "PUT", body: JSON.stringify({ modelId, cost }) }, deps);
+  // Absent and { mode: "automatic" } are the same policy (the server stores automatic as
+  // absent), and key order carries no meaning in a JSON receipt, so compare canonically.
+  const canonicalPolicy = (policy: ProviderCostOverlay["promptLengthPricing"]): string =>
+    policy === undefined || policy.mode === "automatic" ? `{"mode":"automatic"}`
+      : JSON.stringify(policy, (_key, item: unknown) => (item && typeof item === "object" && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : item));
   const receivedCost = priceRecord(result) ? result.cost : undefined;
   if (!priceRecord(result) || result.ok !== true || result.provider !== provider || result.modelId !== modelId
     || (cost === null ? receivedCost !== null : !validPriceCost(receivedCost)
-      || !PRICE_RATE_KEYS.every(key => receivedCost[key] === cost[key]))) {
+      || !PRICE_RATE_KEYS.every(key => receivedCost[key] === cost[key])
+      || canonicalPolicy(receivedCost.promptLengthPricing) !== canonicalPolicy(cost.promptLengthPricing))) {
     throw new Error("Invalid model price persistence receipt");
   }
   // Project the acknowledged fields only; unrelated response fields are not CLI output.
@@ -566,6 +594,39 @@ async function shadow(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, ["Shadow-call settings updated."]);
 }
 
+async function autoReview(argv: string[], deps: RuntimeApiDeps): Promise<number | void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "status").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/auto-review-settings", {}, deps);
+    printData(result, wantsJson);
+    return;
+  }
+  if (action !== "set") throw new CliUsageError("unknown auto-review action " + action, USAGE);
+  const modelRaw = args[0] && !args[0].startsWith("--") ? args.shift() : undefined;
+  const enabled = takeBooleanOption(args, "--enabled");
+  rejectArgs(args, USAGE);
+  const body: Record<string, unknown> = {};
+  if (modelRaw !== undefined) body.model = modelRaw === "-" ? "" : modelRaw;
+  if (enabled !== undefined) body.enabled = enabled;
+  if (Object.keys(body).length === 0) throw new CliUsageError("model and/or --enabled is required", USAGE);
+  const result = await runtimeRequest<{ catalogRefresh?: { status?: string; retryable?: boolean } }>(
+    "/api/auto-review-settings", { method: "PUT", body: JSON.stringify(body) }, deps,
+  );
+  const refresh = result.catalogRefresh;
+  printData(result, wantsJson, [
+    "Auto-review settings updated.",
+    ...(refresh?.status === "failed"
+      ? ["Settings saved, but the Codex model catalog refresh failed. Resolve the refresh issue before running ocx sync."]
+      : refresh?.status === "skipped" && refresh.retryable === true
+        ? ["Settings saved, but the Codex model catalog refresh is pending. Run ocx sync to retry."]
+        : []),
+  ]);
+  if (refresh?.status === "failed") return 1;
+}
+
 export async function handleModelsRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
   if (sub === "order" || sub === "display-name") {
     const { handleModelsOrderCommand, handleModelsDisplayNameCommand } = await import("./models-order");
@@ -574,7 +635,7 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   // The dispatch below and MODELS_RUNTIME_SUBCOMMANDS must name the same set;
   // tests/cli/cli-models-runtime-dispatch.test.ts fails if they drift (#3094).
   if (!isModelsRuntimeSubcommand(sub)) return null;
-  let action: (() => Promise<void>) | undefined;
+  let action: (() => Promise<number | void>) | undefined;
   if (sub === "live") action = () => live(argv, deps);
   else if (sub === "price") action = () => price(false, argv, deps);
   else if (sub === "set-price") action = () => price(true, argv, deps);
@@ -589,8 +650,11 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   else if (sub === "new-arrivals") action = () => newArrivals(argv, deps);
   else if (sub === "context") action = () => context(argv, deps);
   else if (sub === "shadow") action = () => shadow(argv, deps);
+  else if (sub === "auto-review") action = () => autoReview(argv, deps);
   if (!action) return null;
-  return runCliAction(action);
+  let outcome: number | void = 0;
+  const exit = await runCliAction(async () => { outcome = await action(); });
+  return exit || outcome || 0;
 }
 
 export const MODELS_RUNTIME_USAGE = USAGE;

package/src/cli/observe-stream.ts

@@ -14,6 +14,8 @@ export interface ObserveStreamDeps extends RuntimeApiDeps {
   /** Reduced timings for isolated tests only; never command-line options. */
   pollIntervalMs?: number;
   requestTimeoutMs?: number;
+  /** Frozen clock for usage-compare tests; never a command-line option. */
+  now?: () => number;
 }
 
 export class ObservationError extends Error {}

package/src/cli/observe.ts

@@ -14,9 +14,11 @@ import {
 } from "./runtime-api";
 import { followLogs } from "./log-follow";
 import { handleLogFilterCommand } from "./log-view-filter";
+import { handleLogGetCommand, handleLogHistoryCommand } from "./log-history";
 import { followInjection } from "./injection-follow";
 import type { ObserveStreamDeps } from "./observe-stream";
 import { formatUsageReport } from "./usage-report";
+import { handleUsageCompareCommand } from "./usage-compare";
 import { selectUsageModelView, takeUsageSearchOption } from "./usage-model-search";
 import { USAGE_RANGES, USAGE_SURFACES, type UsageSummary, type UsageFilterEcho } from "../usage/summary";
 import { parseUsageTimeWindow, type UsageTimeWindow } from "../usage/time-range";
@@ -30,12 +32,16 @@ const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
       [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl] [--events]
   ocx logs explain <request-id> [--json]
+  ocx logs history [selectors] [--cursor <token>] [--limit <1-100>] [--json|--jsonl]
+  ocx logs get <request-id> [--json]
   ocx logs filter [selectors] [--scan-limit <1..2000>] [--limit <1..2000>] [--json|--jsonl]
   ocx logs rebuild-index
   ocx logs index-status
   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]
+      [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--top <1-1000>] [--json]
+  ocx usage compare [--range <today|1d|7d|30d>] [--surface <all|codex|claude|grok>]
+      [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]
   ocx observe storage [codex-logs [status|protect|unprotect|repair|compact] [--mode <compat|quiet>]] [--json]
   ocx observe memory [--json]
   ocx observe debug [--json]
@@ -174,6 +180,7 @@ async function indexStatus(argv: string[], deps: RuntimeApiDeps): Promise<void>
 async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const search = takeUsageSearchOption(args);
+  const top = takeIntegerOption(args, "--top", { min: 1, max: 1000 });
   const wantsJson = takeFlag(args, "--json");
   const range = takeOption(args, "--range") ?? "30d";
   const surface = takeOption(args, "--surface") ?? "all";
@@ -246,10 +253,10 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   // the call, so passing formatUsageReport(...) inline would run the human
   // renderer during --json and let its assumptions affect a path that is meant
   // to bypass it entirely.
-  const view = search === undefined ? undefined : selectUsageModelView(result, search);
+  const view = search === undefined ? undefined : selectUsageModelView(result, search, wantsJson ? undefined : top);
   const displayed = view ?? result;
   if (wantsJson) printData(displayed, true);
-  else printData(displayed, false, formatUsageReport(displayed as Parameters<typeof formatUsageReport>[0], view ? { modelView: view.modelView } : undefined));
+  else printData(displayed, false, formatUsageReport(displayed as Parameters<typeof formatUsageReport>[0], { modelView: view?.modelView, modelRowLimit: top }));
 }
 
 async function simple(path: string, argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -320,12 +327,17 @@ export async function handleObserveCommand(argv: string[], deps: ObserveStreamDe
     if (sub === "logs") {
       const action = rest[0];
       if (action === "filter") streamExit = await handleLogFilterCommand(rest.slice(1), deps, formatLog);
+      else if (action === "history") await handleLogHistoryCommand(rest.slice(1), deps, formatLog);
+      else if (action === "get") await handleLogGetCommand(rest.slice(1), deps, formatLog);
       else if (action === "explain") await explain(rest.slice(1), deps);
       else if (action === "rebuild-index") await rebuildIndex(rest.slice(1), deps);
       else if (action === "index-status") await indexStatus(rest.slice(1), deps);
       else streamExit = await logs(rest, deps);
     }
-    else if (sub === "usage") await usage(rest, deps);
+    else if (sub === "usage") {
+      if (rest[0] === "compare") await handleUsageCompareCommand(rest.slice(1), deps);
+      else await usage(rest, deps);
+    }
     else if (sub === "storage") await storage(rest, deps);
     else if (sub === "memory") await simple("/api/system/memory", rest, deps);
     else if (sub === "debug") await simple("/api/debug", rest, deps);