@bitkyc08/opencodex 2.84.0 → 2.87.0

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,
+  }));
+}

package/src/cli/usage-model-search.ts

@@ -5,7 +5,7 @@ export interface UsageModelView {
   query: string;
   matchedModelCount: number;
   returnedModelCount: number;
-  limit: 100;
+  limit: number;
   truncated: boolean;
 }
 
@@ -36,7 +36,7 @@ export function takeUsageSearchOption(args: string[]): string | undefined {
   return value;
 }
 
-export function selectUsageModelView<T extends { models?: unknown }>(report: T, rawQuery: string): Omit<T, "models"> & { models: SearchableModel[]; modelView: UsageModelView } {
+export function selectUsageModelView<T extends { models?: unknown }>(report: T, rawQuery: string, limit = 100): Omit<T, "models"> & { models: SearchableModel[]; modelView: UsageModelView } {
   if (!report || !Array.isArray(report.models)) throw new Error("Invalid usage model rows; retry after checking the runtime.");
   const models = report.models.map((raw: unknown): SearchableModel => {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Invalid usage model row.");
@@ -53,6 +53,6 @@ export function selectUsageModelView<T extends { models?: unknown }>(report: T,
   const matching = models.toSorted((a, b) => b.totalTokens - a.totalTokens).filter(row => !query
     || row.model.toLowerCase().includes(query) || row.provider.toLowerCase().includes(query)
     || (row.resolvedModel ?? "").toLowerCase().includes(query));
-  const selected = matching.slice(0, 100);
-  return { ...report, models: selected, modelView: { query, matchedModelCount: matching.length, returnedModelCount: selected.length, limit: 100, truncated: matching.length > selected.length } };
+  const selected = matching.slice(0, limit);
+  return { ...report, models: selected, modelView: { query, matchedModelCount: matching.length, returnedModelCount: selected.length, limit, truncated: matching.length > selected.length } };
 }

package/src/cli/usage-report.ts

@@ -113,7 +113,7 @@ function describeScope(data: UsageReportInput): string {
   return terminalText(parts.join(", "));
 }
 
-export function formatUsageReport(data: UsageReportInput, options?: { modelView?: UsageModelView }): string[] {
+export function formatUsageReport(data: UsageReportInput, options?: { modelView?: UsageModelView; modelRowLimit?: number }): string[] {
   const summary = data.summary ?? {};
   const lines: string[] = [describeScope(data), ""];
   if (data.source === "hub" && data.scope === "client") {
@@ -192,7 +192,7 @@ export function formatUsageReport(data: UsageReportInput, options?: { modelView?
   const models = view ? (data.models ?? []) : (data.models ?? []).filter(row => row.requests > 0);
   if (models.length > 0) {
     lines.push("");
-    const shown = models.slice(0, view?.limit ?? MAX_MODEL_ROWS);
+    const shown = models.slice(0, view?.limit ?? options?.modelRowLimit ?? MAX_MODEL_ROWS);
     lines.push(...table(
       ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
       shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),

package/src/cli/v2.ts

@@ -148,7 +148,7 @@ function printLocalStatus(deps: V2CliDeps): number {
     const modeHint = getMultiAgentModeHintText();
     log.log(`multi_agent_mode_hint_text: ${modeHint === null ? "(unset — effort-derived policy: ultra=proactive, else explicit)" : JSON.stringify(modeHint)}`);
     if (isEnabled() && hasMaxThreads()) {
-      log.log("WARNING: [agents] max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove it from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
+      log.log("WARNING: [agents] max_concurrent_threads_per_session / max_threads is set — codex refuses to start while multi_agent_v2 is enabled. Remove the agents limit from config.toml (concurrency lives in features.multi_agent_v2.max_concurrent_threads_per_session).");
     }
     return 0;
 }

package/src/client/machine-listener.ts

@@ -107,9 +107,7 @@ export function startMachineListener(
   const machineApiDeps: MachineApiDeps = {
     sync: deps.machineApi?.sync ?? syncConnectedClient,
     disconnect: deps.machineApi?.disconnect ?? disconnectClient,
-    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (tokenFingerprint => {
-      void import("./runtime").then(module => module.scheduleStandaloneRecycle(tokenFingerprint));
-    }),
+    scheduleStandaloneRecycle: deps.machineApi?.scheduleStandaloneRecycle ?? (() => {}),
     hubReachability: deps.machineApi?.hubReachability ?? (() => hubReachability),
     setHubReachability: deps.machineApi?.setHubReachability ?? (value => { hubReachability = value; }),
     ...(linkMode ? { linkHomeName: () => linkHomeName(connection, sidecarOrNull) } : {}),

package/src/client/runtime.ts

@@ -250,6 +250,7 @@ export async function bindClientListener(
     try {
       const server = startListener(port, {
         state: request.state,
+        machineApi: { scheduleStandaloneRecycle },
         ...(request.linkStatus ? { linkStatus: request.linkStatus } : {}),
         ...(request.linkKeySource ? { linkKeySource: request.linkKeySource } : {}),
         ...(request.linkTunnel ? { linkTunnel: request.linkTunnel } : {}),

package/src/clients/client-path.ts

@@ -0,0 +1,51 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import type { OpencodeLaunchEnv } from "./config-export/contracts";
+
+// Leaf owner of client path validation, shared by config-export and gentle-shell-path
+// without an import cycle between them.
+
+/**
+ * Expand `~` against the effective home; REFUSE anything still relative.
+ *
+ * A first attempt at this called `resolve()` and claimed the path would "mean
+ * the same thing next time". It does not: `resolve()` only anchors the current
+ * invocation, so applying from one directory and disabling from another still
+ * resolved two different files — the second reported "not applied" and left
+ * the managed block behind with nothing claiming it.
+ *
+ * There is no honest way to recover the other process's cwd, so a relative
+ * selector is refused at the boundary instead of being silently anchored to
+ * whichever directory we happened to start in. A `~` path IS stable, because
+ * it anchors to the effective home rather than the cwd.
+ */
+export class ClientPathError extends Error {}
+
+export function absoluteClientPath(raw: string, home: string, variable: string): string {
+  const trimmed = raw.trim();
+  if (trimmed === "~") return home;
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return join(home, trimmed.slice(2));
+  if (!isAbsolute(trimmed)) {
+    throw new ClientPathError(
+      `${variable} must be an absolute path or start with ~; "${trimmed}" depends on the working directory, `
+      + "so opencodex and the client would disagree about which file it names.",
+    );
+  }
+  return trimmed;
+}
+
+/**
+ * Pi resolves its agent directory from `PI_CODING_AGENT_DIR`, falling back to
+ * `~/.pi/agent`. `ompAgentDir` below already reads that variable — OMP is a Pi
+ * derivative — so Pi's own resolver honoring it is what makes the two agree
+ * rather than a new claim about Pi's contract.
+ *
+ * A relative override is refused for the same reason MCode's and ZCode's are: a
+ * background proxy and a foreground client can have different working
+ * directories, and would otherwise disagree about which file is named.
+ */
+export function piAgentDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.PI_CODING_AGENT_DIR?.trim();
+  if (override) return absoluteClientPath(override, home, "PI_CODING_AGENT_DIR");
+  return join(home, ".pi", "agent");
+}

package/src/clients/config-export/contracts.ts

@@ -202,6 +202,7 @@ export interface ExportContext {
 export type DroidReasoningDefaults = Record<string, string>;
 
 export type ExportClientId =
+  | "qoder"
   | "opencode"
   | "pi"
   | "omp"
@@ -219,7 +220,8 @@ export type ExportClientId =
   | "cline"
   | "commandcode"
   | "kilo"
-  | "droid";
+  | "droid"
+  | "gentle-shell";
 
 export interface ExportClientSpec {
   id: ExportClientId;

package/src/clients/config-export/model-metadata.ts

@@ -9,8 +9,9 @@ import { shouldInjectApiAuthHeader } from "../../codex/inject";
 
 
 /**
- * Authoritative context window, or undefined. Never guesses: a missing, non-finite, or
- * non-positive value means the serializer omits every context-derived field.
+ * Validate the supplied catalog window (which may be a labelled vendor estimate).
+ * A missing, non-finite, or non-positive value omits every context-derived field;
+ * this serializer does not independently infer a window.
  */
 export function authoritativeContextWindow(contextWindow: number | undefined): number | undefined {
   if (typeof contextWindow === "number" && Number.isFinite(contextWindow) && contextWindow > 0) {