@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/cli/claude.ts

@@ -18,12 +18,14 @@ import { isProxyAdmissionSecret } from "../server/auth-cors";
 import { findLiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { configuredAdminToken } from "../lib/admin-secrets";
+import { localAdmissionToken, localInferenceDestination, localLoopbackInferencePorts, localManagementOrigin } from "../lib/local-destinations";
 import { PROXY_MARKER, ownAdmissionTokens, defaultAuthDetectDeps, detectClaudeAuth, type AuthDetectDeps } from "../claude/auth-detect";
 import { resolveClaudeAuthMode } from "../claude/auth-mode";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { selfLaunchArgv } from "../lib/self-launch-argv";
 import { ANTHROPIC_PARENT_ENV_SLOTS, trustedNodeLauncherContext, type AnthropicParentEnvSlot } from "./launcher-context";
 import { readClientConnectionState, type ClientConnectionState } from "../client/state";
+import { resolveHubState } from "../client/hub-state";
 import { readServiceApiTokenState, type ServiceApiTokenState } from "../lib/service-secrets";
 import { DEFAULT_CATALOG_PATH } from "../codex/paths";
 import { readFileSync } from "node:fs";
@@ -102,16 +104,34 @@ function isClaudeLoopbackHostname(hostname: string): boolean {
     || normalized === "[::1]";
 }
 
-function targetsLocalClaudeProxy(value: string | undefined, port: number): boolean {
+/**
+ * Is this base URL one of OURS?
+ *
+ * Two ways to be ours (#4236), because a hub has two shapes of local destination:
+ *
+ *  - a SET of loopback ports, not one port: with an unauthenticated loopback listener the
+ *    public port and the listener's port are both addresses this proxy answers on at
+ *    127.0.0.1, so a URL naming either of them was written by us. Treating the one this launch
+ *    did not pick as a foreign proxy would strip our own admission token out of the
+ *    environment. On a tailnet bind with no listener that set is EMPTY, so a leftover
+ *    `http://127.0.0.1:<port>` is correctly seen as stale rather than as ours.
+ *  - the resolved destination origin itself, which on such a bind is the bind address. Without
+ *    this arm the launch would write a base URL and then refuse to recognize it one line later.
+ */
+function targetsLocalClaudeProxy(
+  value: string | undefined,
+  ports: readonly number[],
+  ownOrigin?: string,
+): boolean {
   if (!value) return false;
   try {
     const parsed = new URL(value);
+    if (parsed.username !== "" || parsed.password !== "") return false;
+    if (ownOrigin !== undefined && parsed.origin === ownOrigin) return true;
     const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
     return parsed.protocol === "http:"
       && isClaudeLoopbackHostname(parsed.hostname)
-      && effectivePort === port
-      && parsed.username === ""
-      && parsed.password === "";
+      && ports.includes(effectivePort);
   } catch {
     return false;
   }
@@ -147,7 +167,16 @@ export function buildClaudeEnv(
 ): ClaudeLaunchEnv {
   const explicitTarget = typeof portOrTarget === "number" ? null : portOrTarget;
   const port = typeof portOrTarget === "number" ? portOrTarget : null;
-  const managedBaseUrl = explicitTarget ? new URL(explicitTarget.baseUrl).origin : `http://127.0.0.1:${port}`;
+  // A local launch dials the unauthenticated loopback listener whenever one is enabled — the
+  // only credential-free local socket a tailnet-bound hub has (#4236). With the listener OFF
+  // the destination is the BIND address, which is reachable but demands data-plane admission;
+  // the resolver says which of the two this is instead of every caller guessing.
+  const destination = port === null ? null : localInferenceDestination(config, port);
+  const managedBaseUrl = explicitTarget
+    ? new URL(explicitTarget.baseUrl).origin
+    : destination!.origin;
+  // Every port this proxy answers on at 127.0.0.1, so a base URL naming any of them is ours.
+  const ownLocalPorts = port === null ? [] : localLoopbackInferencePorts(config, port);
   const env: ClaudeLaunchEnv = { ...base };
   // Step 1 — strip OUR OWN dummy from the inherited environment before anything reads
   // or writes the token slot. setDefault below preserves any non-empty value, so a
@@ -188,10 +217,14 @@ export function buildClaudeEnv(
     try {
       const parsed = new URL(existingBaseUrl);
       const effectivePort = parsed.port === "" ? 80 : Number(parsed.port);
+      // Stale means "a port no live local listener of ours owns". With a loopback listener
+      // enabled that is two ports, and rewriting one of them into the other would reject a
+      // destination we wrote ourselves.
       if (parsed.protocol === "http:"
         && isClaudeLoopbackHostname(parsed.hostname)
-        && effectivePort !== port) {
-        const replacement = `http://127.0.0.1:${port}`;
+        && !ownLocalPorts.includes(effectivePort)
+        && parsed.origin !== managedBaseUrl) {
+        const replacement = managedBaseUrl;
         console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${parsed.origin} with ${replacement}.`);
         env.ANTHROPIC_BASE_URL = replacement;
         // The credentials in this environment were paired with the destination we just
@@ -216,10 +249,19 @@ export function buildClaudeEnv(
   // the user's Claude login. Resolve the mode before adding any proxy-owned credential:
   // subscription launches must keep their OAuth, while proxy launches may use the
   // admission key or dummy marker (see server/claude-messages.ts).
-  const ownTokens = explicitTarget ? [explicitTarget.admissionToken] : ownAdmissionTokens(config);
+  // A bind that demands admission needs a credential the machine can actually present, which
+  // is wider than `config.apiKeys`: the service installs its data-plane secret as
+  // `OPENCODEX_API_AUTH_TOKEN` / the hardened token file, and that is the ladder the Codex
+  // provider table already uses. Never the admin token (reviewer constraint on #4236).
+  const hostAdmissionToken = destination?.requiresAdmissionToken === true
+    ? localAdmissionToken(config)
+    : undefined;
+  const ownTokens = explicitTarget
+    ? [explicitTarget.admissionToken]
+    : [...new Set([...(hostAdmissionToken ? [hostAdmissionToken] : []), ...ownAdmissionTokens(config)])];
   const targetsLocalProxy = explicitTarget
     ? targetsClaudeRoutingTarget(env.ANTHROPIC_BASE_URL, explicitTarget)
-    : targetsLocalClaudeProxy(env.ANTHROPIC_BASE_URL, port!);
+    : targetsLocalClaudeProxy(env.ANTHROPIC_BASE_URL, ownLocalPorts, managedBaseUrl);
   const isOwnAdmissionToken = (value: string): boolean =>
     ownTokens.includes(value) || isProxyAdmissionSecret(value, config);
   const inheritedApiKey = env.ANTHROPIC_API_KEY;
@@ -265,6 +307,19 @@ export function buildClaudeEnv(
   if (!env.ANTHROPIC_AUTH_TOKEN && !hasUserApiKey && targetsLocalProxy && resolved.markerMode === "proxy") {
     env.ANTHROPIC_AUTH_TOKEN = PROXY_MARKER;
   }
+  // Degrade out loud rather than hand Claude Code a destination that 401s (#4236). A
+  // subscription launch deliberately carries no host token — asserting one logs a claude.ai
+  // subscriber out (#253) — so on a bind that demands admission the honest outcome is a
+  // warning naming the two fixes, not a silent refusal at the first request.
+  if (destination?.requiresAdmissionToken === true && targetsLocalProxy) {
+    const carried = env.ANTHROPIC_AUTH_TOKEN?.trim();
+    if (!hasUserApiKey && (!carried || carried === PROXY_MARKER)) {
+      console.error(
+        `⚠ ${managedBaseUrl} requires an opencodex data-plane credential and this launch carries none — `
+        + "requests will be refused. Enable `unauthenticatedLoopbackListener` or bind the proxy to loopback.",
+      );
+    }
+  }
   const finalAuthToken = env.ANTHROPIC_AUTH_TOKEN;
   const hostOwnsAuthentication = targetsLocalProxy
     && !hasUserApiKey
@@ -335,6 +390,12 @@ export function buildClaudeEnv(
  * Context-window map from the RUNNING proxy's management API (warm TTL cache; the
  * daemon registers every selector form — audit R3#1). 3s bound + management auth header.
  * (no [1m] marking, conservative).
+ *
+ * This is the MANAGEMENT destination, not the inference one (#4236): `/api/claude-code` is
+ * never served by the unauthenticated loopback listener, so it resolves through
+ * `localManagementOrigin` — a hub's loopback management ingress when it has one, otherwise the
+ * public bind — and keeps sending the local admin token. `enabled: false` is how `ocx claude`
+ * decides to launch natively, so a wrong destination here silently downgrades every launch.
  */
 export interface ClaudeCodeLiveState {
   contextWindows: Record<string, number>;
@@ -346,7 +407,7 @@ export async function fetchClaudeCodeState(config: OcxConfig, port: number, time
     const headers = new Headers();
     const token = configuredAdminToken();
     if (token) headers.set("x-opencodex-api-key", token);
-    const res = await fetch(`http://127.0.0.1:${port}/api/claude-code`, {
+    const res = await fetch(`${localManagementOrigin(config, port)}/api/claude-code`, {
       headers,
       signal: AbortSignal.timeout(timeoutMs),
     });
@@ -525,7 +586,16 @@ export function buildNativeClaudeEnv(
     return Boolean(value && (value === PROXY_MARKER || isProxyAdmissionSecret(value, config)));
   });
   const baseUrl = env.ANTHROPIC_BASE_URL;
-  if (hasOwnedAdmission && targetsLocalClaudeProxy(baseUrl, config.port)) {
+  // Shedding asks a DIFFERENT question than the stale-replacement branch above, so it uses a
+  // wider set (#4236). There the question is "is this inherited URL a live destination of
+  // ours?" and a port nothing answers on must be rewritten. Here it is "could we have written
+  // this?" — and the answer is yes for the public port on any topology, because an earlier
+  // config on this machine may have been loopback-bound. Leaving such a URL in place with its
+  // admission token stripped (the loop below always strips it) would point a native launch at a
+  // dead socket with no credential, which is strictly worse than shedding one port too many.
+  const nativeLocalPorts = [...new Set([config.port, ...localLoopbackInferencePorts(config, config.port)])];
+  const nativeOwnOrigin = localInferenceDestination(config, config.port).origin;
+  if (hasOwnedAdmission && targetsLocalClaudeProxy(baseUrl, nativeLocalPorts, nativeOwnOrigin)) {
     delete env.ANTHROPIC_BASE_URL;
   }
   for (const name of admissionSlots) {
@@ -594,6 +664,43 @@ export function rootSkipPermissionsNotice(env: ClaudeLaunchEnv): string {
   return `⚠ Root --dangerously-skip-permissions requested: preserving user IS_SANDBOX=${env.IS_SANDBOX}; Claude Code's root guard remains in control.`;
 }
 
+/**
+ * The hub's featured subagent roster, or undefined to fall back to local `subagentModels`.
+ *
+ * Best-effort by design: a launch must not fail because the hub is slow or old. But the
+ * fallback is ANNOUNCED (#4236) — a silently local roster is exactly how an operator came to
+ * believe a hub that serves grok could only delegate to five native models.
+ *
+ * An empty hub roster is honoured as empty, not treated as "no answer": an operator who cleared
+ * the hub's featured list meant it.
+ */
+export async function resolveHubRosterForClaude(
+  connection: { serverUrl: string; apiKeyId: string; connectedAt: string },
+  token: string,
+  deps: { resolve?: typeof resolveHubState; warn?: (message: string) => void } = {},
+): Promise<readonly string[] | undefined> {
+  const warn = deps.warn ?? (message => console.error(message));
+  const resolve = deps.resolve ?? resolveHubState;
+  try {
+    const resolved = await resolve({
+      owner: { serverUrl: connection.serverUrl, apiKeyId: connection.apiKeyId, connectedAt: connection.connectedAt },
+      token,
+    });
+    if (!resolved.state) {
+      warn(`⚠ Hub roster unavailable (${resolved.reason ?? "unknown reason"}); using this machine's local subagentModels instead. The delegable agents below may not be what the hub can route.`);
+      return undefined;
+    }
+    if (resolved.stateSource === "cache") {
+      warn(`⚠ Hub roster came from a cached read ${resolved.ageSeconds ?? "?"}s old (${resolved.reason ?? "live read failed"}).`);
+    }
+    return resolved.state.subagentModels;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    warn(`⚠ Hub roster could not be read (${message}); using this machine's local subagentModels instead.`);
+    return undefined;
+  }
+}
+
 export async function cmdClaude(args: string[]): Promise<number> {
   const config = loadConfig();
   const clientState = readClientConnectionState();
@@ -606,10 +713,13 @@ export async function cmdClaude(args: string[]): Promise<number> {
   if (preflight.kind === "native") return launchNativeClaude(config, args, preflight.notice);
   let route: number | ClaudeRoutingTarget;
   let contextWindows: Record<string, number>;
+  /** The hub's featured roster on a connected client; undefined means "use local config". */
+  let hubRoster: readonly string[] | undefined;
   if (clientState.kind === "connected") {
     if (tokenState?.kind !== "present") return 1;
     route = { baseUrl: clientState.value.serverUrl, admissionToken: tokenState.token };
     contextWindows = readConnectedClaudeContextWindows();
+    hubRoster = await resolveHubRosterForClaude(clientState.value, tokenState.token);
   } else {
     const port = await ensureProxyForClaude();
     if (!port) {
@@ -641,16 +751,24 @@ export async function cmdClaude(args: string[]): Promise<number> {
     console.error(`⚠ Gateway model cache could not be refreshed: ${message}`);
   }
   // Sync roster agents (devlog 070): subagentModels + self -> ~/.claude/agents/ocx-*.md.
-  if (typeof route === "number") {
-    try {
-      const written = injectClaudeAgentDefs(config, contextWindows);
-      if (written === null) {
-        console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
+  //
+  // This used to run only when `route` was a number — i.e. never on a connected client, where
+  // `route` is a ClaudeRoutingTarget (#4236). So `~/.claude/agents/ocx-*.md` on a client stayed
+  // whatever a previous standalone run had left, and the five delegable agents an operator saw
+  // were a frozen snapshot of a machine that no longer does the routing. Nothing in the output
+  // said so; the roster simply looked like the answer.
+  //
+  // On a client the roster comes from the hub, because the local `subagentModels` list is the
+  // one this machine had before it joined. The five-row cap stays: it is a Claude Code picker
+  // constraint, not the defect — sourcing the five from the wrong machine was.
+  try {
+    const written = injectClaudeAgentDefs(config, contextWindows, undefined, hubRoster);
+    if (written === null) {
+      console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
     }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
   }
   return spawnClaude(args, env);
 }

package/src/cli/config-command.ts

@@ -4,6 +4,7 @@ import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeMo
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
 import type { OcxConfig } from "../types";
 import { normalizeVisionReasoningForModel } from "../vision/reasoning";
+import type { ClientConnectionStatus } from "./connect";
 import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
 
 const USAGE = `Usage:
@@ -26,8 +27,55 @@ const USAGE = `Usage:
 const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret|webhookUrl)$/i;
 const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 
+/**
+ * The synthetic `_remoteHub` note printed by `ocx config show` on a client (#4236).
+ *
+ * `runtimeRole: "client"` and the `client` block were already printed, and were already ignored:
+ * an agent read a client's `config.json`, saw an empty `providers` map and no grok, and concluded
+ * the hub could not serve grok. Naming the situation in the config output costs one key.
+ *
+ * `connected` is OBSERVED, never assumed. It was briefly hardcoded `true` for any config with a
+ * `client` block, which is the same defect in miniature: the presence of configuration is not
+ * evidence that the connection works, and a machine whose data-plane token was revoked, rotated
+ * away or deleted would have been labelled `connected: true` while it could not reach the hub at
+ * all. `collectClientConnectionStatus` is the one reader that knows — it compares the token file's
+ * fingerprint against the connection record — so the caller passes its answer in and this stays
+ * pure and testable.
+ *
+ * Synthetic and NOT persisted, for two reasons. `clientConnectionSchema` is `.strict()`, so a
+ * `client.note` field would not validate; and persisted prose drifts from the behaviour it
+ * describes. The leading underscore marks it as an annotation rather than a setting, and
+ * `config export` emits the real config untouched so round-trips still validate.
+ */
+export function remoteHubConfigNote(
+  config: OcxConfig,
+  readConnection: () => Pick<ClientConnectionStatus, "state" | "reason" | "token">,
+): { connected: boolean; origin: string; note: string } | null {
+  if (config.runtimeRole !== "client" || !config.client) return null;
+  // A thunk, so a standalone or hub install pays nothing: the guard above returns first and the
+  // connection probe (three file reads) never runs.
+  const connection = readConnection();
+  // Both halves are required: a settled connection record AND the token it recorded. Either one
+  // alone describes a machine that cannot read its hub, and `ocx status` is still the command
+  // that has the facts — so the note points there in every case, connected or not.
+  const connected = connection.state === "connected" && connection.token === "owned";
+  const note = connection.state !== "connected"
+    ? `this machine is configured as a client but its connection is ${connection.state}${connection.reason ? ` (${connection.reason})` : ""}; run ocx connect status`
+    : connection.token !== "owned"
+      ? `this machine is configured as a client but its hub data-plane token is ${connection.token}; run ocx connect status`
+      : "provider credentials and model availability live on the hub; run ocx status";
+  return { connected, origin: config.client.serverUrl, note };
+}
+
 function redact(value: unknown, key = ""): unknown {
   if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  // `client.priorCatalog` is the base64 catalog snapshot connect took before overwriting the
+  // local one — up to 64 MB of it (src/config.ts). Printed in full it buried `runtimeRole` and
+  // the `client` block under a wall of base64, which is how a reader came to miss that this
+  // machine is a client at all. Size only, mirroring sanitizeModelCostsForDisplay.
+  if (key === "priorCatalog" && typeof value === "string") {
+    return value ? `<omitted: ${Buffer.byteLength(value)} bytes>` : value;
+  }
   // modelCosts rows are keyed by model id; a pasted API key in a key position
   // must not be echoed back by config show/get (values are already redacted).
   if (key === "modelCosts") return sanitizeModelCostsForDisplay(value);
@@ -119,7 +167,25 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       const source = takeFlag(args, "--source");
       rejectArgs(args, USAGE);
       const diagnostics = readConfigDiagnostics();
-      const config = redact(diagnostics.config);
+      const redacted = redact(diagnostics.config);
+      // Imported here rather than at module scope: `./connect` pulls the whole client lifecycle
+      // in, and `ocx config get/set` has no use for it.
+      const { collectClientConnectionStatus } = await import("./connect");
+      // The readiness probe is declined explicitly. `collectClientConnectionStatus` observes the
+      // local Codex ladder for a connected client, and observing it spawns `codex debug models`
+      // under a 45s budget. `ocx config show` reads only `state`, `reason` and `token` from the
+      // result, so paying for a subprocess here would buy nothing and would quietly turn a
+      // read-only config dump into a runtime probe. Returning no ladder resolves readiness to
+      // `unverified`, which is the honest answer for a caller that never asked.
+      const note = remoteHubConfigNote(
+        diagnostics.config,
+        () => collectClientConnectionStatus(undefined, undefined, { supportedEfforts: () => null }),
+      );
+      // First key, not last: it has to be read before the empty `providers` map that misled a
+      // reader into concluding nothing was configured anywhere.
+      const config = note && redacted && typeof redacted === "object" && !Array.isArray(redacted)
+        ? { _remoteHub: note, ...redacted as Record<string, unknown> }
+        : redacted;
       const result = source ? { config, source: diagnostics.source, error: diagnostics.error, warnings: diagnostics.warnings ?? [] } : config;
       printData(result, true);
       return;

package/src/cli/connect.ts

@@ -1,5 +1,13 @@
-import { existsSync, lstatSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { DEFAULT_CATALOG_PATH } from "../codex/paths";
+import { codexSupportedReasoningEfforts } from "../codex/catalog/effort";
+import { resolveCodexRuntime } from "../codex/runtime";
+import {
+  inspectClientCatalogReadiness,
+  type CatalogCompatibilityDeps,
+  type ClientCatalogFileState,
+  type ClientCatalogReadiness,
+} from "../client/catalog-compatibility";
 import {
   disconnectClient,
   revokeConnectedClientKey,
@@ -26,6 +34,12 @@ import {
 
 export interface ClientCommandDeps extends RuntimeApiDeps {
   lifecycleLockDeps?: ClientLifecycleLockDeps;
+  catalogProbeDeps?: ClientCatalogProbeDeps;
+}
+
+export interface ClientCatalogProbeDeps extends CatalogCompatibilityDeps {
+  /** Injected in tests; defaults to reading the materialized client catalog off disk. */
+  readCatalogBody?: () => string | null;
 }
 
 export const CONNECT_USAGE = `Usage:
@@ -56,21 +70,96 @@ export type ClientConnectionStatus = {
   catalog: "present" | "missing" | "unsafe";
   token: "owned" | "missing" | "changed" | "unsafe";
   rotation: "clean" | "orphan-cleaned" | "recovery-required" | "unsafe";
+  /**
+   * Whether the selected local Codex CLI can actually launch against this connection (#4207).
+   *
+   * `state: "connected"` proves the hub answered and the credential works. It never proved the
+   * local runtime could consume what was downloaded, which is how a connection kept reporting
+   * itself healthy while `codex exec` exited on `unknown variant` before its first request.
+   *
+   * Reported only while connected, and reported as its own field rather than as a fourth
+   * `catalog` value: the status JSON is documented additive-only, so widening an existing
+   * field's value domain would change what `catalog: "present"` means for every consumer that
+   * already reads it.
+   */
+  readiness?: ClientCatalogReadiness["kind"];
+  /** Present whenever readiness is not `ready`; names the fault and the way out. */
+  readinessReason?: string;
 };
 
-export function collectClientConnectionStatus(now = Date.now(), lifecycleLockDeps?: ClientLifecycleLockDeps): ClientConnectionStatus {
+function readInstalledCatalogBody(): string | null {
+  try {
+    return readFileSync(DEFAULT_CATALOG_PATH, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The ladder the selected Codex CLI accepts, observed without persisting anything.
+ *
+ * `codexSupportedReasoningEfforts()` with no deps reaches `resolveAndPersistCodexRuntime`, which
+ * writes codex-runtime.json. `ocx status` deliberately resolves without persisting, and a
+ * read-only diagnostics command should not start writing runtime selection state because a
+ * readiness check was added to it. Handing the already-resolved command in as the only candidate
+ * skips that path and reuses the resolve cache `ocx status` has usually already filled.
+ */
+function observeLocalCodexEffortLadder(): ReadonlySet<string> | null {
+  const command = resolveCodexRuntime().runtime.command;
+  return codexSupportedReasoningEfforts({ commandCandidates: () => [command] });
+}
+
+/**
+ * One observer per command, for the write-time gate and the readiness check alike. Built even
+ * when nothing was injected, so production does not silently fall back to the default inside
+ * {@link assertClientCatalogCompatible} — that default persists runtime selection state and
+ * would run its own probe, which is how the two checks could disagree about the ladder within
+ * a single `ocx connect`.
+ */
+function catalogObserver(deps: ClientCatalogProbeDeps | undefined): CatalogCompatibilityDeps {
+  return { supportedEfforts: deps?.supportedEfforts ?? observeLocalCodexEffortLadder };
+}
+
+/** The stat half of the catalog verdict, shared by the status collector and `ocx connect`. */
+function installedCatalogFileState(): ClientCatalogFileState {
+  if (!existsSync(DEFAULT_CATALOG_PATH)) return "missing";
+  try {
+    const stat = lstatSync(DEFAULT_CATALOG_PATH);
+    return !stat.isSymbolicLink() && stat.isFile() ? "present" : "unsafe";
+  } catch {
+    return "unsafe";
+  }
+}
+
+/**
+ * Observing the runtime spawns `codex debug models`, so this runs only for a connected client —
+ * the one configuration that installs hub bytes the local clamp never touched. A standalone or
+ * hub install pays nothing for it.
+ *
+ * Never throws. A status command that dies because a Codex probe failed would replace one wrong
+ * answer with a worse one.
+ */
+function inspectInstalledCatalogReadiness(
+  file: ClientCatalogFileState,
+  deps: ClientCatalogProbeDeps,
+): ClientCatalogReadiness {
+  try {
+    const read = deps.readCatalogBody ?? readInstalledCatalogBody;
+    return inspectClientCatalogReadiness(file, file === "present" ? read() : null, catalogObserver(deps));
+  } catch {
+    return { kind: "unverified", reason: "the selected local Codex runtime could not be inspected" };
+  }
+}
+
+export function collectClientConnectionStatus(
+  now = Date.now(),
+  lifecycleLockDeps?: ClientLifecycleLockDeps,
+  catalogProbeDeps: ClientCatalogProbeDeps = {},
+): ClientConnectionStatus {
   const state = readClientConnectionState();
   const tokenState = readServiceApiTokenState();
   const rotation = inspectClientRotationRecoveryGate(state, lifecycleLockDeps).kind;
-  let catalog: ClientConnectionStatus["catalog"] = "missing";
-  if (existsSync(DEFAULT_CATALOG_PATH)) {
-    try {
-      const stat = lstatSync(DEFAULT_CATALOG_PATH);
-      catalog = !stat.isSymbolicLink() && stat.isFile() ? "present" : "unsafe";
-    } catch {
-      catalog = "unsafe";
-    }
-  }
+  const catalog = installedCatalogFileState();
   if (state.kind !== "connected") {
     return {
       state: state.kind,
@@ -88,6 +177,7 @@ export function collectClientConnectionStatus(now = Date.now(), lifecycleLockDep
     : tokenState.kind === "unsafe"
       ? "unsafe"
       : tokenState.fingerprint === state.value.tokenFingerprint ? "owned" : "changed";
+  const readiness = inspectInstalledCatalogReadiness(catalog, catalogProbeDeps);
   return {
     state: "connected",
     serverUrl: state.value.serverUrl,
@@ -102,6 +192,8 @@ export function collectClientConnectionStatus(now = Date.now(), lifecycleLockDep
     catalog,
     token,
     rotation,
+    readiness: readiness.kind,
+    ...(readiness.kind === "ready" ? {} : { readinessReason: readiness.reason }),
   };
 }
 
@@ -113,12 +205,74 @@ function parseClients(raw: string | undefined): OcxConnectedClientId[] {
   return values as OcxConnectedClientId[];
 }
 
+/** Reads as a verdict, not a field dump: "ready" is the only word that means the client works. */
+function readinessLine(status: ClientConnectionStatus): string {
+  const label = status.readiness === "ready"
+    ? "ready"
+    : status.readiness === "incompatible"
+      ? "not ready"
+      : "unverified";
+  return `Local Codex CLI: ${label}${status.readinessReason ? ` (${status.readinessReason})` : ""}`;
+}
+
+export type ConnectCompletionReport = {
+  readonly lines: readonly string[];
+  /** Non-null when `ocx connect` must exit non-zero rather than report success. */
+  readonly failure: string | null;
+};
+
+/**
+ * What `ocx connect` says once the hub and the credential are settled, and whether the command
+ * still fails (#4207).
+ *
+ * Pure so the fail-closed decision can be exercised without a hub. Two rules it encodes:
+ *
+ * On a proven incompatibility the verdict is printed FIRST and the `Connected to …` line is
+ * withheld, because a caller grepping for that phrase would otherwise read a catalog the local
+ * CLI cannot parse as a success. The connection really was saved, so the replacement line says
+ * where to see it.
+ *
+ * And that failure applies only when this connection selected Codex. A Claude-only connection
+ * never launches the Codex CLI, so an old binary somewhere on PATH is not a reason to fail the
+ * operator's Claude Desktop setup — it is still worth saying, which is why the line survives
+ * without the exit code.
+ */
+export function connectCompletionReport(
+  connection: { serverUrl: string; apiKeyId: string },
+  selectedClients: readonly OcxConnectedClientId[],
+  readiness: ClientCatalogReadiness,
+): ConnectCompletionReport {
+  const connected = `Connected to ${connection.serverUrl} as key ${connection.apiKeyId}.`;
+  if (readiness.kind === "ready") {
+    return { lines: [connected, "Local Codex CLI: ready (it accepts every reasoning level in the installed catalog)."], failure: null };
+  }
+  if (readiness.kind === "unverified") {
+    // Not a failure. A client with no observable Codex CLI is a working configuration, and the
+    // write-time gate deliberately lets it through; saying so is the honest middle report.
+    return { lines: [connected, `Local Codex CLI: unverified (${readiness.reason}).`], failure: null };
+  }
+  const verdict = `Local Codex CLI: not ready (${readiness.reason})`;
+  if (!selectedClients.includes("codex")) {
+    return {
+      lines: [connected, `${verdict} This connection selected ${selectedClients.join(", ")}, so nothing here launches Codex.`],
+      failure: null,
+    };
+  }
+  return {
+    lines: [verdict, `The connection to ${connection.serverUrl} as key ${connection.apiKeyId} was saved; run 'ocx connect status' to see it.`],
+    failure: `client_not_ready: ${readiness.reason}`,
+  };
+}
+
 function statusLines(status: ClientConnectionStatus): string[] {
   if (status.state !== "connected") {
     return [`Connection: ${status.state}${status.reason ? ` (${status.reason})` : ""}`];
   }
   return [
     "Connection: connected",
+    // Second line on purpose. The whole of #4207 is that a reader stopped at "connected" and
+    // believed the client was usable, so the local verdict has to arrive before the hub detail.
+    readinessLine(status),
     `Hub: ${status.serverUrl}`,
     `Management: ${status.managementUrl} (${status.managementTransport})`,
     `Protocol: ${status.protocolVersion}`,
@@ -183,8 +337,21 @@ async function runConnect(argv: string[], deps: ClientCommandDeps): Promise<void
     managementTransport,
     noSync,
     ...(catalogTimeoutSeconds === undefined ? {} : { catalogTimeoutMs: catalogTimeoutSeconds * 1_000 }),
-  }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps });
-  console.log(`Connected to ${connection.serverUrl} as key ${connection.apiKeyId}.`);
+  }, {
+    fetchImpl: deps.fetchImpl,
+    lifecycleLockDeps: deps.lifecycleLockDeps,
+    // Same observer the readiness check below uses. Passed unconditionally: leaving it out in
+    // production would let the gate fall back to its own probing, persisting default, so one
+    // command could run two probes and act on two different ladders.
+    catalogCompatibility: catalogObserver(deps.catalogProbeDeps),
+  });
+  // The hub and the credential are proven at this point; the local runtime is not. Reporting
+  // only the first half is what #4207 was filed for, so the catalog now on disk is checked
+  // against the Codex CLI that will read it.
+  const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {});
+  const report = connectCompletionReport(connection, clients, readiness);
+  for (const line of report.lines) console.log(line);
+  if (report.failure) throw new Error(report.failure);
 }
 
 async function runRevoke(argv: string[], deps: ClientCommandDeps): Promise<void> {
@@ -204,7 +371,7 @@ export async function handleConnectCommand(argv: string[], deps: ClientCommandDe
       const args = argv.slice(1);
       const wantsJson = takeFlag(args, "--json");
       rejectArgs(args, CONNECT_USAGE, { redactValues: true });
-      const status = collectClientConnectionStatus(Date.now(), deps.lifecycleLockDeps);
+      const status = collectClientConnectionStatus(Date.now(), deps.lifecycleLockDeps, deps.catalogProbeDeps ?? {});
       printData(status, wantsJson, statusLines(status));
       return;
     }