@bitkyc08/opencodex 2.86.0 → 2.88.0

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).",
     ],
   },
   {

package/src/cli/runtime-api.ts

@@ -279,13 +279,15 @@ export function takeBooleanOption(args: string[], flag: string): boolean | undef
 }
 
 /** Parse a decimal safe integer, allowing separators only between digits. */
-export function takeIntegerOption(args: string[], flag: string, options: { min?: number } = {}): number | undefined {
+export function takeIntegerOption(args: string[], flag: string, options: { min?: number; max?: number } = {}): number | undefined {
   const raw = takeOption(args, flag);
   if (raw === undefined) return undefined;
   const decimal = raw.trim();
   const value = /^[+-]?\d+(?:[_,]\d+)*$/.test(decimal) ? Number(decimal.replace(/[_,]/g, "")) : NaN;
-  if (!Number.isSafeInteger(value) || value < (options.min ?? Number.MIN_SAFE_INTEGER)) {
-    throw new CliUsageError(`${flag} must be an integer${options.min !== undefined ? ` >= ${options.min}` : ""}`);
+  const { min, max } = options;
+  if (!Number.isSafeInteger(value) || value < (min ?? Number.MIN_SAFE_INTEGER) || value > (max ?? Number.MAX_SAFE_INTEGER)) {
+    const bound = min !== undefined && max !== undefined ? ` between ${min} and ${max}` : min !== undefined ? ` >= ${min}` : max !== undefined ? ` <= ${max}` : "";
+    throw new CliUsageError(`${flag} must be an integer${bound}`);
   }
   return value;
 }

package/src/cli/system-command.ts

@@ -28,6 +28,7 @@ const USAGE = `Usage:
   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]
+  ocx system codex-cli-update plan [--channel latest] [--json]
   ocx system update check [--channel <latest|preview>] [--json]
   ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]
   ocx system update status <job-id> [--json]
@@ -270,24 +271,55 @@ export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps =
       const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
       printData(await runtimeRequest("/api/system/codex-app-server", {}, deps), wantsJson);
     } else if (sub === "codex-restart") {
-      // --yes required: this fully quits and relaunches the user's Codex desktop app as well as
-      // restarting app-servers, which can discard unsaved drafts, selections, and approval prompts.
+      // --yes required: this interrupts running Codex turns, and when the desktop picker predates
+      // the catalog it also quits and relaunches the app, which can discard unsaved client state.
       const args = [...rest];
       const wantsJson = takeFlag(args, "--json");
       const yes = takeFlag(args, "--yes");
       if (!yes) throw new CliUsageError(
-        "system codex-restart requires --yes: this fully quits and relaunches the Codex desktop app, so unsaved composer drafts, model-picker selections, and pending approval prompts may be lost; it also restarts the app-servers",
+        "system codex-restart requires --yes: this restarts the Codex app-servers, interrupting running turns, and when the desktop app's model picker predates the current catalog (or that cannot be determined) it fully quits and relaunches the Codex desktop app, so unsaved composer drafts, model-picker selections, and pending approval prompts may be lost",
         USAGE,
       );
       rejectArgs(args, USAGE);
-      printData(
-        await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps),
-        wantsJson,
-        ["Codex desktop app and app-server restart requested. Unsaved composer drafts, model-picker selections, and pending approval prompts may be lost."],
-      );
+      const result = await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps);
+      printData(result, wantsJson, codexRestartLines(result));
     } else if (sub === "update") await update(rest, deps);
     else throw new CliUsageError(`unknown system command ${sub}`, USAGE);
   });
 }
 
+/**
+ * Operator text for a codex-restart outcome. It reports what happened to the desktop app,
+ * because whether unsaved client state survived is the one thing the operator needs to know.
+ */
+export function codexRestartLines(result: unknown): string[] {
+  const view = recordValue(result);
+  const desktop = recordValue(view?.desktopApp);
+  const reason = typeof desktop?.reason === "string" ? desktop.reason : undefined;
+  // Only a reported `stale` reading may claim the picker predated the catalog; an unreadable
+  // reading also takes the full restart, and an older proxy reports no reading at all.
+  const why = desktop?.pickerState === "stale"
+    ? "its model picker predated the current catalog"
+    : "its model picker could not be confirmed current";
+  const stopped = Array.isArray(view?.stopped) ? view.stopped.length : 0;
+  const appServers = view?.code === "stopped"
+    ? `Stopped ${stopped} Codex app-server(s); their owners start replacements.`
+    : view?.code === "partially_stopped"
+      ? "Some Codex app-servers did not exit; stop them manually if Codex stays stale."
+      : view?.code === "enumeration_unavailable"
+        ? "Could not list Codex app-servers, so none were stopped."
+        : "No Codex app-server needed stopping.";
+  if (reason === "picker_current") {
+    return [appServers, "The Codex desktop app was left running: its model picker already shows the current catalog, so unsaved drafts and pending approvals were kept."];
+  }
+  if (reason === "no_targets") return [appServers, "The Codex desktop app is not running."];
+  if (desktop?.relaunch === "started") {
+    return [appServers, `The Codex desktop app was quit and relaunched because ${why}. Unsaved composer drafts, model-picker selections, and pending approval prompts may have been lost.`];
+  }
+  if (desktop?.attempted === true) {
+    return [appServers, `The Codex desktop app restart did not complete (${reason ?? "no outcome reported"}). Unsaved composer drafts, model-picker selections, and pending approval prompts may have been lost.`];
+  }
+  return [appServers, `The Codex desktop app was not restarted (${reason ?? "no outcome reported"}).`];
+}
+
 export const SYSTEM_USAGE = USAGE;

package/src/cli/uninstall-client-state.ts

@@ -5,9 +5,13 @@ import { assertClientLifecycleHeld, withClientLifecycle } from "../client/lifecy
 import { inspectRemoteDesktopCleanup, readDesktopDisconnectReceipt } from "../claude/desktop-remote-store";
 import { removeOwnedConfigState, type ConfigRemovalResult } from "../lib/config-ownership";
 import { windowsSecretAclReapPendingAtOrBelow } from "../lib/windows-secret-acl";
+import { supportsDesktopPicker } from "../claude/desktop-picker-platform";
 import { sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { cleanupOwnedIntegrationsBeforeUninstall } from "./uninstall-integrations";
 
+/** Outcome of retiring the Desktop picker profile and every picker root this install trusted. */
+export interface PickerUninstallCleanup { ok: boolean; residual?: string[] }
+
 export interface UninstallClientStateDeps {
   readConnection: typeof readClientConnectionState;
   inspectDesktop: typeof inspectRemoteDesktopCleanup;
@@ -18,6 +22,25 @@ export interface UninstallClientStateDeps {
   remove: () => ConfigRemovalResult;
   /** True while a timed-out icacls child still owns a path at or below the config directory. */
   aclReapPending: (rootPath: string) => boolean;
+  /** Release the picker profile, then untrust the current and any pending predecessor picker root. */
+  removePickerArtifacts: () => Promise<PickerUninstallCleanup>;
+}
+
+/**
+ * The picker root lives in the OS trust store (login keychain, CurrentUser Root on Windows), outside
+ * the config directory. Deleting config first would erase ca.pem and the pending-untrust journal,
+ * the only records naming which root to remove, and strand a trusted root after uninstall.
+ */
+async function removePickerArtifactsBeforeUninstall(): Promise<PickerUninstallCleanup> {
+  if (!supportsDesktopPicker()) return { ok: true };
+  const configDir = getConfigDir();
+  const [{ removeDesktopPickerArtifacts }, { drainPendingPickerCaUntrust }] = await Promise.all([
+    import("../claude/desktop-picker"),
+    import("../claude/intercept/picker-ca-cleanup"),
+  ]);
+  const removed = await removeDesktopPickerArtifacts({ configDir });
+  if (!removed.ok) return removed;
+  return await drainPendingPickerCaUntrust(configDir) ? { ok: true } : { ok: false, residual: ["pending_trust"] };
 }
 
 const defaults: UninstallClientStateDeps = {
@@ -29,6 +52,7 @@ const defaults: UninstallClientStateDeps = {
   cleanupIntegrations: cleanupOwnedIntegrationsBeforeUninstall,
   remove: () => removeOwnedConfigState(getConfigDir()),
   aclReapPending: rootPath => windowsSecretAclReapPendingAtOrBelow(rootPath),
+  removePickerArtifacts: removePickerArtifactsBeforeUninstall,
 };
 
 /** Restore connection-owned client artifacts before removing their ownership/recovery records. */
@@ -67,6 +91,14 @@ export async function removeOwnedConfigAfterDesktopCleanup(
     throw new Error("Client cleanup refused: finish Desktop recovery before uninstalling.");
   }
 
+  // Picker cleanup takes L itself, so it runs before the final lock. A residual keeps every
+  // record the retry needs: the config directory still names the root to untrust.
+  const picker = await deps.removePickerArtifacts();
+  if (!picker.ok) {
+    throw new Error(`Client cleanup refused: Claude Desktop picker cleanup left ${picker.residual?.join(", ") || "state"} behind; `
+      + "approve the certificate removal prompt or run 'ocx claude desktop picker off', then rerun 'ocx uninstall'.");
+  }
+
   // A connection can appear while asynchronous cleanup is finishing. The final
   // inspection and actual remover share L, but never hold C while deleting its DB.
   return deps.withLifecycle(async held => {

package/src/cli/usage-compare.ts

@@ -0,0 +1,309 @@
+/**
+ * Compare a bounded usage range with the previous equal window.
+ *
+ * Two sequential GET /api/usage reads with acknowledged custom bounds.
+ * `--range all` is refused: there is no previous equal window for open history.
+ */
+import { readClientConnectionState, sameClientConnectionOwner } from "../client/state";
+import { fetchHubUsage } from "../client/hub-client";
+import { readServiceApiTokenState, serviceApiTokenFingerprint } from "../lib/service-secrets";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+import { redactSecretString } from "../lib/redact";
+import { rangeWindow, USAGE_SURFACES } from "../usage/summary";
+import type { UsageTimeWindow } from "../usage/time-range";
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  RuntimeApiError,
+  runtimeRequest,
+  runtimeBaseUrl,
+  takeFlag,
+  takeOption,
+  takeOptionWithSyntax,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+export const USAGE_COMPARE_USAGE = `Usage:
+  ocx usage compare [--range <today|1d|7d|30d>] [--surface <all|codex|claude|grok>]
+      [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]`;
+
+export type CompareRange = "today" | "7d" | "30d";
+export type UsageCompareDeps = RuntimeApiDeps & { now?: () => number };
+
+const METRICS = ["requests", "totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "estimatedCostUsd"] as const;
+type Metric = typeof METRICS[number];
+type Totals = Partial<Record<Metric, number>>;
+type ScopedUsage = {
+  customWindow?: boolean;
+  since?: number | null;
+  until?: number;
+  summary?: Totals;
+  usageIncomplete?: boolean;
+  filter?: Record<string, unknown>;
+};
+
+function query(params: Record<string, string | number | 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 parseCompareRange(raw: string): CompareRange {
+  if (raw === "all") throw new CliUsageError("--range all has no previous equal window; use today, 1d, 7d or 30d", USAGE_COMPARE_USAGE);
+  if (raw === "today" || raw === "1d") return "today";
+  if (raw === "7d" || raw === "30d") return raw;
+  throw new CliUsageError("--range must be one of today, 1d, 7d, 30d", USAGE_COMPARE_USAGE);
+}
+
+/** Named range at `now`, then the same range evaluated one equal window earlier. */
+export function compareUsageWindows(range: CompareRange, now: number): {
+  current: UsageTimeWindow;
+  previous: UsageTimeWindow;
+  days: number;
+} {
+  const days = range === "today" ? 1 : range === "7d" ? 7 : 30;
+  const { since } = rangeWindow(range, now);
+  if (since === null) throw new Error("compare requires a bounded usage range");
+  const prior = new Date(now);
+  prior.setDate(prior.getDate() - days);
+  const priorNow = prior.getTime();
+  const { since: previousSince } = rangeWindow(range, priorNow);
+  if (previousSince === null) throw new Error("compare requires a bounded usage range");
+  return {
+    current: Object.freeze({ since, until: now }),
+    previous: Object.freeze({ since: previousSince, until: priorNow }),
+    days,
+  };
+}
+
+function metric(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function totalsOf(report: ScopedUsage): Totals {
+  const row = report.summary ?? {};
+  const totals: Totals = {};
+  for (const key of METRICS) {
+    const value = metric((row as Totals)[key]);
+    if (value !== undefined) totals[key] = value;
+  }
+  return totals;
+}
+
+function delta(current?: number, previous?: number): number | undefined {
+  if (current === undefined || previous === undefined) return undefined;
+  return current - previous;
+}
+
+function changePct(current?: number, previous?: number): number | null | undefined {
+  if (current === undefined || previous === undefined) return undefined;
+  if (previous === 0) return current === 0 ? 0 : null;
+  return (current - previous) / previous * 100;
+}
+
+function count(value: number | undefined): string {
+  return value === undefined ? "—" : value.toLocaleString("en-US");
+}
+
+function usd(value: number | undefined): string {
+  return value === undefined ? "—" : `~$${value.toFixed(4)}`;
+}
+
+function signed(value: number | undefined, money: boolean): string {
+  if (value === undefined) return "—";
+  const abs = money ? usd(Math.abs(value)) : count(Math.abs(value));
+  if (value === 0) return money ? usd(0) : "0";
+  return `${value > 0 ? "+" : "-"}${abs}`;
+}
+
+function pct(value: number | null | undefined): string {
+  if (value === undefined) return "—";
+  if (value === null) return "n/a";
+  const abs = Math.abs(value).toFixed(1);
+  if (value === 0) return "0.0%";
+  return `${value > 0 ? "+" : "-"}${abs}%`;
+}
+
+function iso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+function formatCompare(input: {
+  range: CompareRange;
+  days: number;
+  currentWindow: UsageTimeWindow;
+  previousWindow: UsageTimeWindow;
+  current: Totals;
+  previous: Totals;
+  incomplete: boolean;
+}): string[] {
+  const lines = [
+    `Usage compare — ${input.range} vs previous ${input.days} local day${input.days === 1 ? "" : "s"} (equal window)`,
+    `Current   ${iso(input.currentWindow.since)} to ${iso(input.currentWindow.until)}`,
+    `Previous  ${iso(input.previousWindow.since)} to ${iso(input.previousWindow.until)}`,
+    "",
+  ];
+  if (input.incomplete) {
+    lines.push("WARNING: Usage is incomplete; some records could not be included. Totals reflect readable records only.", "");
+  }
+  const labels: Record<Metric, string> = {
+    requests: "Requests",
+    totalTokens: "Tokens",
+    inputTokens: "Input",
+    outputTokens: "Output",
+    cachedInputTokens: "Cached",
+    estimatedCostUsd: "Est. cost",
+  };
+  const rows = METRICS.map(key => {
+    const money = key === "estimatedCostUsd";
+    const show = money ? usd : count;
+    return [
+      labels[key],
+      show(input.current[key]),
+      show(input.previous[key]),
+      signed(delta(input.current[key], input.previous[key]), money),
+      pct(changePct(input.current[key], input.previous[key])),
+    ];
+  });
+  const header = ["METRIC", "CURRENT", "PREVIOUS", "DELTA", "CHANGE"];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(row => row[i]!.length)));
+  const line = (cols: string[]) => cols.map((c, i) => c.padEnd(widths[i]!)).join("  ").trimEnd();
+  lines.push(line(header), ...rows.map(line), "", "Not a billing receipt. Subscription usage or provider credits may apply instead.");
+  return lines;
+}
+
+// Private command-local authority; neither credentials nor fingerprints enter output.
+function captureUsageOwner() {
+  const connection = readClientConnectionState();
+  if (connection.kind === "invalid" || connection.kind === "mismatched") {
+    throw new Error(`Client usage unavailable: ${connection.reason}`);
+  }
+  const token = readServiceApiTokenState();
+  if (connection.kind === "connected" && (token.kind !== "present" || token.fingerprint !== connection.value.tokenFingerprint)) {
+    throw new Error("Client usage unavailable: the enrolled data key is missing or changed; repair the client connection");
+  }
+  const headers = runningProxyUpdateHeaders();
+  const fingerprint = connection.kind === "connected" ? connection.value.tokenFingerprint
+    : serviceApiTokenFingerprint(headers.get("X-OpenCodex-API-Key") ?? "");
+  return { connection, token, headers, fingerprint };
+}
+type UsageOwner = ReturnType<typeof captureUsageOwner>;
+
+function assertUsageOwner(owner: UsageOwner): void {
+  const current = readClientConnectionState();
+  const expected = owner.connection;
+  let same = current.kind === expected.kind;
+  if (expected.kind === "connected") {
+    const token = readServiceApiTokenState();
+    same = current.kind === "connected" && sameClientConnectionOwner(current.value, expected.value)
+      && current.value.transport === expected.value.transport
+      && JSON.stringify(current.value.link) === JSON.stringify(expected.value.link)
+      && current.value.tokenFingerprint === owner.fingerprint
+      && token.kind === "present" && token.fingerprint === owner.fingerprint;
+  } else {
+    same &&= serviceApiTokenFingerprint(runningProxyUpdateHeaders().get("X-OpenCodex-API-Key") ?? "") === owner.fingerprint;
+  }
+  if (!same) throw new Error("Usage owner changed during comparison; no comparison was produced. Retry for the current connection and credential.");
+}
+
+async function readUsage(
+  suffix: string,
+  window: UsageTimeWindow,
+  apiKeyId: string | undefined,
+  deps: RuntimeApiDeps,
+  owner: UsageOwner,
+): Promise<ScopedUsage> {
+  assertUsageOwner(owner);
+  const { connection, token } = owner;
+  let result: ScopedUsage;
+  if (connection.kind === "connected") {
+    if (apiKeyId !== undefined) {
+      throw new CliUsageError("--api-key-id is unavailable on connected clients; run on the hub for a selected key, or omit it for this client's usage", USAGE_COMPARE_USAGE);
+    }
+    if (token.kind !== "present" || token.fingerprint !== connection.value.tokenFingerprint) {
+      throw new Error("Client usage unavailable: the enrolled data key is missing or changed; repair the client connection");
+    }
+    const link = connection.value.transport === "link" && connection.value.link;
+    const peerFetch = deps.fetchImpl
+      ?? (link ? (await import("../client/link-home")).linkBoundFetch(connection.value, token.token) : undefined);
+    result = await fetchHubUsage(connection.value.serverUrl, token.token, new URLSearchParams(suffix.replace(/^\?/, "")), {
+      fetchImpl: peerFetch, timeoutMs: 60_000, ...(link ? { peer: "Home" as const } : {}),
+    });
+  } else if (apiKeyId === undefined) {
+    result = await runtimeRequest(`/api/usage${suffix}`, { headers: owner.headers }, deps);
+  } else {
+    try {
+      result = await runtimeRequest(`/api/usage${suffix}`, { redirect: "error", credentials: "omit", headers: owner.headers }, deps);
+    } catch (error) {
+      if (error instanceof RuntimeApiError && error.code === "proxy_not_running") throw error;
+      throw new Error("Key-scoped usage could not be read. Check runtime access and retry.");
+    }
+    if (result.filter?.apiKeyId !== apiKeyId) {
+      throw new Error("The server did not confirm the requested API key scope. Upgrade and restart the proxy, then retry.");
+    }
+  }
+  if (result?.customWindow !== true || result.since !== window.since || result.until !== window.until) {
+    throw new Error("The server did not confirm the requested custom usage window. Upgrade and restart the proxy, then retry.");
+  }
+  assertUsageOwner(owner);
+  return result;
+}
+
+/** Compare the current named range with the previous equal window through two /api/usage reads. */
+export async function handleUsageCompareCommand(argv: string[], deps: UsageCompareDeps = {}): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const range = parseCompareRange(takeOption(args, "--range") ?? "30d");
+  const surface = takeOption(args, "--surface") ?? "all";
+  const provider = takeOption(args, "--provider");
+  const model = takeOption(args, "--model");
+  const rawKeyId = takeOptionWithSyntax(args, "--api-key-id")?.value;
+  const apiKeyId = rawKeyId?.trim();
+  if (apiKeyId !== undefined && !apiKeyId) throw new CliUsageError("--api-key-id must not be blank", USAGE_COMPARE_USAGE);
+  if (takeOption(args, "--since") !== undefined || takeOption(args, "--until") !== undefined) {
+    throw new CliUsageError("compare derives both windows; do not pass --since or --until", USAGE_COMPARE_USAGE);
+  }
+  if (!USAGE_SURFACES.includes(surface as (typeof USAGE_SURFACES)[number])) {
+    throw new CliUsageError(`--surface must be one of ${USAGE_SURFACES.join(", ")}`, USAGE_COMPARE_USAGE);
+  }
+  rejectArgs(args.map(redactSecretString), USAGE_COMPARE_USAGE);
+  const now = deps.now?.() ?? Date.now();
+  if (!Number.isSafeInteger(now) || now < 0) throw new CliUsageError("compare clock is invalid", USAGE_COMPARE_USAGE);
+  const windows = compareUsageWindows(range, now);
+  const filters = { range, surface, provider, model, apiKeyId };
+  const owner = captureUsageOwner();
+  const readDeps = owner.connection.kind === "disconnected" ? { ...deps, baseUrl: await runtimeBaseUrl(deps) } : deps;
+  const currentReport = await readUsage(query({ ...filters, since: windows.current.since, until: windows.current.until }), windows.current, apiKeyId, readDeps, owner);
+  const previousReport = await readUsage(query({ ...filters, since: windows.previous.since, until: windows.previous.until }), windows.previous, apiKeyId, readDeps, owner);
+  const current = totalsOf(currentReport);
+  const previous = totalsOf(previousReport);
+  const deltaTotals: Totals = {};
+  const change: Partial<Record<Metric, number | null>> = {};
+  for (const key of METRICS) {
+    const d = delta(current[key], previous[key]);
+    if (d !== undefined) deltaTotals[key] = d;
+    const pctValue = changePct(current[key], previous[key]);
+    if (pctValue !== undefined) change[key] = pctValue;
+  }
+  const incomplete = currentReport.usageIncomplete === true || previousReport.usageIncomplete === true;
+  const result = {
+    schemaVersion: 1,
+    range,
+    surface,
+    days: windows.days,
+    filter: { provider: provider ?? null, model: model ?? null, apiKeyId: apiKeyId ?? null },
+    current: { since: windows.current.since, until: windows.current.until, summary: current, usageIncomplete: currentReport.usageIncomplete === true },
+    previous: { since: windows.previous.since, until: windows.previous.until, summary: previous, usageIncomplete: previousReport.usageIncomplete === true },
+    delta: deltaTotals,
+    change,
+    incomplete,
+  };
+  printData(result, wantsJson, wantsJson ? undefined : formatCompare({
+    range, days: windows.days, currentWindow: windows.current, previousWindow: windows.previous,
+    current, previous, incomplete,
+  }));
+}