@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/cli/registry.ts

@@ -29,18 +29,32 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "--socks5-off          Clear a saved SOCKS5 outbound proxy from config.proxy.",
     ],
   },
-  { name: "stop", usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
+  {
+    name: "stop",
+    usage: "ocx stop [--json]",
+    summary: "Stop the proxy and restore native Codex config.",
+    details: [
+      "--json keeps the stop path unchanged and prints one structured summary document on stdout; human output moves to stderr.",
+      "Exit codes are identical with and without --json: 0, 1, 79 (history cleanup incomplete), 80 (teardown deferred).",
+    ],
+  },
   {
     name: "restore",
     aliases: ["eject"],
     usage: "ocx restore [back]",
     summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
+    details: [
+      "--remove-codex-provider-table  Also remove [model_providers.opencodex] when a paginated home made restore keep it. Conversations tagged opencodex stop opening.",
+    ],
   },
   {
     name: "eject",
     aliases: [],
     usage: "ocx eject [back]",
     summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
+    details: [
+      "--remove-codex-provider-table  Also remove [model_providers.opencodex] when a paginated home made restore keep it. Conversations tagged opencodex stop opening.",
+    ],
   },
   {
     name: "recover-history",
@@ -94,9 +108,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   {
     name: "tray",
     usage: "ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]",
-    summary: "Install and control the Windows status tray icon.",
+    summary: "Install and control the Windows status tray icon (deprecated in favor of the desktop app).",
     details: [
       "The tray starts at Windows login and provides one-click proxy controls.",
+      "Deprecated: the OpenCodex desktop app provides the tray on Windows, macOS, and Linux; `ocx tray` remains for installs without the desktop app.",
       "Tray start/stop controls the icon only; use its menu to start or stop the proxy.",
       "--no-start (install only) installs the tray without launching it immediately.",
     ],
@@ -298,6 +313,16 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx model <subcommand>",
     summary: "Alias of ocx models.",
   },
+  {
+    name: "companion",
+    usage: "ocx companion <show|set|reset> ...",
+    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    details: [
+      "ocx companion and ocx companion show read settings; use --json for machine-readable output.",
+      "ocx companion set accepts one or more key=value assignments; values are parsed as JSON when possible.",
+      "ocx companion reset restores the default settings.",
+    ],
+  },
   {
     name: "combo",
     usage: "ocx combo <list|show|set|remove> ...",
@@ -480,6 +505,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     details: [
       "Alias of ocx integration client <sub> --client zcode.",
       "enable writes the managed provider.opencodex block into ~/.zcode/v2/config.json; disable removes only that block.",
+      "ZCode 3.14 moved its providers to ~/.zcode/v2/provider_config.json; where that file exists, enable is refused because the write cannot reach the client.",
       "ZCode reads its config at startup — restart ZCode after enable/disable.",
       "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
     ],
@@ -531,6 +557,19 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
     ],
   },
+  {
+    name: "resolve",
+    usage: "ocx resolve [--json]",
+    summary: "Emit the resolved config home, effective port, and identity-checked proxy liveness as one JSON document.",
+    details: [
+      "Machine surface for embedding shells: it replaces a second home/port/liveness implementation beside the CLI.",
+      "The port is the live listener's port when an opencodex proxy answers, otherwise the configured port (default 10100).",
+      "Liveness is three-valued: live, absent-proven (every recorded and configured endpoint definitively dead), or unknown — unknown exits 1 and never reads as absent.",
+      "--json emits one versioned document (schema ocx-resolve/1); the default prints two human lines.",
+      "Exit 0 carries a trustworthy verdict; exit 1 means the CLI could not resolve (invalid config or undecidable liveness) and callers must refuse to guess.",
+      "Any unknown argument exits 64 before preflight side effects.",
+    ],
+  },
   {
     name: "lab",
     usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",

package/src/cli/resolve.ts

@@ -0,0 +1,230 @@
+/**
+ * `ocx resolve` — the machine-readable runtime resolution surface for an embedding shell.
+ *
+ * D5 of devlog/_plan/260921_app_runtime_ownership/: the desktop shell must stop resolving
+ * the config home, the port and liveness itself. The tuned probe budgets in
+ * src/server/proxy-liveness.ts exist because a shell-side reimplementation answered
+ * "nobody listening" twice and started duplicate proxies; this verb exposes that module's
+ * verdict instead of copying it, alongside src/config/paths.ts (the home) and the CLI's
+ * own preferred-port selection (`config.port ?? 10100` — resolve takes no --port).
+ *
+ * Contract:
+ *  - `--json` puts exactly ONE JSON document on stdout, versioned by `schema`; the
+ *    default prints two human lines, the same opt-in split as `ocx ready --json`.
+ *  - liveness has three answers, not two: "live", "absent-proven" (every recorded and
+ *    configured endpoint definitively refused or answered non-opencodex), and unknown.
+ *    Unknown NEVER reaches the wire as absent — a probe that timed out, a listener that
+ *    withheld /healthz, or an identity mismatch exits 1 instead. Only "absent-proven"
+ *    may authorise starting a new runtime.
+ *  - exit 0 whenever a trustworthy verdict exists — live, or proven absent. A MISSING
+ *    config.json is defaults, not an error.
+ *  - exit 1 when the CLI cannot resolve: an invalid config.json must NOT be answered
+ *    with `loadConfig`'s repair-to-defaults behaviour, because that hands the caller
+ *    a guessed port; and unknown liveness must not be answered as absence.
+ *  - exit 64 for any argument, pre-parsed in src/cli/root.ts before preflight side
+ *    effects, mirroring `ocx ready`. The verb is read-only and listed in
+ *    skipsCodexShimAutoRestore, so a lookup made to populate a consent surface never
+ *    triggers a shim repair side effect.
+ *
+ * Discovery uses the START_OWNERSHIP_LIVENESS budget, not the 750ms single-shot default:
+ * the shell's launch decision keys on this verdict, and answering "nobody" for a slow
+ * live proxy is the duplicate-proxy decision the start path tunes against (#5004).
+ *
+ * Lives outside cli/index.ts (which dispatches argv at module top level) so tests can
+ * import it, the same split as ready.ts.
+ */
+import { readConfigDiagnostics, type ConfigDiagnostics } from "../config";
+import { getConfigDir } from "../config/paths";
+import { readRuntimePort } from "../config/process-state";
+import { packageVersion } from "../lib/package-version";
+import {
+  findLiveProxy,
+  probeEndpointLiveness,
+  START_OWNERSHIP_LIVENESS,
+  type EndpointLiveness,
+  type LiveProxy,
+} from "../server/proxy-liveness";
+import { endpointsToProve, everyEndpointProvenDownAsync, type ProbeEndpoint } from "./uninstall-plan";
+
+/** Wire version of the resolve document. Bump only on an incompatible shape change. */
+export const RESOLVE_SCHEMA = "ocx-resolve/1";
+
+/** The port every preferred-port selection in the CLI falls back to. */
+export const RESOLVE_DEFAULT_PORT = 10100;
+
+export interface ResolveLivenessJson {
+  /**
+   * "live" when the identity-checked probe found our proxy; "absent-proven" when every
+   * recorded and configured endpoint is definitively dead. The third state — unknown —
+   * exits 1 before this document is printed, so it never appears on the wire as absence.
+   */
+  status: "live" | "absent-proven";
+  pid: number | null;
+  port: number | null;
+  /** Raw bind hostname that answered; compose probe URLs via probeHostname semantics. */
+  hostname?: string;
+  /** Where the verdict came from: the runtime record, or the configured listen port. */
+  source: LiveProxy["source"] | null;
+  /** Version the live proxy reported on /healthz, when it reported one. */
+  version?: string;
+  /** Listener role the live proxy reported, when it reported one ("client" = connected client). */
+  role?: string;
+}
+
+export interface ResolveJson {
+  schema: typeof RESOLVE_SCHEMA;
+  /** Version of this CLI binary, so a shell can compare its engine against the live proxy. */
+  cliVersion: string;
+  /** Resolved opencodex home (OPENCODEX_HOME or ~/.opencodex), from src/config/paths.ts. */
+  configHome: string;
+  port: {
+    /** The port a client should use: the live listener's port when one answers, else the configured one. */
+    effective: number;
+    /** The configured listen port (config.port ?? 10100); what a start would prefer. */
+    configured: number;
+    /** Whether `effective` came from a live proxy or from configuration. */
+    source: LiveProxy["source"];
+  };
+  liveness: ResolveLivenessJson;
+}
+
+export interface ResolveArgs {
+  json: boolean;
+}
+
+export type ResolveParseResult = { ok: true; args: ResolveArgs } | { ok: false; code: 64 };
+
+/** Pure argument parser: the only flag is `--json`. */
+export function parseResolveArgs(argv: string[]): ResolveParseResult {
+  for (const flag of argv) {
+    if (flag !== "--json") return { ok: false, code: 64 };
+  }
+  return { ok: true, args: { json: argv.includes("--json") } };
+}
+
+export interface ResolveIo {
+  configDir?: () => string;
+  readDiagnostics?: () => ConfigDiagnostics;
+  findLive?: () => Promise<LiveProxy | null>;
+  /** Runtime-port record reader; production default is readRuntimePort. */
+  readRuntime?: () => { port?: number; hostname?: string } | null;
+  /** Tri-state endpoint probe; production default runs in-process for compiled standalone binaries. */
+  probeEndpoint?: (endpoint: ProbeEndpoint) => EndpointLiveness | Promise<EndpointLiveness>;
+  cliVersion?: () => string;
+  stdout?: { log: (s: string) => void };
+  stderr?: { error: (s: string) => void };
+}
+
+function livenessJson(live: LiveProxy | null): ResolveLivenessJson {
+  // Reaching here with null means absence was PROVEN by the caller (unknown exits 1
+  // before this document is built).
+  if (!live) return { status: "absent-proven", pid: null, port: null, source: null };
+  return {
+    status: "live",
+    pid: live.pid,
+    port: live.port,
+    source: live.source,
+    ...(live.hostname === undefined ? {} : { hostname: live.hostname }),
+    ...(live.version === undefined ? {} : { version: live.version }),
+    ...(live.role === undefined ? {} : { role: live.role }),
+  };
+}
+
+/** Pure shaper: one live verdict plus configuration becomes the wire document. */
+export function buildResolveJson(
+  config: { port?: number },
+  live: LiveProxy | null,
+  configHome: string,
+  cliVersion: string,
+): ResolveJson {
+  const configured = config.port ?? RESOLVE_DEFAULT_PORT;
+  return {
+    schema: RESOLVE_SCHEMA,
+    cliVersion,
+    configHome,
+    port: {
+      effective: live ? live.port : configured,
+      configured,
+      source: live ? live.source : "config",
+    },
+    liveness: livenessJson(live),
+  };
+}
+
+/**
+ * Human form: two lines, no prose flourish — an operator skims it, a shell uses --json.
+ */
+function reportHuman(json: ResolveJson, stdout: { log: (s: string) => void }): void {
+  stdout.log(`Config home: ${json.configHome}`);
+  const live = json.liveness;
+  if (live.status === "live") {
+    const pidText = live.pid === null ? "unknown" : String(live.pid);
+    const versionText = live.version ?? "unknown version";
+    stdout.log(`Proxy live on port ${json.port.effective} (PID ${pidText}, ${versionText}); effective port ${json.port.effective}.`);
+  } else {
+    stdout.log(`No live proxy (absence proven); effective port ${json.port.effective} (configured).`);
+  }
+}
+
+/**
+ * Run `ocx resolve` over injected I/O. Returns the exit code. The production defaults
+ * read config through the diagnostics surface (which distinguishes missing, valid and
+ * invalid instead of repairing to defaults) and perform one identity-checked discovery
+ * at the ownership-safe budget — resolve adds no probing policy of its own.
+ */
+export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise<number> {
+  const stdout = io.stdout ?? console;
+  const stderr = io.stderr ?? console;
+  const configDir = io.configDir ?? getConfigDir;
+  const readDiagnostics = io.readDiagnostics ?? readConfigDiagnostics;
+  const findLive = io.findLive ?? (() => findLiveProxy(START_OWNERSHIP_LIVENESS));
+  const readRuntime = io.readRuntime ?? readRuntimePort;
+  const probeEndpoint = io.probeEndpoint ?? probeEndpointLiveness;
+  const cliVersion = io.cliVersion ?? packageVersion;
+  const configHome = configDir();
+  let diagnostics: ConfigDiagnostics;
+  try {
+    diagnostics = readDiagnostics();
+  } catch (error) {
+    // A resolution that could not run must not read as "no proxy": the caller has to
+    // refuse to guess (D5) rather than treat this as a proven-absent verdict.
+    stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (diagnostics.source === "fallback") {
+    // An invalid config must not resolve to defaults: the effective port would be a
+    // guess at 10100 while the operator's config.port is unread. The repair-to-defaults
+    // policy in loadConfig is for interactive recovery, not for a shell contract.
+    stderr.error(`resolve failed: the config in ${configHome} is invalid (${diagnostics.error ?? "unknown error"}); refusing to guess.`);
+    return 1;
+  }
+  let live: LiveProxy | null;
+  try {
+    live = await findLive();
+  } catch (error) {
+    stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+  if (!live) {
+    // findLiveProxy collapses "definitely nothing" and "could not tell" into the same
+    // null. The launch decision keys on this verdict, so resolve owes the caller the
+    // tri-state answer the updater already enforces: only EVERY candidate definitively
+    // dead is absence. Anything else is unknown, and unknown exits 1 — it must never
+    // authorise starting a second runtime.
+    let provenDown = false;
+    try {
+      provenDown = await everyEndpointProvenDownAsync(endpointsToProve(readRuntime(), diagnostics.config), probeEndpoint);
+    } catch {
+      // A probe that cannot run is not evidence of absence.
+      provenDown = false;
+    }
+    if (!provenDown) {
+      stderr.error("resolve: liveness is unknown (a probe timed out or a listener withheld /healthz); refusing to treat unknown as absent.");
+      return 1;
+    }
+  }
+  const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion());
+  if (args.json) stdout.log(JSON.stringify(json));
+  else reportHuman(json, stdout);
+  return 0;
+}

package/src/cli/root.ts

@@ -10,16 +10,19 @@
  */
 import { hasHelpFlag, printSubcommandUsage, printUsage, printVersion } from "./help";
 import { parseReadyArgs, type ReadyArgs } from "./ready";
+import { parseResolveArgs, type ResolveArgs } from "./resolve";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 
 export interface CliHead {
-  kind: "version" | "help" | "ready" | "command";
+  kind: "version" | "help" | "ready" | "resolve" | "command";
   command: string | undefined;
   args: string[];
   /** For kind "help": the subcommand whose usage should print, if any. */
   helpTarget?: string;
   /** Present only for `ready`; undefined when the ready args failed to parse. */
   readyArgs?: ReadyArgs;
+  /** Present only for `resolve`; undefined when the resolve args failed to parse. */
+  resolveArgs?: ResolveArgs;
 }
 
 export function parseCliHead(argv: string[]): CliHead {
@@ -51,6 +54,13 @@ export function parseCliHead(argv: string[]): CliHead {
     if (!parsed.ok) return { kind: "ready", command, args, readyArgs: undefined };
     return { kind: "ready", command, args, readyArgs: parsed.args };
   }
+  // Same ordering contract as `ready`: `ocx resolve` rejects any argument with exit
+  // 64 BEFORE maybeAutoRestoreCodexShim (or any other preflight with side effects) runs.
+  if (command === "resolve") {
+    const parsed = parseResolveArgs(args.slice(1));
+    if (!parsed.ok) return { kind: "resolve", command, args, resolveArgs: undefined };
+    return { kind: "resolve", command, args, resolveArgs: parsed.args };
+  }
   return { kind: "command", command, args };
 }
 
@@ -79,6 +89,19 @@ export async function runCli(argv: string[]): Promise<CliHead> {
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;
     }
+    case "resolve": {
+      // Fail-closed impossible-state guard, mirroring ready: the pre-parse above already
+      // rejected invalid arguments before any preflight, so a missing resolveArgs means
+      // dispatch diverged. Refuse with code 64 and perform NO I/O.
+      if (!head.resolveArgs) {
+        console.error("Usage: ocx resolve [--json]");
+        console.error("  --json prints one JSON document: the config home, the effective port,");
+        console.error("  and the identity-checked liveness verdict.");
+        process.exit(64);
+      }
+      maybeAutoRestoreCodexShim(head.command, head.args);
+      return head;
+    }
     case "command":
       maybeAutoRestoreCodexShim(head.command, head.args);
       return head;

package/src/cli/start-ownership-publication.ts

@@ -0,0 +1,56 @@
+export interface StartOwnershipLease {
+  release(): void;
+}
+
+export class StartOwnershipRollbackUncertainError extends AggregateError {
+  constructor(errors: Iterable<unknown>) {
+    super(errors, "start listener rollback could not be proven complete");
+    this.name = "StartOwnershipRollbackUncertainError";
+  }
+}
+
+export interface StartOwnershipPublicationDeps<TBound> {
+  acquireLease(): StartOwnershipLease;
+  bind(): Promise<TBound>;
+  writePid(bound: TBound): void;
+  writeRuntime(bound: TBound): void;
+  stopBound(bound: TBound): void | Promise<void>;
+  removeRuntime(): void;
+  removePid(): void;
+}
+
+/** Bind and publish PID/runtime ownership as one lease-protected transaction. */
+export async function bindAndPublishStartOwnership<TBound>(
+  deps: StartOwnershipPublicationDeps<TBound>,
+): Promise<TBound> {
+  const lease = deps.acquireLease();
+  let bound: TBound;
+  let releaseLease = true;
+  try {
+    try { bound = await deps.bind(); }
+    catch (error) {
+      if (error instanceof StartOwnershipRollbackUncertainError) releaseLease = false;
+      throw error;
+    }
+    try {
+      deps.writePid(bound);
+      deps.writeRuntime(bound);
+    } catch (error) {
+      const failures: unknown[] = [error];
+      let stopFailed = false;
+      try { await deps.stopBound(bound); }
+      catch (failure) { stopFailed = true; failures.push(failure); }
+      try { deps.removeRuntime(); } catch (failure) { failures.push(failure); }
+      try { deps.removePid(); } catch (failure) { failures.push(failure); }
+      if (stopFailed) {
+        releaseLease = false;
+        throw new StartOwnershipRollbackUncertainError(failures);
+      }
+      if (failures.length > 1) throw new AggregateError(failures, "start ownership publication rollback failed");
+      throw error;
+    }
+    return bound;
+  } finally {
+    if (releaseLease) lease.release();
+  }
+}

package/src/cli/status-probes.ts

@@ -1,5 +1,5 @@
 import { readPidFileValue, readRuntimePort } from "../config/process-state";
-import { isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
+import { isConnectionRefused, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import { isProcessAlive } from "../lib/process-control";
 
@@ -26,23 +26,7 @@ export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "
     : "unreachable";
 }
 
-/**
- * "Nothing is listening" is narrower than "the probe failed". `unreachable` covers every
- * non-abort failure, including a socket that was ACCEPTED and then reset — which is what
- * an in-flight start looks like mid-bind. Only a connect-phase refusal proves the port is
- * free, so this reads the underlying errno instead of the display string.
- */
-export function isConnectionRefused(error: unknown): boolean {
-  for (let current: unknown = error, depth = 0; current instanceof Error && depth < 4; depth++) {
-    const code = (current as { code?: unknown }).code;
-    if (code === "ECONNREFUSED" || code === "ConnectionRefused") return true;
-    // Bun surfaces the refusal as a plain message on some platforms; the errno name is
-    // still the discriminator, not a substring of arbitrary prose.
-    if (typeof code === "string" && code.endsWith("ECONNREFUSED")) return true;
-    current = (current as { cause?: unknown }).cause;
-  }
-  return false;
-}
+export { isConnectionRefused } from "../server/proxy-liveness";
 
 /**
  * A proxy killed by a native trap or SIGKILL never runs the exit cleanup that removes

package/src/cli/status.ts

@@ -1,4 +1,5 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
+import { existsSync, readFileSync } from "node:fs";
 import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
 import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
@@ -7,6 +8,8 @@ import type { OcxConfig } from "../types";
 import { diagnoseService, serviceLogPath } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
+import { missingOwnedCatalogPath } from "../codex/inject/config-toml";
+import { CODEX_CONFIG_PATH } from "../codex/paths";
 import { diagnoseCodexShim } from "../codex/shim";
 import { displayCodexRuntimePath, effortClampAppliesToRuntime, liveRemovedEfforts, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
 import { packageVersion } from "./help";
@@ -502,6 +505,65 @@ export function unusedProxyWarningLines(input: {
   ];
 }
 
+/**
+ * The mirror case: routing is ours and nothing is answering it.
+ *
+ * #5261: this state does not merely fail model calls. The root `openai_base_url` we inject
+ * is the base URL of Codex's own built-in openai provider, so with the proxy down a user can
+ * be stopped at Codex sign-in with no mention of opencodex anywhere on the screen. The
+ * injection is on disk and survives reboot, so it does not clear itself.
+ *
+ * The rest of the not-running report offers only ways to bring the proxy BACK, which is the
+ * wrong half of the choice for someone who wants their editor working again now. `ocx restore`
+ * needs no proxy, no management API and no network, so name it here — this report is the
+ * surface such a user is most likely to reach before the config file itself.
+ *
+ * Restricted to routing opencodex owns. `custom-local` is somebody else's gateway, and
+ * `ocx restore` would not remove it.
+ */
+export function deadProxyRoutingAdviceLines(input: {
+  proxyUp: boolean;
+  routingKind: StartupHealth["routingKind"];
+}): string[] {
+  if (input.proxyUp || input.routingKind !== "opencodex-local") return [];
+  return [
+    "Codex is still pointed at this proxy, so sign-in and model requests both fail while it is down.",
+    "To hand Codex back to its own account and endpoints without starting anything: ocx restore",
+  ];
+}
+
+/**
+ * Read the live Codex config and report an opencodex catalog pointer whose file is gone.
+ *
+ * Unreadable or absent config is reported as no finding rather than as a problem: this is a
+ * diagnostic line, and inventing one from missing evidence is worse than staying quiet.
+ */
+export function detectMissingCodexCatalogPath(): string | null {
+  try {
+    if (!existsSync(CODEX_CONFIG_PATH)) return null;
+    return missingOwnedCatalogPath(readFileSync(CODEX_CONFIG_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The one state in this report where Codex is broken independently of the proxy (#5261).
+ *
+ * A `model_catalog_json` naming a file that is gone stops Codex loading its configuration at
+ * all, so it presents as the same blank wall as dead routing while having a different cause and
+ * a different fix. Both are named, because restarting the proxy rewrites the catalog and
+ * restoring removes the pointer, and which one the user wants is their choice, not ours.
+ */
+export function missingCodexCatalogLines(missingCatalogPath: string | null): string[] {
+  if (!missingCatalogPath) return [];
+  return [
+    "⚠️  Codex is pointed at a model catalog that is no longer on disk, so Codex cannot load its config:",
+    `   ${missingCatalogPath}`,
+    "   Regenerate it with 'ocx start', or remove opencodex from Codex with 'ocx restore'.",
+  ];
+}
+
 export async function collectStatus(): Promise<CliStatusView> {
   const configDiagnostics = readConfigDiagnostics();
   const config = configDiagnostics.config;