@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/cli/status.ts

@@ -8,21 +8,103 @@ import { diagnoseService, serviceLogPath } from "../service";
 import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health";
 import { getCodexRoutingKind } from "../codex/inject";
 import { diagnoseCodexShim } from "../codex/shim";
-import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
+import { displayCodexRuntimePath, effortClampAppliesToRuntime, liveRemovedEfforts, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
 import { packageVersion } from "./help";
 import { computeVersionSkew, type VersionSkew } from "./version-skew";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home";
 import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status";
+import { effectiveLoopbackListenerPort } from "../codex/loopback-target";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy, type ClaudeDesktopPolicyHealth } from "../claude/desktop-policy";
-import { collectClientConnectionStatus } from "./connect";
+import { collectClientConnectionStatus, type ClientConnectionStatus } from "./connect";
+import type { HubStateOAuthEntry, HubStateProvider } from "../remote/hub-state";
+import type { HubStateSource } from "../client/hub-state";
+import { readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets";
+import { tokenCollidesWithAdmin } from "../lib/admin-secrets";
 export { proxyHealthFailureReason, isConnectionRefused, isUncleanExitEvidence, probeUncleanExitState } from "./status-probes";
 export type { ListenTarget } from "./status-probes";
 import { checkProxyHealth, probeUncleanExitState, type ListenTarget } from "./status-probes";
 
+/**
+ * The state of the data-plane admission secret the SERVICE will use. State only -- never the value.
+ *
+ * Always about the file, because the file is what the service reads: the launchd plist and the
+ * systemd unit `cat` it into `OPENCODEX_API_AUTH_TOKEN` before exec, so a token in the CLI's own
+ * shell says nothing about the running hub. `present (env)` used to be reported here and was
+ * simply wrong about whose environment it meant (see `dataTokenEnvInShell`).
+ *
+ * `admin-collision (file)` is the #4236 incident shape: the file holds the MANAGEMENT token, so
+ * the server fences the whole management plane closed at boot and the hub crash-loops. It used
+ * to report `present (file)`, which is how the cause stayed invisible.
+ */
+export type HubDataTokenState =
+  | "present (file)"
+  | "unsafe (file)"
+  | "admin-collision (file)"
+  | "missing";
+
+export type HubStatus = {
+  /** Advertised data origin: hub.dataPublicOrigin, else derived from the bind address. */
+  dataOrigin: string;
+  /** True when dataOrigin came from config rather than being derived from the bind. */
+  dataOriginConfigured: boolean;
+  /**
+   * The unauthenticated loopback listener, in PR2's two forms: `companion` shares the public
+   * port (the one-port hub), `ported` binds its own. `off` means the hub does not serve its
+   * own local clients at all.
+   */
+  loopbackListener: { state: "off" | "companion" | "ported"; port: number | null };
+  managementIngress: { enabled: boolean; port: number | null };
+  managementPublicOrigin: string | null;
+  dataToken: HubDataTokenState;
+  dataTokenPath: string;
+  /**
+   * `OPENCODEX_API_AUTH_TOKEN` is set in the shell that ran `ocx status` — which is NOT the
+   * environment the installed service runs in. Reported separately, and honestly, because it
+   * does decide what a FOREGROUND `ocx start` in this same shell would admit.
+   */
+  dataTokenEnvInShell: boolean;
+};
+
+/**
+ * What a connected client learned from its hub, and how reliable that answer is (#4236).
+ *
+ * `stateSource` is the load-bearing field. "hub" is a live read; "cache" is the last good read
+ * from THIS connection, still the hub's state rather than this machine's; "unavailable" means
+ * nothing true is known, and the consumer must say so rather than substitute local facts. A
+ * client's own `providers`/`oauth` sections are empty by design, so presenting them as the
+ * answer is not a degraded report — it is a wrong one.
+ */
+export type CliRemoteHubStatus = {
+  connected: boolean;
+  /** The hub's advertised data origin when it publishes one, else the URL this client dials. */
+  origin: string | null;
+  stateSource: HubStateSource;
+  /** Present whenever `stateSource` is not "hub". Operator-facing, never a bare error code. */
+  reason?: string;
+  fetchedAt?: string;
+  ageSeconds?: number;
+  hubVersion: string | null;
+  providers: HubStateProvider[];
+  oauth: HubStateOAuthEntry[];
+  subagentModels: string[];
+  /** The hub hit one of its own caps, so the lists above are a prefix and the report says so. */
+  truncated: boolean;
+  /** The hub's own Claude Code toggle; a client cannot infer it from local config. */
+  claudeCodeEnabled: boolean | null;
+};
+
 export type CliStatusJson = {
   schemaVersion: 1;
+  /**
+   * This machine's topology role, named rather than inferred (#4236).
+   *
+   * Every other field in this report was already ambiguous without it: an agent reading
+   * `providers: {}` on a client could not tell "nothing is configured" from "the provider
+   * configuration lives on the hub". Additive, so `schemaVersion` stays 1.
+   */
+  runtimeRole: "standalone" | "hub" | "client";
   proxy: {
     running: boolean;
     pid: number | null;
@@ -67,6 +149,14 @@ export type CliStatusJson = {
     catalog?: "present" | "missing" | "unsafe";
     catalogAgeSeconds?: number;
     credentialFile: "owned" | "missing" | "changed" | "unsafe";
+    /**
+     * #4207: whether the selected local Codex CLI can consume the catalog this client
+     * installed. Absent unless a client connection exists. `connected` alone proved only the
+     * hub and the credential, and a reader who stopped there saw a healthy connection while
+     * `codex exec` was exiting before its first request.
+     */
+    readiness?: "ready" | "unverified" | "incompatible";
+    readinessReason?: string;
   };
   service: { summary: string };
   codexShim: { summary: string };
@@ -88,6 +178,26 @@ export type CliStatusJson = {
     desiredEnabled: boolean;
     policy: ClaudeDesktopPolicyHealth;
   };
+  /**
+   * The hub-only facts an operator needs in one place, or null on a standalone/client machine.
+   *
+   * Scattered across the report they were unusable: the public data origin came from `listen`,
+   * the management origin was folded into `dashboard.url`, the loopback companion appeared
+   * nowhere, and the data-plane token appeared nowhere at all -- so the one question a hub
+   * operator actually asks ("is this reachable, and can another machine join?") took four other
+   * commands to answer. Additive and nullable, so `schemaVersion` stays 1.
+   *
+   * Never carries a token value; only which source holds one.
+   */
+  hub: HubStatus | null;
+  /**
+   * The hub's answer on a connected client, or a not-connected placeholder (#4236).
+   *
+   * Separate from `connection`, which describes the LINK (is the key owned, is the catalog
+   * present). This describes what is on the other end of it. Additive and always present, so
+   * `schemaVersion` stays 1 and a consumer never has to branch on the key existing.
+   */
+  remoteHub: CliRemoteHubStatus;
   /**
    * This CLI's version against the running proxy's (#2701).
    *
@@ -119,6 +229,199 @@ function statusDashboardUrl(config: StatusListenConfig, hostname: string | undef
   return `http://${dashboardHostname}:${port}/`;
 }
 
+/**
+ * The hub block, or null when this machine is not a hub.
+ *
+ * The token line is about the FILE, not this shell. `ocx status` used to print `present (env)`
+ * whenever the calling shell happened to export `OPENCODEX_API_AUTH_TOKEN`, but the service
+ * wrapper overwrites that variable from the token file before exec — so the label described the
+ * operator's terminal and not the hub. The shell's variable is reported as its own flag instead.
+ *
+ * The token VALUE is never read into the report. `readServiceApiTokenState` returns it; the only
+ * things derived from it are `kind` and the admin-token comparison, neither of which can carry
+ * bytes of the secret.
+ */
+export function collectHubStatus(
+  config: Pick<OcxConfig, "runtimeRole" | "hostname" | "port" | "hub" | "unauthenticatedLoopbackListener">,
+  listen: { port: number; hostname?: string | null },
+  env: NodeJS.ProcessEnv = process.env,
+): HubStatus | null {
+  if (config.runtimeRole !== "hub") return null;
+  const listener = config.unauthenticatedLoopbackListener;
+  const loopbackPort = effectiveLoopbackListenerPort(config, listen.port);
+  const ingress = config.hub?.managementIngress;
+  const configuredDataOrigin = config.hub?.dataPublicOrigin;
+  const host = probeHostname(listen.hostname ?? config.hostname);
+  const tokenState = ((): HubDataTokenState => {
+    const state = readServiceApiTokenState();
+    if (state.kind === "unsafe") return "unsafe (file)";
+    if (state.kind !== "present") return "missing";
+    return tokenCollidesWithAdmin(state.token, env) ? "admin-collision (file)" : "present (file)";
+  })();
+  return {
+    dataOrigin: configuredDataOrigin
+      ?? `http://${host === "127.0.0.1" ? "localhost" : host}:${listen.port}`,
+    dataOriginConfigured: Boolean(configuredDataOrigin),
+    loopbackListener: loopbackPort === null
+      ? { state: "off", port: null }
+      : { state: listener?.enabled && listener.port === undefined ? "companion" : "ported", port: loopbackPort },
+    managementIngress: {
+      enabled: ingress?.enabled === true,
+      port: ingress?.enabled === true ? ingress.port : null,
+    },
+    managementPublicOrigin: config.hub?.managementPublicOrigin ?? null,
+    dataToken: tokenState,
+    dataTokenPath: serviceApiTokenFilePath(),
+    dataTokenEnvInShell: Boolean(env.OPENCODEX_API_AUTH_TOKEN?.trim()),
+  };
+}
+
+/**
+ * The human rendering of the hub block, owned here rather than in the `ocx status` printer so
+ * the sentences are testable without spawning the CLI. Indentation is the caller's.
+ */
+export function hubStatusLines(hub: HubStatus): string[] {
+  const listener = hub.loopbackListener.state === "off"
+    ? "off — this hub does not route its own local Codex/Claude clients"
+    : hub.loopbackListener.state === "companion"
+      ? `companion on http://127.0.0.1:${hub.loopbackListener.port} — same port as the public listener, no credential needed locally`
+      : `ported on http://127.0.0.1:${hub.loopbackListener.port} — a second port local clients must be pointed at`;
+  const tokenLines = [`  Data token: ${hub.dataToken}${hub.dataToken === "missing" ? "" : ` at ${hub.dataTokenPath}`}`];
+  if (hub.dataToken === "admin-collision (file)") {
+    // Naming the consequence matters more than naming the state: this is what a crash-looping
+    // hub looks like from `ocx status`, and nothing else in the report says so (#4236).
+    tokenLines.push(
+      "    that file holds the MANAGEMENT token, so the hub fences its management API closed at boot —",
+      "    delete it and run 'ocx service repair' to generate a data-plane token",
+    );
+  }
+  if (hub.dataTokenEnvInShell) {
+    tokenLines.push("    OPENCODEX_API_AUTH_TOKEN is also set in this shell; the installed service reads the file, not this");
+  }
+  return [
+    "Hub:",
+    `  Data origin: ${hub.dataOrigin}${hub.dataOriginConfigured ? " (hub.dataPublicOrigin)" : " (derived from the bind address)"}`,
+    `  Loopback listener: ${listener}`,
+    `  Management ingress: ${hub.managementIngress.enabled ? `http://127.0.0.1:${hub.managementIngress.port}` : "disabled"}`,
+    `  Management origin: ${hub.managementPublicOrigin ?? "unset — remote pairing and the remote dashboard need hub.managementPublicOrigin"}`,
+    ...tokenLines,
+    "  Invite a machine: ocx hub invite",
+  ];
+}
+
+/** The not-connected placeholder. Arrays are empty because nothing was asked, not because nothing exists. */
+export function disconnectedRemoteHubStatus(): CliRemoteHubStatus {
+  return {
+    connected: false,
+    origin: null,
+    stateSource: "unavailable",
+    hubVersion: null,
+    providers: [],
+    oauth: [],
+    subagentModels: [],
+    truncated: false,
+    claudeCodeEnabled: null,
+  };
+}
+
+/**
+ * Ask the hub what it can serve, with a bounded read and a cache fallback.
+ *
+ * `ocx status` must answer while the hub is offline, so the fetch is bounded and a failure is
+ * reported rather than thrown. It must also never answer from local provider/login state — see
+ * `src/client/hub-state.ts` for why that substitution is the defect rather than a graceful
+ * degradation.
+ */
+export async function collectRemoteHubStatus(
+  connection: Pick<ClientConnectionStatus, "state" | "serverUrl" | "apiKeyId" | "connectedAt">,
+  options: { fetchImpl?: typeof fetch; timeoutMs?: number; now?: number } = {},
+): Promise<CliRemoteHubStatus> {
+  if (connection.state !== "connected" || !connection.serverUrl || !connection.apiKeyId || !connection.connectedAt) {
+    return disconnectedRemoteHubStatus();
+  }
+  const { resolveHubState } = await import("../client/hub-state");
+  const token = readServiceApiTokenState();
+  const resolved = await resolveHubState({
+    owner: {
+      serverUrl: connection.serverUrl,
+      apiKeyId: connection.apiKeyId,
+      connectedAt: connection.connectedAt,
+    },
+    token: token.kind === "present" ? token.token : null,
+    ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    ...(options.now === undefined ? {} : { now: options.now }),
+  });
+  return {
+    connected: true,
+    // The hub's own advertised origin when it publishes one; otherwise the URL this client
+    // dials, which is the origin the operator would recognize.
+    origin: resolved.state?.origin ?? connection.serverUrl,
+    stateSource: resolved.stateSource,
+    ...(resolved.reason ? { reason: resolved.reason } : {}),
+    ...(resolved.fetchedAt ? { fetchedAt: resolved.fetchedAt } : {}),
+    ...(resolved.ageSeconds === undefined ? {} : { ageSeconds: resolved.ageSeconds }),
+    hubVersion: resolved.state?.hubVersion ?? null,
+    providers: resolved.state?.providers ?? [],
+    oauth: resolved.state?.oauth ?? [],
+    subagentModels: resolved.state?.subagentModels ?? [],
+    truncated: resolved.state?.truncated === true,
+    claudeCodeEnabled: resolved.state ? resolved.state.claudeCode.enabled : null,
+  };
+}
+
+/**
+ * The one line that has to be read before anything else in the report.
+ *
+ * It goes FIRST, above the proxy line, because the failure mode is an agent or operator reading
+ * the provider and login lines in isolation and concluding the hub cannot do something it can.
+ * A buried `Remote hub: connected (<url>)` line — which is all this report had — does not stop
+ * that, as #4236 demonstrated.
+ */
+export function remoteHubBannerLine(remoteHub: CliRemoteHubStatus): string | null {
+  if (!remoteHub.connected) return null;
+  const origin = remoteHub.origin ?? "the hub";
+  if (remoteHub.stateSource === "unavailable") {
+    return `⚠️  Hub ${origin}: state unavailable (${remoteHub.reason ?? "unknown reason"}) — provider and login lines below are LOCAL and do not describe the hub.`;
+  }
+  const staleness = remoteHub.stateSource === "cache"
+    ? ` — cached ${remoteHub.ageSeconds ?? "?"}s ago (${remoteHub.reason ?? "live read failed"})`
+    : "";
+  return `🔗 State from hub ${origin}${staleness}: provider credentials, logins and delegable models below are the HUB's, not this machine's.`;
+}
+
+/**
+ * The hub-sourced provider/login/model block, owned here so the sentences are testable without
+ * spawning the CLI. Indentation is the caller's. Empty when nothing true is known.
+ */
+export function remoteHubStatusLines(remoteHub: CliRemoteHubStatus): string[] {
+  if (!remoteHub.connected || remoteHub.stateSource === "unavailable") return [];
+  const origin = remoteHub.origin ?? "hub";
+  const lines = [
+    `OAuth logins (hub ${origin}):`,
+    ...(remoteHub.oauth.length === 0
+      ? ["  (the hub reported no OAuth providers)"]
+      : remoteHub.oauth.map(entry => `  ${entry.provider.padEnd(10)} ${entry.loggedIn ? "✓ logged in" : "✗ not logged in"}`)),
+    `Providers (hub ${origin}):`,
+    ...(remoteHub.providers.length === 0
+      ? ["  (the hub reported no providers)"]
+      : remoteHub.providers.map(provider => {
+        // `authMode` is what keeps "no API key" from reading as "not configured": an `oauth`
+        // provider legitimately has no key and is still fully usable.
+        const credential = provider.hasCredential ? "credential stored" : `no API key (authMode ${provider.authMode ?? "key"})`;
+        return `  ${provider.name.padEnd(10)} ${provider.adapter} — ${credential}${provider.disabled ? ", disabled" : ""}`;
+      })),
+    `Delegable models (hub ${origin}): ${remoteHub.subagentModels.length === 0 ? "none" : remoteHub.subagentModels.join(", ")}`,
+  ];
+  if (remoteHub.hubVersion) lines.push(`Hub version: ${remoteHub.hubVersion}`);
+  // The hub told us its own lists are a prefix. Saying nothing here would make this report claim
+  // completeness it does not have — the same shape of confident-and-wrong answer as #4236.
+  if (remoteHub.truncated) {
+    lines.push("  (the hub truncated this state to fit its response caps; some rows are not listed)");
+  }
+  return lines;
+}
+
 export function selectListenTarget(
   config: StatusListenConfig,
   pid: number | null,
@@ -175,6 +478,10 @@ export async function collectStatus(): Promise<CliStatusView> {
     policy: claudeDesktopPolicyHealth(probeClaudeDesktopPolicy()),
   };
   const clientConnection = collectClientConnectionStatus();
+  // Asked before the local probes below so a connected client's report is hub-sourced from its
+  // first line. Bounded and failure-tolerant: an offline hub degrades the remoteHub block, it
+  // does not fail `ocx status`.
+  const remoteHub = await collectRemoteHubStatus(clientConnection);
   // Prefer identity-verified liveness (runtime-port + /healthz) over ocx.pid alone (#618).
   // Pass the already-resolved diagnostics config so findLiveProxy does not re-load and
   // warn on malformed config.json (status --json must stay stderr-clean).
@@ -274,7 +581,7 @@ export async function collectStatus(): Promise<CliStatusView> {
   }
   if (clampActive) {
     warningParts.push(
-      `Catalog clamp removed: ${lastClamp!.removedEfforts.join(", ")}. Run ocx doctor for diagnosis and recovery.`,
+      `Catalog clamp removed: ${liveRemovedEfforts(lastClamp).join(", ")}. Run ocx doctor for diagnosis and recovery.`,
     );
   }
   // A Grok fence naming a port we are not listening on is invisible everywhere else:
@@ -282,7 +589,13 @@ export async function collectStatus(): Promise<CliStatusView> {
   // no log line — ever reaches us. Surface it here, where the live port is already known.
   const grokDrift = (() => {
     try {
-      return grokFenceEndpointDrift(readGrokStatus(), health.ok ? listen.port : undefined);
+      // Locally reachable is a set: the public port plus the unauthenticated loopback
+      // listener's port. A fence naming either is correct; only a third port is drift (#4236).
+      return grokFenceEndpointDrift(
+        readGrokStatus(),
+        health.ok ? listen.port : undefined,
+        health.ok ? effectiveLoopbackListenerPort(config, listen.port) : null,
+      );
     } catch {
       return null; // reading grok's config must never break `ocx status`
     }
@@ -306,7 +619,9 @@ export async function collectStatus(): Promise<CliStatusView> {
     warning: warningParts.length > 0 ? warningParts.join(" ") : null,
     catalogClamp: {
       active: clampActive,
-      removedEfforts: clampActive ? (lastClamp?.removedEfforts ?? []) : [],
+      // Report what is still clamped, not what the file happens to name: a leftover written
+      // before the max/ultra exemption lists rungs nothing removes any more.
+      removedEfforts: clampActive ? [...liveRemovedEfforts(lastClamp)] : [],
       runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null,
     },
   };
@@ -325,6 +640,7 @@ export async function collectStatus(): Promise<CliStatusView> {
     healthLabel: health.label,
     json: {
       schemaVersion: 1,
+      runtimeRole: config.runtimeRole ?? "standalone",
       proxy: {
         running: Boolean(live) || Boolean(pid && health.ok),
         pid: live?.pid ?? pid,
@@ -350,6 +666,8 @@ export async function collectStatus(): Promise<CliStatusView> {
         source: bunRuntime.source,
         ...(bunRuntime.source === "override" ? { overrideEnv: bunRuntime.overrideEnv } : {}),
       },
+      hub: collectHubStatus(config, listen),
+      remoteHub,
       codexAutostart: codexAutoStartEnabled(config),
       startup,
       defaultProvider: typeof config.defaultProvider === "string" ? config.defaultProvider : null,
@@ -368,6 +686,8 @@ export async function collectStatus(): Promise<CliStatusView> {
         catalog: clientConnection.catalog,
         ...(clientConnection.catalogAgeSeconds !== undefined ? { catalogAgeSeconds: clientConnection.catalogAgeSeconds } : {}),
         credentialFile: clientConnection.token,
+        ...(clientConnection.readiness ? { readiness: clientConnection.readiness } : {}),
+        ...(clientConnection.readinessReason ? { readinessReason: clientConnection.readinessReason } : {}),
       },
       service: { summary: serviceSummary },
       codexShim: { summary: codexShimSummary },

package/src/cli/version-skew.ts

@@ -66,7 +66,10 @@ export function computeVersionSkew(cliVersion: string, proxyVersion: string | un
   const order = cliSemver && proxySemver ? compareVersions(cliSemver, proxySemver) : 0;
   const advice = order > 0
     ? "the running proxy is older than this CLI. Restart the proxy using the intended current installation. "
-      + "For a background service, run ocx service repair (ocx service restart is an alias)."
+      // `restart`, not `repair`: a version skew leaves the service DEFINITION unchanged, and
+      // repair reloads only when something changed, so it would no-op and keep the old
+      // process serving (#4249).
+      + "For a background service, run ocx service restart (repair reloads only a changed definition)."
     : order < 0
       ? "this ocx on PATH is older than the running proxy. Upgrade the CLI or resolve PATH to the intended installation."
       : "the versions differ, but neither can be identified as older. Check which installations the CLI and proxy use.";

package/src/cli.ts

@@ -3,8 +3,8 @@
 //
 // Before the src/ restructure the CLI lived at src/cli.ts, and durable launchers
 // (codex shim wrappers, installed service definitions) baked that absolute path
-// into their command lines. Users who upgrade in place with a bare
-// `npm install -g @bitkyc08/opencodex` (instead of `ocx update`, which repairs the
+// into their command lines. Users who upgrade in place with a bare package-manager
+// install (`npm install -g` or `pnpm add -g`) (instead of `ocx update`, which repairs the
 // shim/service) would otherwise be stranded on a dead path. Keep this stub for at
 // least one release cycle after the restructure ships.
 import "./cli/index.ts";

package/src/client/catalog-compatibility.ts

@@ -0,0 +1,192 @@
+/**
+ * #4207: a connected client reported `connected` with a present, freshly synced catalog while
+ * its installed Codex CLI exited before making a request, because the hub's catalog contained a
+ * reasoning level that CLI does not know:
+ *
+ *   failed to parse model_catalog_json ... unknown variant `max`,
+ *   expected one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`
+ *
+ * The connection state answered a different question from the one the operator was asking. It
+ * proved the hub was reachable and the credential worked; it never proved the selected local
+ * runtime could consume what was downloaded. This module supplies the missing half, and the
+ * connect path fails closed on it: an incompatible catalog is refused before it is written, so
+ * the previous known-good file survives and no success is reported.
+ *
+ * What it deliberately does not do: rewrite the hub's catalog into a locally compatible
+ * projection (the client would then silently disagree with hub truth) and terminate running
+ * Codex processes. Both are ruled out by the issue.
+ */
+import { catalogEffortCompatibility, codexSupportedReasoningEfforts } from "../codex/catalog/effort";
+import type { RawEntry } from "../codex/catalog/parsing";
+
+export type ClientCatalogCompatibility =
+  | { kind: "compatible" }
+  /** The runtime ladder could not be observed, so incompatibility cannot be established. */
+  | { kind: "unverified"; reason: string }
+  | {
+    kind: "incompatible";
+    unsupportedEfforts: readonly string[];
+    affectedModels: readonly string[];
+  };
+
+export interface CatalogCompatibilityDeps {
+  /** Injected in tests; defaults to observing the selected local Codex runtime. */
+  supportedEfforts?: () => ReadonlySet<string> | null;
+}
+
+/** State of the materialized client catalog file, as `ocx connect status` already reports it. */
+export type ClientCatalogFileState = "present" | "missing" | "unsafe";
+
+/**
+ * Whether the selected local Codex runtime can consume the catalog that is *already on disk* —
+ * a different question from the write-time gate, and the one #4207 was actually asking.
+ *
+ * The gate runs once, on bytes about to be written. It cannot speak for a file that predates it,
+ * for a file written while the ladder was {@link ClientCatalogCompatibility} `unverified`, or for
+ * a runtime that was swapped after the write. Those are exactly the states that kept reporting
+ * `connected` while `codex exec` died on `unknown variant \`max\``.
+ *
+ * Only `ready` means ready. `unverified` is not `incompatible`: a client machine may legitimately
+ * have no observable Codex CLI, and calling that an incompatibility would condemn a working
+ * install on absent evidence — the same mistake the write-time gate refuses to make.
+ */
+export type ClientCatalogReadiness =
+  | { kind: "ready" }
+  | { kind: "unverified"; reason: string }
+  | {
+    kind: "incompatible";
+    reason: string;
+    unsupportedEfforts: readonly string[];
+    affectedModels: readonly string[];
+  };
+
+function parseModels(body: string): RawEntry[] | null {
+  try {
+    const parsed = JSON.parse(body) as { models?: unknown };
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return Array.isArray(parsed.models) ? parsed.models as RawEntry[] : [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assess a downloaded catalog against the reasoning efforts the selected local Codex runtime
+ * accepts. Unreadable bytes are reported as unverified rather than incompatible: the hub
+ * client already rejects a malformed body, and inventing a second cause for it here would
+ * repeat the mistake #4169 was filed for.
+ */
+export function assessClientCatalogCompatibility(
+  body: string,
+  deps: CatalogCompatibilityDeps = {},
+): ClientCatalogCompatibility {
+  const models = parseModels(body);
+  if (!models) return { kind: "unverified", reason: "the downloaded catalog could not be read" };
+  const supported = (deps.supportedEfforts ?? (() => codexSupportedReasoningEfforts()))();
+  if (!supported) {
+    return {
+      kind: "unverified",
+      reason: "the selected local Codex runtime did not report the reasoning levels it supports",
+    };
+  }
+  const result = catalogEffortCompatibility(models, supported);
+  if (result.compatible) return { kind: "compatible" };
+  return {
+    kind: "incompatible",
+    unsupportedEfforts: result.unsupportedEfforts,
+    affectedModels: result.affectedModels,
+  };
+}
+
+/**
+ * Raised instead of writing an incompatible catalog. It names both remedies the issue asks
+ * for, because the operator cannot act on "incompatible" alone, and it never suggests editing
+ * the hub.
+ */
+export class ClientCatalogIncompatibleError extends Error {
+  readonly unsupportedEfforts: readonly string[];
+  readonly affectedModels: readonly string[];
+
+  constructor(unsupportedEfforts: readonly string[], affectedModels: readonly string[]) {
+    const efforts = unsupportedEfforts.join(", ");
+    const models = affectedModels.length > 3
+      ? `${affectedModels.slice(0, 3).join(", ")} and ${affectedModels.length - 3} more`
+      : affectedModels.join(", ");
+    super(
+      `catalog_incompatible: the hub catalog uses reasoning ${unsupportedEfforts.length === 1 ? "level" : "levels"} `
+      + `${efforts}, which the selected local Codex CLI rejects${models ? ` (${models})` : ""}. `
+      + "The previous catalog was kept and nothing was changed. Upgrade the Codex CLI to a "
+      + "version that supports those levels, or point CODEX_CLI_PATH at one that does and run "
+      + "`ocx sync`, then retry. `ocx doctor` reports which runtime is selected.",
+    );
+    this.name = "ClientCatalogIncompatibleError";
+    this.unsupportedEfforts = unsupportedEfforts;
+    this.affectedModels = affectedModels;
+  }
+}
+
+/** Fail closed: refuse an incompatible catalog before anything is written. */
+export function assertClientCatalogCompatible(body: string, deps: CatalogCompatibilityDeps = {}): void {
+  const assessment = assessClientCatalogCompatibility(body, deps);
+  if (assessment.kind !== "incompatible") return;
+  throw new ClientCatalogIncompatibleError(assessment.unsupportedEfforts, assessment.affectedModels);
+}
+
+/**
+ * Why an already-installed incompatible catalog does not reuse the refusal message above:
+ * nothing was kept back. The unusable bytes are the ones Codex will read on its next launch,
+ * so "the previous catalog was kept" would be false. The two remedies are the same, because
+ * the operator's options do not depend on when the file arrived.
+ */
+function installedCatalogRejectionReason(
+  unsupportedEfforts: readonly string[],
+  affectedModels: readonly string[],
+): string {
+  const models = affectedModels.length > 3
+    ? `${affectedModels.slice(0, 3).join(", ")} and ${affectedModels.length - 3} more`
+    : affectedModels.join(", ");
+  return `the installed catalog uses reasoning ${unsupportedEfforts.length === 1 ? "level" : "levels"} `
+    + `${unsupportedEfforts.join(", ")}, which the selected local Codex CLI rejects`
+    + `${models ? ` (${models})` : ""}. Codex exits before its first request until the CLI is `
+    + "upgraded to a version that supports those levels, or CODEX_CLI_PATH points at one that "
+    + "does and `ocx sync` is run. `ocx doctor` reports which runtime is selected.";
+}
+
+/**
+ * Assess the catalog this machine has already installed, so a surface can stop calling a
+ * connection ready when the local runtime cannot launch against it.
+ *
+ * `body` is the file's bytes, or `null` when they could not be read; `file` is the state the
+ * caller already established by stat. Neither non-present file state is an incompatibility: an
+ * absent or non-regular catalog is a different fault, and this function only ever claims an
+ * incompatibility it has proven.
+ */
+export function inspectClientCatalogReadiness(
+  file: ClientCatalogFileState,
+  body: string | null,
+  deps: CatalogCompatibilityDeps = {},
+): ClientCatalogReadiness {
+  if (file === "missing") {
+    return { kind: "unverified", reason: "no catalog is installed for the local Codex CLI to read" };
+  }
+  if (file === "unsafe") {
+    return { kind: "unverified", reason: "the catalog path is not a regular file, so its bytes were not read" };
+  }
+  if (body === null) return { kind: "unverified", reason: "the installed catalog could not be read" };
+  const assessment = assessClientCatalogCompatibility(body, deps);
+  if (assessment.kind === "compatible") return { kind: "ready" };
+  if (assessment.kind === "unverified") {
+    // assessClientCatalogCompatibility words its parse failure for bytes that have just been
+    // downloaded. These bytes are already installed, so blaming a download would send the
+    // operator to the wrong place; name the file that is actually unusable.
+    return parseModels(body) === null
+      ? { kind: "unverified", reason: "the installed catalog is not readable JSON, so the local Codex CLI cannot parse it either" }
+      : assessment;
+  }
+  return {
+    kind: "incompatible",
+    reason: installedCatalogRejectionReason(assessment.unsupportedEfforts, assessment.affectedModels),
+    unsupportedEfforts: assessment.unsupportedEfforts,
+    affectedModels: assessment.affectedModels,
+  };
+}