@bitkyc08/opencodex 2.86.0 → 2.87.0

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/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);

package/src/cli/provider.ts

@@ -8,13 +8,15 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate, withConfigMutationLockSync } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, readConfigAdmissionSnapshot, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate, withConfigMutationLockSync } from "../config";
 import { apiKeyTransportConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../config/provider-validation";
 import { hasHelpFlag, printSubcommandUsage } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
 import { assertAnthropicInstanceLoginConfig } from "../oauth/store-anthropic-instance";
 import { dropProviderCustomModels } from "../providers/provider-id-rewrite";
+import { cleanupRemovedGcpCredentials, commitProviderGcpCredentialRemoval, providerGcpCredentialMarkers } from "../providers/gcp-credential-cleanup";
+import { providerCredentialInputError } from "../providers/api-keys";
 import type { OcxProviderConfig } from "../types";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { syncModelsToCodex } from "../codex/sync";
@@ -223,6 +225,12 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
   if (registryEntry) {
     provConfig = providerConfigSeed(registryEntry);
     if (apiKey) {
+      const candidateError = providerCredentialInputError({ apiKey });
+      if (candidateError) {
+        console.error(`Error: ${candidateError}`);
+        process.exitCode = 2;
+        return;
+      }
       if ((authMode ?? registryEntry.authKind) === "forward") {
         console.warn(`Warning: provider "${name}" uses ChatGPT login (forward auth); --api-key is ignored.`);
       } else if ((authMode ?? registryEntry.authKind) === "oauth") {
@@ -249,6 +257,12 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
   }
 
   if (responsesPath !== undefined) provConfig.responsesPath = responsesPath;
+  const credentialError = providerCredentialInputError(provConfig);
+  if (credentialError) {
+    console.error(`Error: ${credentialError}`);
+    process.exitCode = 2;
+    return;
+  }
   if (authMode !== undefined) provConfig.authMode = authMode as OcxProviderConfig["authMode"];
   if (name === "anthropic2") {
     if (provConfig.adapter !== "anthropic" || provConfig.authMode !== "oauth") delete provConfig.anthropicOAuthInstance;
@@ -328,12 +342,17 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
   }
   const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
   let markerCollision = false;
+  let removedCredentials: string[] = [];
   withConfigMutationLockSync(() => {
     if (provConfig.anthropicOAuthInstance) {
       try { assertAnthropicInstanceLoginConfig(config, name); }
       catch { markerCollision = true; return; }
     }
     initializeProviderModelSelection(name, provConfig, existingProvider, config);
+    const durable = readConfigAdmissionSnapshot();
+    const durableProvider = durable.kind === "read" && durable.diagnostics.source === "file"
+      && durable.diagnostics.error === null ? durable.diagnostics.config.providers[name] : undefined;
+    removedCredentials = [config.providers[name], durableProvider].flatMap(provider => provider ? providerGcpCredentialMarkers(provider) : []);
     config.providers[name] = provConfig;
     if (setDefault) config.defaultProvider = name;
     validateAndSave(config);
@@ -344,6 +363,7 @@ async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<voi
     return;
   }
 
+  cleanupRemovedGcpCredentials(removedCredentials);
   let sync: LocalSyncResult | undefined;
   if (wantsSync) {
     try {
@@ -440,10 +460,12 @@ function handleRemove(args: string[]): void {
     process.exit(1);
   }
 
-  delete config.providers[name];
-  const droppedCustomModels = dropProviderCustomModels(config, name);
-  validateAndSave(config);
-
+  const droppedCustomModels = commitProviderGcpCredentialRemoval(config, name, () => {
+    delete config.providers[name];
+    const dropped = dropProviderCustomModels(config, name);
+    validateAndSave(config);
+    return dropped;
+  });
 
   if (wantsJson) {
     console.log(JSON.stringify({

package/src/cli/registry.ts

@@ -8,6 +8,12 @@ export interface CliCommandEntry {
 }
 
 export const CLI_COMMANDS: CliCommandEntry[] = [
+  {
+    name: "codex-provider",
+    usage: "ocx codex-provider <status|allow <id> [--yes]|revoke <id>>",
+    summary: "Explicitly allow or revoke local routing management for a custom Codex provider.",
+    details: ["Consent is bound to the selected CODEX_HOME and provider ID. Only base_url is managed; transport settings and history are preserved."],
+  },
   {
     name: "message",
     usage: "ocx message <sessions|send> [options]",
@@ -178,7 +184,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "Fetch provider models and inject them into Codex config.",
     details: [
       "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
-      "--restart-codex restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, so its model picker re-reads the catalog. It ends live conversations.",
+      "--restart-codex restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, after catalog/cache writes or a committed configuration change. It ends live conversations.",
       "--restart-app-server-only keeps the narrow behaviour: SIGTERM to matching app-server / code-mode-host processes, desktop app left running. It wins over --restart-codex when both are given.",
       "--restart-desktop-app is a deprecated alias of --restart-codex and prints a notice.",
     ],
@@ -226,9 +232,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "login",
-    usage: "ocx login <provider>",
+    usage: "ocx login <provider> [--headless]",
     summary: "OAuth or API-key login for a provider.",
     details: [
+      "--headless (anthropic, anthropic2): no browser and no local port; approve in any browser and paste the displayed code.",
       "Codex/ChatGPT: ocx login codex runs the Codex account-pool login (same flow as ocx account login codex).",
       "That one needs a running proxy; the OAuth and API-key providers log in locally.",
       "'chatgpt' and 'openai' are the same route; an OpenAI platform API key is 'ocx login openai-apikey'.",
@@ -336,6 +343,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
       "pool <provider>          Read/edit runtime-supported pool policy.",
       "credits openai ...       Explicit paid-credit-after-limit policy; separate from displaying balances.",
+      "use-remaining openai <id|main> <on|off|status>  Use included quota up to its limit.",
       "quota-activation openai  Enable/disable one account reset-window refresh policy.",
       "anthropic-reset-grants   Read grant status only; consumption remains in the dashboard.",
       "login supports explicit browser/add-account options only for applicable flows; human verification remains required.",
@@ -444,11 +452,21 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "`inspect star` reads the repository star status only. Starring uses your GitHub identity and is available from the dashboard alone.",
     ],
   },
-  { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl|--events]", summary: "Read or follow request logs." },
+  {
+    name: "logs",
+    usage: "ocx logs [filters] [--follow] [--json|--jsonl|--events]; ocx logs history [selectors] [--cursor <token>] [--json|--jsonl]; ocx logs get <request-id> [--json]",
+    summary: "Read or follow request logs.",
+    details: [
+      "Default reads the recent ring. `history` pages the derived index with a resumable cursor; `get` reads one canonical row; `explain` is the route-decision view.",
+    ],
+  },
   {
     name: "usage",
-    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--top <1-1000>] [--json]; ocx usage compare [--range <today|1d|7d|30d>] [--json]",
     summary: "Report token usage and estimated cost (alias of ocx observe usage).",
+    details: [
+      "`compare` reads the current named range and the previous equal window; `--range all` is refused.",
+    ],
   },
   {
     name: "storage",
@@ -486,13 +504,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "export",
-    usage: "ocx export --client <qoder|opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|commandcode|prime|aside|raycast|omo|cline|kilo|droid> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid, Qoder) wired to the running proxy.",
+    usage: "ocx export --client <qoder|opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|commandcode|prime|aside|raycast|omo|cline|kilo|droid|gentle-shell> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid, Qoder, Gentle Shell) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",
       "Cline exports a two-document bundle: settings for providers.json and catalog for sibling models.json. Use integration client enable --client cline for a journaled write.",
       "Droid exports documented customModels for settings.json; use integration client enable --client droid for a journaled write.",
+      "Gentle Shell uses its persistent selected home; use integration client enable --client gentle-shell for a journaled write, or Pi for link/shared homes.",
       "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
       "The destination path is printed for merging by hand — ocx never writes your real client config.",
     ],
@@ -516,14 +535,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   {
     name: "system",
     usage: "ocx system <status|health|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...",
-    summary: "Manage headless runtime settings, startup, sync, diagnostics, OpenCodex updates, and read-only Codex CLI inspection.",
+    summary: "Manage headless runtime settings, health, startup, sync, diagnostics, OpenCodex updates, and read-only Codex CLI inspection and planning.",
     details: [
       "system update manages OpenCodex itself.",
       "system health reads authenticated service and spend-ledger diagnostics; root health remains liveness.",
       "ocx system codex-cli-update check [--json]",
       "ocx system codex-cli-update attest [--json]",
       "ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]",
-      "The Codex CLI inspection command makes no package-registry request, does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state.",
+      "ocx system codex-cli-update plan [--channel latest] [--json]",
+      "check and attest make no package-registry request, do not execute Codex or npm, and write nothing. plan adds a registry query and a process-table read and mutates no application state (temporary isolated npm files only, removed best-effort).",
     ],
   },
   {