@bitkyc08/opencodex 2.90.0 → 2.92.0

package/src/cli/registry.ts

@@ -150,7 +150,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "link",
-    usage: "ocx link <port|issue|status|revoke|reconnect>",
+    usage: "ocx link <port|issue|status|revoke|reconnect|cleanup>",
     summary: "Allocate and manage a loopback remote home link.",
     details: [
       "Port: ocx link port [--json]",
@@ -158,6 +158,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Status: ocx link status [--json]",
       "Revoke: ocx link revoke --link-id <id> [--force --yes] [--json]",
       "Reconnect: ocx link reconnect --link-id <id> [--json]",
+      "Cleanup: ocx link cleanup [--link-id <id>] [--json]",
       "Issue, status, revoke, and reconnect use the running proxy's loopback management API and admin token.",
     ],
   },
@@ -434,6 +435,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Works both online (via live proxy API) and offline (modifies persisted config safely with atomic writes).",
     ],
   },
+  {
+    name: "fallback",
+    usage: "ocx fallback <status|off|on|clear|local> [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Turn model and provider fallback off or on per scope, and record per-device local fallback.",
+    details: [
+      "A refused fallback answers fallback_refused with the status of the failure that triggered it, and names the command that allows it.",
+      "Precedence: a device set to off always refuses; otherwise route, then provider, then global; unset allows.",
+      "Rotation among the accounts or keys of one provider pool is not a fallback and is not governed here.",
+      "Live proxy only. On a Remote Link Child, status reads the Home; writes are refused. Run write commands on the Home.",
+    ],
+  },
   {
     name: "agent",
     usage: "ocx agent <status|injection|effort|subagents|fallback|sidecar> ...",

package/src/cli/restart-failure.ts

@@ -16,6 +16,10 @@ export function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: f
       console.error("The proxy home or lifecycle ownership could not be verified. Run `ocx status`; if a service owns the proxy, use its installation's `ocx service restart`, otherwise use the owning app or supervisor. No changes were made.");
     } else if (code === "restart_package_tree_unsettled") {
       console.error(`The proxy's package files are unsettled. Wait for the install to finish, then run \`ocx restart\`. ${INCOMPLETE_INSTALL_RECOVERY}`);
+    } else if (code === "restart_supervised_service") {
+      console.error("Restart not performed; the running client runtime was kept. Its background service owns it: run `ocx service restart`.");
+    } else if (code === "restart_supervised_desktop") {
+      console.error("Restart not performed; the running client runtime was kept. The OpenCodex desktop app owns it: restart it from the app.");
     } else {
       console.error("Proxy restart request could not be confirmed; no fallback stop/start was attempted. Run `ocx status` to inspect ownership and runtime state.");
     }

package/src/cli/runtime-api.ts

@@ -202,7 +202,7 @@ export async function runtimeRequest<T = unknown>(
     if (!linkChildReadable(method, path)) {
       throw new RuntimeApiError(linkChildRefusal(link, `${method} ${pathname}`), 503, null, "link_child_management_unavailable");
     }
-    const { status, body } = await readLinkHomeJson(link, path, deps.linkHome);
+    const { status, body } = await readLinkHomeJson(link, path, deps.linkHome, init.signal ? { signal: init.signal } : {});
     if (status < 200 || status >= 300) throw new RuntimeApiError(responseMessage(body, status), status, body);
     return body as T;
   }

package/src/cli/status-codex-settings.ts

@@ -0,0 +1,56 @@
+/**
+ * The OCX-6 fields of `ocx status --json`: which Codex settings this machine applied, when, and
+ * when its client runtime started.
+ *
+ * - `appliedCodexSettingsDigest` (any device): the digest of the values this machine applies. On a
+ *   Remote Link Child that is its apply record (the Home's values its last sync wrote); on a Home or
+ *   standalone install, its own projection, which is also exactly what it serves its Children. Null
+ *   on a hub client and on a Child that has no apply record yet.
+ * - `lastApplyAt` (Child): epoch ms of the last successful apply of a different Home settings
+ *   document; null elsewhere.
+ * - `runtimeStartedAt` (Child): epoch ms the live client runtime reports as its start; null when no
+ *   client runtime answers.
+ */
+import type { LiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig } from "../types";
+
+export interface CliAppliedCodexSettingsStatus {
+  appliedCodexSettingsDigest: string | null;
+  lastApplyAt: number | null;
+  runtimeStartedAt: number | null;
+}
+
+export interface AppliedCodexSettingsStatusDeps {
+  readStartedAt?: (live: LiveProxy) => Promise<number | null>;
+}
+
+export async function collectAppliedCodexSettingsStatus(
+  config: OcxConfig,
+  live: LiveProxy | null,
+  deps: AppliedCodexSettingsStatusDeps = {},
+): Promise<CliAppliedCodexSettingsStatus> {
+  const { codexSettingsDigest, projectHomeCodexSettings } = await import("../link/codex-settings");
+  if (config.runtimeRole !== "client") {
+    return {
+      appliedCodexSettingsDigest: codexSettingsDigest(projectHomeCodexSettings(config, "0.0.0").settings),
+      lastApplyAt: null,
+      runtimeStartedAt: null,
+    };
+  }
+  const linkId = config.client?.transport === "link" ? config.client.link?.linkId : undefined;
+  if (!linkId) return { appliedCodexSettingsDigest: null, lastApplyAt: null, runtimeStartedAt: null };
+  const { readHomeCodexSettingsRecord } = await import("../client/link-home");
+  const record = readHomeCodexSettingsRecord(linkId);
+  const appliedAt = record ? Date.parse(record.appliedAt) : Number.NaN;
+  let runtimeStartedAt: number | null = null;
+  if (live?.role === "client") {
+    const read = deps.readStartedAt ?? (async (target: LiveProxy) =>
+      (await import("./link-apply-restart")).readClientRuntimeStartedAt(target));
+    runtimeStartedAt = await read(live);
+  }
+  return {
+    appliedCodexSettingsDigest: record ? codexSettingsDigest(record.document.settings) : null,
+    lastApplyAt: Number.isFinite(appliedAt) ? appliedAt : null,
+    runtimeStartedAt,
+  };
+}

package/src/cli/status-fallback.ts

@@ -0,0 +1,29 @@
+/**
+ * `ocx status --json` `fallback` (OCX-11). The live proxy's `GET /api/fallback` when it answers
+ * (on a Remote Link Child that read is the Home's, over the link); otherwise the policy from this
+ * machine's config with no events, marked `source: "local"`. Never fails the status report.
+ */
+import type { OcxConfig } from "../types";
+import { buildFallbackState, type FallbackStateView } from "../routing/fallback-state";
+import { runtimeRequest, type RuntimeApiDeps } from "./runtime-api";
+
+export type StatusFallback = (FallbackStateView | ReturnType<typeof buildFallbackState>) & { source: "live" | "home" | "local" };
+
+const STATUS_FALLBACK_TIMEOUT_MS = 2_000;
+
+export async function collectStatusFallback(
+  config: Pick<OcxConfig, "fallback">,
+  options: { live: boolean; linkChild: boolean; deps?: RuntimeApiDeps },
+): Promise<StatusFallback> {
+  if (options.live) {
+    try {
+      const state = await runtimeRequest<FallbackStateView>("/api/fallback", {
+        signal: AbortSignal.timeout(STATUS_FALLBACK_TIMEOUT_MS),
+      }, options.deps ?? {});
+      if (state && typeof state === "object" && state.schema === "ocx.fallback/1") {
+        return { ...state, source: options.linkChild ? "home" : "live" };
+      }
+    } catch { /* an older or unreachable proxy: report the local policy instead */ }
+  }
+  return { ...buildFallbackState(options.linkChild ? {} : config), source: "local" };
+}

package/src/cli/status-install.ts

@@ -0,0 +1,52 @@
+import { detectInstallOwnership, type InstallOwnership } from "../update";
+
+/** How this ocx is installed, from the updater's own ownership detector. */
+export type InstallMethod = "bun" | "npm" | "pnpm" | "mise" | "source" | "standalone" | "unknown";
+
+/**
+ * `ocx status --json` `install`. Additive within `schemaVersion: 1`.
+ *
+ * The verdict is the one `ocx update` acts on (`src/update/install-detection.mjs`), read
+ * from the running package's own location — PATH is never consulted, because a machine can
+ * carry several package managers at once. `evidence` names what decided it without adding
+ * a path: the package layout, mise's backend record (tool alias and backend only), the
+ * compiled standalone binary, or nothing when detection itself failed.
+ */
+export type InstallDetectionStatus = {
+  method: InstallMethod;
+  evidence: {
+    basis: "package-layout" | "mise-backend-record" | "standalone-binary" | "unavailable";
+    mise?: { tool: string; backend: string };
+    error?: "metadata_unreadable" | "metadata_inconsistent" | "detection_failed";
+  };
+};
+
+export function installDetectionStatus(
+  detect: () => InstallOwnership = detectInstallOwnership,
+): InstallDetectionStatus {
+  let ownership: InstallOwnership;
+  try {
+    ownership = detect();
+  } catch {
+    return { method: "unknown", evidence: { basis: "unavailable", error: "detection_failed" } };
+  }
+  switch (ownership.installer) {
+    case "standalone":
+      return { method: "standalone", evidence: { basis: "standalone-binary" } };
+    case "mise":
+      if (ownership.owner) {
+        return {
+          method: "mise",
+          evidence: { basis: "mise-backend-record", mise: { tool: ownership.owner.tool, backend: ownership.owner.backend } },
+        };
+      }
+      return { method: "mise", evidence: { basis: "mise-backend-record", error: ownership.error ?? "metadata_unreadable" } };
+    case "bun":
+    case "npm":
+    case "pnpm":
+    case "source":
+      return { method: ownership.installer, evidence: { basis: "package-layout" } };
+    default:
+      return { method: "unknown", evidence: { basis: "unavailable", error: "detection_failed" } };
+  }
+}

package/src/cli/status.ts

@@ -36,6 +36,8 @@ export type { ListenTarget } from "./status-probes";
 import { checkProxyHealth, probeUncleanExitState, type ListenTarget } from "./status-probes";
 import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
 import { fetchBoundLocalManagementRead } from "../server/local-management-read-client";
+import { collectAppliedCodexSettingsStatus, type CliAppliedCodexSettingsStatus } from "./status-codex-settings";
+import { installDetectionStatus, type InstallDetectionStatus } from "./status-install";
 
 /**
  * The state of the data-plane admission secret the SERVICE will use. State only -- never the value.
@@ -118,6 +120,8 @@ export type CliRemoteHubStatus = {
 
 export type CliStatusJson = {
   mainAccountHardLock?: CodexMainAccountPolicyHealth;
+  /** OCX-11 fallback state; see src/cli/status-fallback.ts. */
+  fallback?: import("./status-fallback").StatusFallback;
   schemaVersion: 1;
   /**
    * This machine's topology role, named rather than inferred (#4236).
@@ -229,8 +233,10 @@ export type CliStatusJson = {
    */
   versionSkew: VersionSkew;
   cliCommand: CliPathDiagnostics;
+  /** Installer ownership from the updater's detector (OCX-10); additive, `schemaVersion` stays 1. */
+  install: InstallDetectionStatus;
   startupSource: "live" | "local" | "local-supervision-override";
-};
+} & CliAppliedCodexSettingsStatus;
 
 export type CliStatusView = {
   json: CliStatusJson;
@@ -853,12 +859,22 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
   const mainAccountHardLock = options.mainAccountPolicy && live
     ? (await (await import("../oauth/health")).fetchCodexHealthFromLiveProxy(undefined, async () => live)).mainAccountHardLock
     : undefined;
+  // Same `--json`-only gate as the hard-lock read above: the human report stays one probe.
+  const fallback = options.mainAccountPolicy
+    ? await (await import("./status-fallback")).collectStatusFallback(config, {
+      live: Boolean(live), linkChild: config.client?.transport === "link",
+      deps: { findLiveProxy: async () => live },
+    })
+    : undefined;
   const pidFile = readPid();
   // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile.
   const pid = resolveStatusPid(live, pidFile);
   // No extra request: findLiveProxy's identity probe already parsed and validated the
   // healthz body, so the version came back with the liveness result.
   const versionSkew = computeVersionSkew(packageVersion(), live?.version);
+  // OCX-6: what this machine applied and, on a Child, when its runtime started. Additive and
+  // always present (null when unknown), so `schemaVersion` stays 1.
+  const appliedCodexSettings = await collectAppliedCodexSettingsStatus(config, live);
   const listen = live
     ? {
       port: live.port,
@@ -1005,6 +1021,7 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
     healthLabel: formatCliStatusHealthLabel(health.label, cliCommand, remoteHub.connected),
     json: {
       ...(mainAccountHardLock ? { mainAccountHardLock } : {}),
+      ...(fallback ? { fallback } : {}),
       schemaVersion: 1,
       runtimeRole: config.runtimeRole ?? "standalone",
       proxy: {
@@ -1067,7 +1084,9 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
       // print it under the wrong heading (#2701).
       versionSkew,
       cliCommand,
+      install: installDetectionStatus(),
       startupSource,
+      ...appliedCodexSettings,
     },
   };
 }

package/src/cli/system-restart-client.ts

@@ -1,4 +1,5 @@
 import { readRuntimePort } from "../config/process-state";
+import { readBoundedResponseBytes } from "../lib/bounded-body";
 import {
   LOCAL_ATTESTATION_CHALLENGE_HEADER,
   LOCAL_ATTESTATION_PROOF_HEADER,
@@ -6,6 +7,8 @@ import {
   verifyLocalAttestationProof,
 } from "../lib/local-management-attestation";
 import {
+  CLIENT_RESTART_REQUEST_MIN_REMAINING_MS,
+  RESTART_SUPERVISED_ERROR,
   SYSTEM_RESTART_CAPABILITY_HEADER,
   SYSTEM_RESTART_CAPABILITY_VERSION,
   SYSTEM_RESTART_EXPECTED_PID_HEADER,
@@ -182,6 +185,13 @@ export async function requestBoundSystemRestart(
   );
   if (!capability) return rejected("restart_capability_unavailable");
 
+  // A connected client runtime keeps serving when its replacement fails, but its rollback takes
+  // up to CLIENT_RESTART_BUDGET_MS. Ask only while that still ends before this CLI stops observing,
+  // or the recovery start below could race the rollback for the port (OCX-6).
+  if (body.role === "client" && deadlineAt - now() < CLIENT_RESTART_REQUEST_MIN_REMAINING_MS) {
+    return rejected("restart_deadline_expired");
+  }
+
   const requestBudget = remaining(deadlineAt, now, SYSTEM_RESTART_REQUEST_TIMEOUT_MS);
   if (requestBudget <= 0) return rejected("restart_deadline_expired");
   try {
@@ -194,10 +204,31 @@ export async function requestBoundSystemRestart(
       },
       signal: AbortSignal.timeout(requestBudget),
     });
-    return response.ok ? { accepted: true } : rejected(`restart_request_http_${response.status}`);
+    if (response.ok) return { accepted: true };
+    if (response.status === 409) {
+      const supervisor = await supervisedRefusal(response);
+      if (supervisor) return rejected(`${RESTART_SUPERVISED_ERROR}_${supervisor}`);
+    }
+    return rejected(`restart_request_http_${response.status}`);
   } catch {
     // The server may have accepted the restart before the response connection failed.
     // The coordinator observes the original PID for replacement instead of replaying.
     return uncertain("restart_request_outcome_unknown");
   }
 }
+
+/**
+ * A client runtime under the desktop app or a service answers 409 `restart_supervised` and keeps
+ * serving (OCX-6). Read that small body and return the validated supervisor, or null.
+ */
+async function supervisedRefusal(response: Response): Promise<"service" | "desktop" | null> {
+  try {
+    const read = await readBoundedResponseBytes(response, { maxBytes: 1024, signal: AbortSignal.timeout(SYSTEM_RESTART_REQUEST_TIMEOUT_MS) });
+    if (read.oversized) return null;
+    const body = JSON.parse(new TextDecoder().decode(read.bytes)) as { error?: { code?: unknown; supervisor?: unknown } } | null;
+    if (body?.error?.code !== RESTART_SUPERVISED_ERROR) return null;
+    return body.error.supervisor === "service" || body.error.supervisor === "desktop" ? body.error.supervisor : null;
+  } catch {
+    return null;
+  }
+}

package/src/cli/update-restart-child.ts

@@ -20,10 +20,11 @@ function parseMarker(raw: string): UpdateRestartChildMarker {
     || typeof value.home.serviceRecord.digest !== "string" || !/^[a-f0-9]{64}$/.test(value.home.serviceRecord.digest)) throw new Error("update_restart_child_marker_invalid");
   for (const directory of [value.home.config, value.home.codex]) {
     // Windows reports 64-bit NTFS file ids (MFT sequence in the high 16 bits) as doubles above
-    // 2^53. Parent and child read them through the same stat API, so any finite integer is a
-    // faithful identity token; assertUpdateRestartHome still compares path, dev and ino exactly.
+    // 2^53, where neighbouring ids collapse. dev and ino may be large finite integers; fileId
+    // carries the exact "dev:ino" that assertUpdateRestartHome actually relies on.
     if (!directory || typeof directory.path !== "string" || !directory.path
-      || !Number.isInteger(directory.dev) || !Number.isInteger(directory.ino)) {
+      || !Number.isInteger(directory.dev) || !Number.isInteger(directory.ino)
+      || typeof directory.fileId !== "string" || !/^\d{1,20}:\d{1,20}$/.test(directory.fileId)) {
       throw new Error("update_restart_child_marker_invalid");
     }
   }

package/src/cli/update-restart-home.ts

@@ -1,4 +1,4 @@
-import { realpathSync, statSync } from "node:fs";
+import { realpathSync, statSync, type BigIntStats } from "node:fs";
 import { readClientConnectionState } from "../client/state";
 import { readConfigDiagnostics } from "../config/diagnostics";
 import { getConfigDir } from "../config/paths";
@@ -6,23 +6,34 @@ import { currentCodexHome } from "../service/state";
 import { captureUpdateRestartServiceRecord, type UpdateRestartServiceRecord, type UpdateRestartServiceRecordDeps } from "./update-restart-service-record";
 import { probeUpdateRestartSupervision, type UpdateRestartSupervisionDeps } from "./update-restart-supervision";
 
+/**
+ * `fileId` is the exact identity ("dev:ino" from a bigint stat). `dev` and `ino` are doubles and
+ * cannot be: an NTFS file id carries the MFT sequence in its high bits, so above 2^53 a replacement
+ * directory with a nearby MFT index can round to the same `ino` as the one it replaced.
+ */
+export interface UpdateRestartDirectory { path: string; dev: number; ino: number; fileId: string }
+
 export interface UpdateRestartHome {
-  config: { path: string; dev: number; ino: number };
-  codex: { path: string; dev: number; ino: number };
+  config: UpdateRestartDirectory;
+  codex: UpdateRestartDirectory;
   revision: number;
   serviceRecord: UpdateRestartServiceRecord;
 }
 
-function physicalDirectory(path: string): UpdateRestartHome["config"] {
+export type UpdateRestartDirectoryStat = Pick<BigIntStats, "dev" | "ino" | "isDirectory">;
+
+function physicalDirectory(path: string, stat: (path: string) => UpdateRestartDirectoryStat): UpdateRestartDirectory {
   const canonical = realpathSync.native(path);
-  const stat = statSync(canonical);
-  if (!stat.isDirectory()) throw new Error("update_restart_home_unverified");
-  return { path: canonical, dev: stat.dev, ino: stat.ino };
+  const observed = stat(canonical);
+  if (!observed.isDirectory()) throw new Error("update_restart_home_unverified");
+  return { path: canonical, dev: Number(observed.dev), ino: Number(observed.ino), fileId: `${observed.dev}:${observed.ino}` };
 }
 
 export interface UpdateRestartHomeDeps {
   record?: UpdateRestartServiceRecordDeps;
   supervision?: UpdateRestartSupervisionDeps;
+  /** Test seam for the directory identity source; production reads a bigint stat. */
+  statDirectory?: (path: string) => UpdateRestartDirectoryStat;
 }
 
 /** Capture eligibility from the same bytes that supply the frozen fingerprint. */
@@ -32,7 +43,8 @@ export function readUpdateRestartHome(deps: UpdateRestartHomeDeps = {}): UpdateR
   if (owner.kind !== "none" || (state.kind === "state" && platform !== "darwin" && platform !== "linux")) {
     throw new Error("update_restart_owner_unverified");
   }
-  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision, serviceRecord };
+  const stat = deps.statDirectory ?? (path => statSync(path, { bigint: true }));
+  return { config: physicalDirectory(getConfigDir(), stat), codex: physicalDirectory(currentCodexHome(), stat), revision: owner.revision, serviceRecord };
 }
 
 export function assertUpdateRestartHome(expected: UpdateRestartHome, deadlineAt = Date.now() + 2000, deps: UpdateRestartHomeDeps = {}): void {

package/src/cli/usage-compare.ts

@@ -8,7 +8,11 @@ import { readClientConnectionState, sameClientConnectionOwner } from "../client/
 import { fetchHubUsage } from "../client/hub-client";
 import { readServiceApiTokenState, serviceApiTokenFingerprint } from "../lib/service-secrets";
 import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+import { readRuntimePort, type RuntimePortState } from "../config/process-state";
+import { isLocalAttestationSecret } from "../lib/local-management-attestation";
 import { redactSecretString } from "../lib/redact";
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { fetchBoundLocalManagementRead, type LocalManagementReadDeps } from "../server/local-management-read-client";
 import { rangeWindow, USAGE_SURFACES } from "../usage/summary";
 import type { UsageTimeWindow } from "../usage/time-range";
 import {
@@ -16,8 +20,7 @@ import {
   printData,
   rejectArgs,
   RuntimeApiError,
-  runtimeRequest,
-  runtimeBaseUrl,
+  PROXY_NOT_RUNNING_MESSAGE,
   takeFlag,
   takeOption,
   takeOptionWithSyntax,
@@ -29,7 +32,10 @@ export const USAGE_COMPARE_USAGE = `Usage:
       [--provider <name>] [--model <id>] [--api-key-id <id>] [--json]`;
 
 export type CompareRange = "today" | "7d" | "30d";
-export type UsageCompareDeps = RuntimeApiDeps & { now?: () => number };
+export type UsageCompareDeps = RuntimeApiDeps & Pick<LocalManagementReadDeps, "directFetch"> & {
+  now?: () => number;
+  readRuntime?: typeof readRuntimePort;
+};
 
 const METRICS = ["requests", "totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "estimatedCostUsd"] as const;
 type Metric = typeof METRICS[number];
@@ -189,10 +195,60 @@ function captureUsageOwner() {
   const headers = runningProxyUpdateHeaders();
   const fingerprint = connection.kind === "connected" ? connection.value.tokenFingerprint
     : serviceApiTokenFingerprint(headers.get("X-OpenCodex-API-Key") ?? "");
-  return { connection, token, headers, fingerprint };
+  return { connection, token, fingerprint };
 }
 type UsageOwner = ReturnType<typeof captureUsageOwner>;
 
+function pinUsageRuntime(deps: UsageCompareDeps, owner: UsageOwner): (suffix: string) => Promise<ScopedUsage> {
+  const readRuntime = deps.readRuntime ?? readRuntimePort;
+  const initial = readRuntimePortForComparison();
+  const pinned = { ...initial };
+  let liveIdentity: string | undefined;
+  function readRuntimePortForComparison(): RuntimePortState {
+    const runtime = readRuntime();
+    if (!runtime || !isLocalAttestationSecret(runtime.attestationSecret)) {
+      throw new Error("Usage runtime unavailable: restart the proxy with an attested runtime record.");
+    }
+    return runtime;
+  }
+  function assertRuntime(): RuntimePortState {
+    const current = readRuntimePortForComparison();
+    if (current.pid !== pinned.pid || current.port !== pinned.port || current.hostname !== pinned.hostname
+      || current.attestationSecret !== pinned.attestationSecret) {
+      throw new Error("Usage runtime changed during comparison; no comparison was produced. Retry for the current runtime.");
+    }
+    return current;
+  }
+  return async suffix => {
+    assertRuntime();
+    const live = await (deps.findLiveProxy ?? findLiveProxy)();
+    assertRuntime();
+    assertUsageOwner(owner);
+    if (!live) throw new RuntimeApiError(PROXY_NOT_RUNNING_MESSAGE, 503, null, "proxy_not_running");
+    const identity = JSON.stringify([live.pid, live.port, live.hostname, live.source, live.role]);
+    if (live.source !== "runtime" || live.pid !== pinned.pid || live.port !== pinned.port
+      || probeHostname(live.hostname) !== probeHostname(pinned.hostname) || live.role === "client"
+      || (liveIdentity !== undefined && liveIdentity !== identity)) {
+      throw new Error("Usage runtime changed during comparison; no comparison was produced. Retry for the current runtime.");
+    }
+    liveIdentity = identity;
+    const read = await fetchBoundLocalManagementRead(live, `/api/usage?${suffix.replace(/^\?/, "")}`, {
+      fetchImpl: deps.fetchImpl, directFetch: deps.directFetch, readRuntime: assertRuntime,
+      timeoutMs: 60_000, requireResponseProof: true,
+    });
+    assertRuntime();
+    if (read.kind === "unavailable") {
+      throw new RuntimeApiError(`Local usage read unavailable (${read.reason}). No comparison was produced.`, 503, null);
+    }
+    if (!read.response.ok) {
+      throw new RuntimeApiError(`Usage request failed (HTTP ${read.response.status}). No comparison was produced.`, read.response.status, null);
+    }
+    const result = await read.response.json() as ScopedUsage;
+    assertRuntime();
+    return result;
+  };
+}
+
 function assertUsageOwner(owner: UsageOwner): void {
   const current = readClientConnectionState();
   const expected = owner.connection;
@@ -216,6 +272,7 @@ async function readUsage(
   apiKeyId: string | undefined,
   deps: RuntimeApiDeps,
   owner: UsageOwner,
+  localRead?: (suffix: string) => Promise<ScopedUsage>,
 ): Promise<ScopedUsage> {
   assertUsageOwner(owner);
   const { connection, token } = owner;
@@ -233,16 +290,15 @@ async function readUsage(
     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);
+      result = await localRead!(suffix);
     } catch (error) {
-      if (error instanceof RuntimeApiError && error.code === "proxy_not_running") throw error;
+      if (apiKeyId === undefined) throw error;
+      if (error instanceof RuntimeApiError) throw error;
       throw new Error("Key-scoped usage could not be read. Check runtime access and retry.");
     }
-    if (result.filter?.apiKeyId !== apiKeyId) {
+    if (apiKeyId !== undefined && result.filter?.apiKeyId !== apiKeyId) {
       throw new Error("The server did not confirm the requested API key scope. Upgrade and restart the proxy, then retry.");
     }
   }
@@ -276,9 +332,9 @@ export async function handleUsageCompareCommand(argv: string[], deps: UsageCompa
   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 localRead = owner.connection.kind === "disconnected" ? pinUsageRuntime(deps, owner) : undefined;
+  const currentReport = await readUsage(query({ ...filters, since: windows.current.since, until: windows.current.until }), windows.current, apiKeyId, deps, owner, localRead);
+  const previousReport = await readUsage(query({ ...filters, since: windows.previous.since, until: windows.previous.until }), windows.previous, apiKeyId, deps, owner, localRead);
   const current = totalsOf(currentReport);
   const previous = totalsOf(previousReport);
   const deltaTotals: Totals = {};