@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/companion-usage.ts

@@ -0,0 +1,146 @@
+/** Saved companion display filters applied to two bounded management reads. */
+import { ObservationError, withObserveStream, type ObserveStreamDeps } from "./observe-stream";
+import { printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
+
+const USAGE = "Usage: ocx companion usage [--json]";
+const TOTAL_FIELDS = ["requests", "totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "cacheReadInputTokens", "estimatedCostUsd", "measuredRequests", "pricedRequests", "coverageRatio"] as const;
+type Totals = Partial<Record<typeof TOTAL_FIELDS[number], number>>;
+type Model = Totals & { model: string; provider: string };
+interface Usage {
+  summary: Totals;
+  models: Model[];
+  customWindow?: boolean;
+  since?: number | null;
+  until?: number;
+  usageIncomplete?: boolean;
+  historyTruncated?: boolean;
+  entriesTruncated?: boolean;
+}
+interface Filters { models: string[] | null; hiddenProviders: string[] }
+interface Settings { filters: Filters; updatedAt: number | null; corrupt: boolean }
+type RangeResult = { status: "available"; data: Usage } | { status: "unavailable" };
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ObservationError("Invalid companion response. Check the runtime and retry the command.");
+  return value as Record<string, unknown>;
+}
+
+function stringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length <= 100 && value.every(item => typeof item === "string" && item.length > 0 && !/[\x00-\x1f\x7f-\x9f]/.test(item));
+}
+
+function parseSettings(value: unknown): Settings {
+  const body = object(value), settings = object(body.settings);
+  if ((settings.models !== null && !stringList(settings.models)) || !stringList(settings.hiddenProviders)
+    || (body.updatedAt !== null && (typeof body.updatedAt !== "number" || !Number.isFinite(body.updatedAt)))
+    || (body.corrupt !== undefined && typeof body.corrupt !== "boolean")) {
+    throw new ObservationError("Invalid companion settings. Check the runtime and retry the command.");
+  }
+  return { filters: { models: settings.models, hiddenProviders: settings.hiddenProviders }, updatedAt: body.updatedAt, corrupt: body.corrupt === true };
+}
+
+function parseTotals(value: unknown): Totals {
+  const row = object(value), totals: Totals = {};
+  for (const key of TOTAL_FIELDS) {
+    const metric = row[key];
+    if (metric === undefined) continue;
+    if (typeof metric !== "number" || !Number.isFinite(metric) || metric < 0) throw new ObservationError("Invalid companion usage metrics. Check the runtime and retry the command.");
+    totals[key] = metric;
+  }
+  return totals;
+}
+
+function parseUsage(value: unknown): Usage {
+  const body = object(value);
+  if (body.error || !Array.isArray(body.models)) throw new ObservationError("Invalid companion usage report. Check the runtime and retry the command.");
+  const usage: Usage = {
+    summary: parseTotals(body.summary),
+    models: body.models.map(raw => {
+      const row = object(raw);
+      if (typeof row.model !== "string" || typeof row.provider !== "string") throw new ObservationError("Invalid companion model row. Check the runtime and retry the command.");
+      return { ...parseTotals(row), model: row.model, provider: row.provider };
+    }),
+  };
+  for (const key of ["customWindow", "usageIncomplete", "historyTruncated", "entriesTruncated"] as const) {
+    if (body[key] === undefined) continue;
+    if (typeof body[key] !== "boolean") throw new ObservationError("Invalid companion usage metadata. Check the runtime and retry the command.");
+    usage[key] = body[key];
+  }
+  for (const key of ["since", "until"] as const) {
+    const timestamp = body[key];
+    if (timestamp === undefined) continue;
+    if (key === "since" && timestamp === null) { usage.since = null; continue; }
+    if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) throw new ObservationError("Invalid companion usage window. Check the runtime and retry the command.");
+    usage[key] = timestamp;
+  }
+  return usage;
+}
+
+/** Keep in conformance with tray-data's display rules without a GUI runtime import. */
+function filterUsage(usage: Usage, filters: Filters): Usage {
+  const hidden = new Set(filters.hiddenProviders), selected = filters.models === null ? null : new Set(filters.models);
+  const models = usage.models.filter(row => !hidden.has(row.provider)
+    && (selected === null || selected.has(`${row.provider}/${row.model}`) || selected.has(row.model)));
+  if (filters.models === null && filters.hiddenProviders.length === 0) return { ...usage, models };
+  if (filters.models?.length !== 0 && usage.models.some(row => !row.provider || !row.model || (row.provider === "other" && row.model === "other"))) {
+    return { ...usage, models: models.filter(row => row.provider !== "other" || row.model !== "other"), summary: {}, usageIncomplete: true };
+  }
+  const summary: Totals = {};
+  for (const key of TOTAL_FIELDS) {
+    if (key === "coverageRatio") continue;
+    if (models.length && models.every(row => row[key] !== undefined)) summary[key] = models.reduce((sum, row) => sum + row[key]!, 0);
+  }
+  return { ...usage, models, summary };
+}
+
+function measuredTotals<T extends Totals>(data: T): T {
+  const next = { ...data };
+  if ((data.requests ?? 0) > 0 && (data.measuredRequests === 0 || data.coverageRatio === 0)) {
+    for (const key of ["totalTokens", "inputTokens", "outputTokens", "cachedInputTokens", "cacheReadInputTokens"] as const) delete next[key];
+  }
+  if ((data.requests ?? 0) > 0 && data.pricedRequests === 0) delete next.estimatedCostUsd;
+  return next;
+}
+
+function formatRange(label: string, result: RangeResult): string[] {
+  if (result.status === "unavailable") return [`${label}: unavailable`];
+  const count = (value: number | undefined) => value === undefined ? "unknown" : value.toLocaleString("en-US");
+  const cost = (value: number | undefined) => value === undefined ? "unknown" : `~$${value.toFixed(4)}`;
+  const data = result.data;
+  return [`${label}: ${count(data.summary.requests)} requests; ${count(data.summary.totalTokens)} tokens; cost ${cost(data.summary.estimatedCostUsd)}`,
+    ...(data.usageIncomplete || data.historyTruncated || data.entriesTruncated ? ["  Incomplete observation; totals include only attributable measured data."] : []),
+    ...data.models.map(row => `  ${row.provider}/${row.model}: ${count(row.requests)} requests; ${count(row.totalTokens)} tokens; cost ${cost(row.estimatedCostUsd)}`)];
+}
+
+export async function handleCompanionUsageCommand(argv: string[], deps: ObserveStreamDeps = {}): Promise<number> {
+  let outcome = 0;
+  const parseExit = await runCliAction(async () => {
+    const args = [...argv], wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, USAGE, { redactValues: true });
+    outcome = await withObserveStream(deps, async stream => {
+      const settings = parseSettings(await stream.get("/api/companion/settings", new URLSearchParams()));
+      const ranges: Record<"today" | "30d", RangeResult> = { today: { status: "unavailable" }, "30d": { status: "unavailable" } };
+      for (const range of ["today", "30d"] as const) {
+        try {
+          const data = filterUsage(parseUsage(await stream.get("/api/usage", new URLSearchParams({ range }))), settings.filters);
+          ranges[range] = { status: "available", data: { ...data, summary: measuredTotals(data.summary), models: data.models.map(measuredTotals) } };
+        } catch {
+          stream.signal.throwIfAborted();
+        }
+      }
+      stream.signal.throwIfAborted();
+      const partial = ranges.today.status === "unavailable" || ranges["30d"].status === "unavailable";
+      const result = { schemaVersion: 1, filters: settings.filters, settingsUpdatedAt: settings.updatedAt, settingsCorrupt: settings.corrupt,
+        settingsFallback: settings.corrupt || settings.updatedAt === null, ranges, partial };
+      const lines = ["Companion usage — saved display filters (sequential observations)",
+        `Models: ${settings.filters.models === null ? "all" : settings.filters.models.length === 0 ? "none" : settings.filters.models.join(", ")}`,
+        `Hidden providers: ${settings.filters.hiddenProviders.join(", ") || "none"}`,
+        ...(settings.corrupt ? ["WARNING: Saved settings are corrupt; the runtime supplied fallback settings."] : []),
+        ...formatRange("Today", ranges.today), ...formatRange("30 days", ranges["30d"])];
+      printData(result, wantsJson, wantsJson ? undefined : lines);
+      if (partial) console.error("Error: Some companion usage ranges are unavailable. Check the runtime and retry the command.");
+      return partial ? 1 : 0;
+    }, { kind: "snapshot" });
+  });
+  return parseExit || outcome;
+}

package/src/cli/companion.ts

@@ -1,9 +1,16 @@
+import { handleCompanionTimelineCommand } from "./companion-timeline";
+import { handleCompanionUsageCommand } from "./companion-usage";
+import type { ObserveStreamDeps } from "./observe-stream";
 import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
 
 const USAGE = `Usage:
   ocx companion [show] [--json]
   ocx companion set <key>=<value> [...] [--json]
-  ocx companion reset [--json]`;
+  ocx companion reset [--json]
+  ocx companion usage [--json]
+  ocx companion timeline [--hours <6|24|72|168>] [--bucket-minutes <1..1440>]
+      [--metric <total|input|output|cached>] [--aggregation <sum|average|max>]
+      [--grouping <model|modelAccount>] [--model <provider/model>]... [--hide-provider <name>]... [--json]`;
 
 function parseValue(raw: string): unknown {
   if (raw === "null") return null;
@@ -43,9 +50,11 @@ async function reset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }, deps), wantsJson, ["Companion settings reset."]);
 }
 
-export async function handleCompanionCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+export async function handleCompanionCommand(argv: string[], deps: ObserveStreamDeps = {}): Promise<number> {
+  const [sub = "show", ...rest] = argv;
+  if (sub === "timeline") return handleCompanionTimelineCommand(rest, deps);
+  if (sub === "usage") return handleCompanionUsageCommand(rest, deps);
   return runCliAction(async () => {
-    const [sub = "show", ...rest] = argv;
     if (sub === "show") await show(rest, deps);
     else if (sub === "set") await set(rest, deps);
     else if (sub === "reset") await reset(rest, deps);

package/src/cli/config-command.ts

@@ -14,7 +14,7 @@ const USAGE = `Usage:
   ocx config set <dot.path> <json-or-string> [--json]
   ocx config unset <dot.path> [--json]
   ocx config validate [path|-] [--json]
-  ocx config export <path|->
+  ocx config export <path|-> [--json]
   ocx config import <path|-> --yes [--json]`;
 
 /**
@@ -205,14 +205,21 @@ function validate(value: unknown): OcxConfig {
 }
 
 export async function handleConfigCommand(argv: string[]): Promise<number> {
-  return runCliAction(async () => {
+  let outcome = 0;
+  const status = await runCliAction(async () => {
     const args = [...argv];
-    const action = (args.shift() ?? "show").toLowerCase();
     const wantsJson = takeFlag(args, "--json");
+    const source = takeFlag(args, "--source");
+    if (args.includes("--json") || args.includes("--source")) throw new CliUsageError("config flags may only be specified once", USAGE);
+    const action = (args.shift() ?? "show").toLowerCase();
+    if (source && action !== "show") throw new CliUsageError("--source is only supported for config show", USAGE);
     if (action === "show") {
-      const source = takeFlag(args, "--source");
       rejectArgs(args, USAGE);
       const diagnostics = readConfigDiagnostics();
+      if (diagnostics.source === "fallback" || diagnostics.error) {
+        console.error(`Warning: Config at ${getConfigPath()} is invalid or unreadable; defaults are being shown for invalid settings. Run: ocx config validate. Inspect: ocx config show --source.`);
+        if (!source) outcome = 1;
+      }
       const redacted = redact(diagnostics.config);
       const note = await readRemoteHubConfigNote(diagnostics.config);
       // First key, not last: it has to be read before the empty `providers` map that misled a
@@ -228,7 +235,12 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       const path = args.shift();
       if (!path) throw new CliUsageError("config path is required", USAGE);
       rejectArgs(args, USAGE);
-      const value = redact(getPath(readConfigDiagnostics().config, path), pathSegments(path).at(-1));
+      const diagnostics = readConfigDiagnostics();
+      if (diagnostics.source === "fallback" || diagnostics.error) {
+        console.error(`Warning: Config at ${getConfigPath()} is invalid or unreadable; defaults are being shown for invalid settings. Run: ocx config validate. Inspect: ocx config show --source.`);
+        outcome = 1;
+      }
+      const value = redact(getPath(diagnostics.config, path), pathSegments(path).at(-1));
       if (wantsJson || typeof value === "object") console.log(JSON.stringify(value, null, 2));
       else console.log(String(value));
       return;
@@ -236,7 +248,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
     if (action === "set" || action === "unset") {
       const path = args.shift();
       const raw = action === "set" ? args.shift() : undefined;
-      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError("config path and value are required", USAGE);
+      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError(action === "unset" ? "config path is required" : "config path and value are required", USAGE);
       rejectArgs(args, USAGE);
       // #1835/#1838: the read used to happen OUTSIDE the mutation lock, so a concurrent
       // edit landing between it and the save was reverted by this whole-snapshot write.
@@ -288,7 +300,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       })();
       printData(result.ok ? { ok: true, source: path ?? getConfigPath() } : result, wantsJson,
         [result.ok ? "Config is valid." : `Config is invalid: ${result.error}`]);
-      if (!result.ok) process.exitCode = 1;
+      if (!result.ok) outcome = 1;
       return;
     }
     if (action === "export") {
@@ -297,7 +309,10 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       rejectArgs(args, USAGE);
       const content = `${JSON.stringify(readConfigDiagnostics().config, null, 2)}\n`;
       if (path === "-") process.stdout.write(content);
-      else { writeFileSync(path, content, { encoding: "utf8", mode: 0o600 }); console.log(`Exported config to ${path}.`); }
+      else {
+        writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
+        printData({ ok: true, path }, wantsJson, [`Exported config to ${path}.`]);
+      }
       return;
     }
     if (action === "import") {
@@ -312,6 +327,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
     }
     throw new CliUsageError(`unknown config command ${action}`, USAGE);
   });
+  return status || outcome;
 }
 
 export const CONFIG_USAGE = USAGE;

package/src/cli/connect.ts

@@ -40,6 +40,10 @@ import {
   terminalSafeText,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import {
+  inspectCodexShimForConnect,
+  type CodexConnectShimReadiness,
+} from "./codex-shim-readiness";
 
 export interface ClientCommandDeps extends RuntimeApiDeps {
   lifecycleLockDeps?: ClientLifecycleLockDeps;
@@ -277,6 +281,19 @@ export type ConnectCompletionReport = {
   readonly failure: string | null;
 };
 
+export function codexShimReadinessLine(
+  selectedClients: readonly OcxConnectedClientId[],
+  inspect: () => CodexConnectShimReadiness = inspectCodexShimForConnect,
+): string | null {
+  if (!selectedClients.includes("codex")) return null;
+  return `Codex autostart shim: ${terminalSafeText(inspect().message)}`;
+}
+
+function printCodexShimReadiness(selectedClients: readonly OcxConnectedClientId[]): void {
+  const line = codexShimReadinessLine(selectedClients);
+  if (line) console.log(line);
+}
+
 /**
  * What `ocx connect` says once the hub and the credential are settled, and whether the command
  * still fails (#4207).
@@ -414,6 +431,7 @@ async function runHubConnect(argv: string[], deps: ClientCommandDeps): Promise<v
   const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {});
   const report = connectCompletionReport(connection, clients, readiness);
   for (const line of report.lines) console.log(line);
+  printCodexShimReadiness(clients);
   if (report.failure) throw new Error(report.failure);
 }
 
@@ -463,6 +481,7 @@ async function runLinkConnect(argv: string[], deps: ClientCommandDeps): Promise<
   const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {});
   const report = connectCompletionReport(connection, clients, readiness);
   for (const line of report.lines) console.log(line);
+  printCodexShimReadiness(clients);
   if (report.failure) throw new Error(report.failure);
 }
 

package/src/cli/dispatch.ts

@@ -10,13 +10,13 @@ import type { ProxyRestartStartOutcome } from "./tray-proxy";
  * never needs to import the entry module back (no cycle).
  */
 import { CLI_COMMANDS } from "./registry";
-import { isValidProviderName } from "../config/provider-name";
-import type { CliHead } from "./root";
+import { uninstallArgsError, type CliHead } from "./root";
 import type { ReadyArgs } from "./ready";
 import type { LivenessIo, LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import type { OwnedIntegrationRefreshOutcome } from "../integrations/owned-refresh";
 import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
+import { printUnknownCommand } from "./help-recovery";
 import {
   HUB_GATED_SKIP_MESSAGE,
   localClientSkipMessage,
@@ -299,6 +299,11 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   uninstall: async deps => {
+    const error = uninstallArgsError("uninstall", deps.args);
+    if (error) {
+      console.error(error);
+      return 2;
+    }
     await deps.handleUninstall();
     return Number(process.exitCode ?? 0);
   },
@@ -375,62 +380,8 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   logout: async deps => {
-    // Argv is parsed BEFORE any store access, which is the whole point of this shape.
-    // Previously `args[1]` was taken as the provider name with no parsing, so
-    // `ocx logout --json` called removeCredential("--json"), printed "Logged out of
-    // --json." and exited 0 -- a silent false success, the worst outcome for a caller
-    // that can only see the exit code.
-    //
-    // That is not merely a wasted call. `normalizeAuthStore` copies every top-level key
-    // it finds, so a hand-edited, legacy, or corrupted auth.json containing a `--json`
-    // key would have its active account deleted -- and the key dropped entirely if that
-    // was its last account. A flag must never reach the store as a provider name.
-    const logoutArgs = deps.args.slice(1);
-    const wantsJson = logoutArgs.includes("--json");
-    // Any leading dash is an option, not a provider. Matching only `--` left the same defect
-    // one dash shorter: `ocx logout -j` treated `-j` as the provider name and, with a `-j` key
-    // present in the store, deleted it and exited 0.
-    const isOption = (arg: string): boolean => arg.startsWith("-");
-    const positionals = logoutArgs.filter(arg => !isOption(arg));
-    const unknownFlags = logoutArgs.filter(arg => isOption(arg) && arg !== "--json");
-    const name = (positionals[0] ?? "").trim().toLowerCase();
-
-    // Usage failures exit 2 and touch nothing. A missing provider is a usage error; a
-    // provider that simply has no credential is a not-found (4) further down, because the
-    // vocabulary distinguishes "you called this wrong" from "the thing is not there".
-    //
-    // The shape check is `isValidProviderName`, not another dash test. Rejecting a leading
-    // ASCII `-` fixed `-j` and still let `logout —json` through with a Unicode dash, which is
-    // the same defect a third time: each patch named one spelling instead of the class. The
-    // canonical validator states the rule positively -- start and end alphanumeric, internal
-    // `._-` allowed -- so `github-copilot` and `google-antigravity` pass while every dash
-    // variant, empty string, and reserved name fails. Anything that is not a possible
-    // provider id cannot reach the store at all.
-    const malformedName = Boolean(name) && !isValidProviderName(name);
-    if (unknownFlags.length > 0 || positionals.length > 1 || !name || malformedName) {
-      const problem = unknownFlags.length > 0
-        ? `unknown option ${unknownFlags[0]}`
-        : positionals.length > 1 ? "too many arguments"
-        : malformedName ? `not a valid provider name: ${name}`
-        : "missing provider";
-      console.error(`Usage: ocx logout <provider> [--json]  (${problem})`);
-      return 2;
-    }
-
-    // The disposition comes from inside the store mutation, not from a read-then-remove
-    // preflight. `mutateStore` serializes writes, so a preflight leaves a window where a
-    // concurrent logout removes the same account and BOTH callers exit 0 claiming a removal --
-    // a false success again, just a narrower one than the flag bug above.
-    const { removeCredential } = await import("../oauth/store");
-    const outcome = await removeCredential(name);
-    if (outcome === "not-found") {
-      if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: false, provider: name, removed: false, reason: "not_found" }, null, 2));
-      else console.error(`No stored credential for '${name}'.`);
-      return 4;
-    }
-    if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: true, provider: name, removed: true }, null, 2));
-    else console.log(`Logged out of ${name}.`);
-    return 0;
+    const { handleLogoutCommand } = await import("./logout-command");
+    return handleLogoutCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   sync: async deps => {
     const syncArgs = deps.args.slice(1);
@@ -514,7 +465,7 @@ const commandRunners: Record<string, CommandRunner> = {
             },
             config,
             port: live.port,
-          }, ["mcode", "pi", "raycast", "omo", "cline", "droid"]));
+          }, ["mcode", "pi", "raycast", "omo", "cline", "droid", "opencode", "kilo"]));
         } catch (error) {
           console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
         }
@@ -537,7 +488,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   v2: async deps => {
     const { cmdV2 } = await import("./v2");
-    return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
+    return await cmdV2(deps.args.slice(1), { runtimeApi: { findLiveProxy: deps.findLiveProxy } }, async () => (await deps.findLiveProxy())?.port);
   },
   connect: async deps => {
     const { handleConnectCommand } = await import("./connect");
@@ -549,7 +500,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   "remote-workspace": async deps => {
     const { runRemoteWorkspaceCommand } = await import("./remote-workspace");
-    return await runRemoteWorkspaceCommand(deps.args.slice(1));
+    return await runRemoteWorkspaceCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   disconnect: async deps => {
     const { handleDisconnectCommand } = await import("./connect");
@@ -569,7 +520,8 @@ const commandRunners: Record<string, CommandRunner> = {
     const cacheGateSnapshot = deps.loadConfig();
     const desiredDisabled = !shouldSyncCodexOnStart(cacheGateSnapshot);
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
-      invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
+      invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, { allowWhenDesiredDisabled: true }),
+    { intent: "cache", writer: "sync-cache" });
     const cacheJson = cacheArgs.includes("--json");
     const jsonSafeLog = cacheJson
       ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
@@ -632,6 +584,10 @@ const commandRunners: Record<string, CommandRunner> = {
       console.log("No Codex catalog to derive a cache from; nothing to sync.");
     } else if (unchanged) {
       console.log("Codex model cache is already current; nothing to sync.");
+    } else if (invalidated.kind === "unavailable"
+      && (invalidated.reason === "foreign-owner" || invalidated.reason === "owner-unknown")) {
+      const { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE } = await import("../codex/catalog/routed-removal");
+      console.error(invalidated.reason === "foreign-owner" ? FOREIGN_CODEX_HOME_OWNER_MESSAGE : UNKNOWN_CODEX_HOME_OWNER_MESSAGE);
     } else if (!ok) {
       console.error(`Cache refresh did not complete (${invalidated.kind}). The Codex model cache was not rewritten.`);
     }
@@ -696,19 +652,33 @@ const commandRunners: Record<string, CommandRunner> = {
     switch (deps.args[1]) {
       case "install": {
         const r = installCodexShim();
-        const { healthy, summary } = diagnoseCodexShim();
+        const { healthy, runnable, active, summary } = diagnoseCodexShim();
+        const success = !r.refused && (runnable ?? healthy);
         const { collectCodexShimReadinessWarnings } = await import("./codex-shim-readiness");
-        const warnings = healthy
+        const warnings = success
           ? collectCodexShimReadinessWarnings()
           : [];
-        console.log(`${r.installed && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
+        console.log(`${success && healthy && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
         for (const warning of warnings) console.warn(`   ${warning}`);
-        if (!healthy) console.error(`Codex shim installation is unhealthy: ${summary}`);
-        return healthy ? 0 : 1;
+        if (success && active !== undefined && active !== true) {
+          const { overlayActivationHint } = await import("../codex/shim-overlay");
+          console.warn(`   ${overlayActivationHint()}`);
+        }
+        if (!success) console.error(`${r.refused ? "Codex shim installation was refused" : "Codex shim installation is unhealthy"}: ${summary}`);
+        return success ? 0 : 1;
       }
-      case "status":
+      case "status": {
+        const extra = deps.args.slice(2);
+        if (extra.length > 0) {
+          console.error(extra.some(isJsonOption)
+            ? "ocx codex-shim status does not support --json; use ocx status --json (codexShim)."
+            : "ocx codex-shim status does not accept arguments or options.");
+          console.error("Usage: ocx codex-shim status");
+          return 2;
+        }
         console.log(codexShimStatus());
         break;
+      }
       case "uninstall":
       case "remove": {
         const r = uninstallCodexShim();
@@ -730,7 +700,7 @@ const commandRunners: Record<string, CommandRunner> = {
     }
     const { runUpdate } = await import("../update");
     await runUpdate();
-    return 0;
+    return Number(process.exitCode ?? 0);
   },
   "__refresh-version": async deps => {
     // Hidden, detached helper spawned by the update prompt to refresh the
@@ -785,6 +755,10 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   health: async deps => {
     const healthArgs = deps.args.slice(1);
+    if (healthArgs.length > 1 || (healthArgs.length === 1 && healthArgs[0] !== "--json")) {
+      console.error("Usage: ocx health [--json]\nSee: ocx help health");
+      return 2;
+    }
     const wantsHealthJson = healthArgs.includes("--json");
     // A proxy that has only just bound can miss a single probe while its event loop
     // is still settling startup work — the same just-started race the stop paths
@@ -843,7 +817,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   companion: async deps => {
     const { handleCompanionCommand } = await import("./companion");
-    return await handleCompanionCommand(deps.args.slice(1));
+    return await handleCompanionCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   route: async deps => {
     if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
@@ -868,7 +842,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   observe: async deps => {
     const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand(deps.args.slice(1));
+    return await handleObserveCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   inspect: async deps => {
     const { handleInspectCommand } = await import("./inspect");
@@ -876,11 +850,11 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   logs: async deps => {
     const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)], { findLiveProxy: deps.findLiveProxy });
   },
   usage: async deps => {
     const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)], { findLiveProxy: deps.findLiveProxy });
   },
   storage: async deps => {
     // `ocx storage` used to be a pure alias of `observe storage`, which reached only the report
@@ -896,11 +870,11 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   access: async deps => {
     const { handleAccessCommand } = await import("./access");
-    return await handleAccessCommand(deps.args.slice(1));
+    return await handleAccessCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   "api-key": async deps => {
     const { handleAccessCommand } = await import("./access");
-    return await handleAccessCommand(["key", ...deps.args.slice(1)]);
+    return await handleAccessCommand(["key", ...deps.args.slice(1)], { findLiveProxy: deps.findLiveProxy });
   },
   api: async deps => {
     const { handleApiCommand } = await import("./api-protocols");
@@ -924,21 +898,21 @@ const commandRunners: Record<string, CommandRunner> = {
       // integrations `client` manages, so they get their own subcommand rather than being
       // folded into one that means something else.
       const { handleIntegrationCommand } = await import("./inspect");
-      return await handleIntegrationCommand(deps.args.slice(1));
+      return await handleIntegrationCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
     } else if (integration === "claude") {
       const { handleClaudeConfigCommand } = await import("./integrations");
       return await handleClaudeConfigCommand(deps.args.slice(2));
     } else if (integration === "client") {
       const { handleClientIntegrationCommand } = await import("./integrations");
-      return await handleClientIntegrationCommand(deps.args.slice(2));
+      return await handleClientIntegrationCommand(deps.args.slice(2), { findLiveProxy: deps.findLiveProxy });
     } else {
-      console.error("Usage: ocx integration <claude|grok|client> <subcommand>");
+      console.error("Usage: ocx integration <claude|grok|client|native> <subcommand>\nSee: ocx help integration");
       return 2;
     }
   },
   system: async deps => {
     const { handleSystemCommand } = await import("./system-command");
-    return await handleSystemCommand(deps.args.slice(1));
+    return await handleSystemCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   config: async deps => {
     const { handleConfigCommand } = await import("./config-command");
@@ -957,7 +931,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // "ocx claude desktop" → write Desktop 3P config
     if (deps.args[1] === "desktop") {
       const { handleClaudeDesktopCommand } = await import("./claude-desktop");
-      const exitCode = await handleClaudeDesktopCommand(deps.args.slice(2));
+      const exitCode = await handleClaudeDesktopCommand(deps.args.slice(2), { findLiveProxyImpl: deps.findLiveProxy });
       if (exitCode !== 0) return exitCode;
       return 0;
     }
@@ -1167,8 +1141,7 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
   }
   const runner = commandRunners[resolveDispatchCommand(command) ?? ""];
   if (!runner) {
-    console.error(`Unknown command: ${command}`);
-    printUsage();
+    printUnknownCommand(command);
     return 1;
   }
   return await runner(deps);