@bitkyc08/opencodex 2.49.0 → 2.51.0

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;
     }

package/src/cli/dispatch.ts

@@ -16,7 +16,12 @@ import type { LivenessIo, LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import type { OwnedIntegrationRefreshOutcome } from "../integrations/owned-refresh";
 import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
-import { setIntegrationEnabled, shouldSyncCodexOnStart } from "../codex/desired-state";
+import {
+  HUB_GATED_SKIP_MESSAGE,
+  localClientSkipMessage,
+  setIntegrationEnabled,
+  shouldSyncCodexOnStart,
+} from "../codex/desired-state";
 import { syncModelsToCodex } from "../codex/sync";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
 import { restoreNativeCodexAsync } from "../codex/inject";
@@ -54,6 +59,24 @@ export interface CliDispatchDeps {
 
 type CommandRunner = (deps: CliDispatchDeps) => Promise<number>;
 
+/**
+ * The hub's management ingress is deliberately loopback-only. Prefer it for
+ * a browser opened on the hub itself: the proxy listener may be restricted to
+ * a Tailscale address, while the ingress is the local authenticated dashboard.
+ */
+export function selectDefaultGuiUrl(
+  config: Pick<OcxConfig, "port" | "hostname" | "runtimeRole" | "hub">,
+  live: Pick<LiveProxy, "port" | "hostname"> | null,
+  probeHostname: (hostname: string | undefined) => string,
+): string {
+  const ingress = config.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
+  if (ingress?.enabled) return `http://localhost:${ingress.port}`;
+
+  const guiHost = probeHostname(live?.hostname ?? config.hostname);
+  const hostname = guiHost === "127.0.0.1" ? "localhost" : guiHost;
+  return `http://${hostname}:${live?.port ?? config.port ?? 10100}`;
+}
+
 const commandRunners: Record<string, CommandRunner> = {
   init: async () => {
     const { runInit } = await import("./init");
@@ -105,7 +128,17 @@ const commandRunners: Record<string, CommandRunner> = {
       }
       const synced = await syncModelsToCodex(live.port);
       if (synced.status === "skipped") {
-        return emitBack(false, "Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.", 2);
+        // `setIntegrationEnabled` above just committed ON, so a skip here is NOT the toggle and
+        // is not a competing writer either — on a hub it is the role gate. Telling the operator
+        // to "retry after the competing integration change finishes" sent them waiting for a
+        // writer that does not exist (#4236).
+        return emitBack(
+          false,
+          synced.skippedReason === "hub-gated"
+            ? `${HUB_GATED_SKIP_MESSAGE} restore back did not change Codex.`
+            : "Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.",
+          2,
+        );
       }
       if (!synced.ok) {
         return emitBack(false, "Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.", 1);
@@ -372,7 +405,9 @@ const commandRunners: Record<string, CommandRunner> = {
     );
     let code = 0;
     if (synced.status === "skipped") {
-      console.log("Codex integration is OFF; sync skipped and no Codex files changed.");
+      console.log(synced.skippedReason === "hub-gated"
+        ? `${HUB_GATED_SKIP_MESSAGE} sync skipped and no Codex files changed.`
+        : "Codex integration is OFF; sync skipped and no Codex files changed.");
     } else if (synced.status === "catalog-only") {
       // Explicit sync with the integration OFF still refreshes the catalog/cache
       // for side profiles that consume the proxy without injection.
@@ -448,7 +483,8 @@ const commandRunners: Record<string, CommandRunner> = {
     const { readCodexCatalogPathForHome } = await import("../codex/catalog/parsing");
     const { existsSync } = await import("node:fs");
     const owningCodexHome = getCodexHome();
-    const desiredDisabled = !shouldSyncCodexOnStart(deps.loadConfig());
+    const cacheGateSnapshot = deps.loadConfig();
+    const desiredDisabled = !shouldSyncCodexOnStart(cacheGateSnapshot);
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
       invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
     const cacheJson = cacheArgs.includes("--json");
@@ -462,7 +498,11 @@ const commandRunners: Record<string, CommandRunner> = {
     } else if (desiredDisabled && !cacheJson) {
       // Worth saying in the human path, because it explains why nothing was written.
       // Under --json this belongs on the envelope, not as a second stdout line.
-      console.log("Codex integration is OFF; no catalog or cache write resulted.");
+      console.log(localClientSkipMessage(
+        cacheGateSnapshot,
+        "Codex integration is OFF; no catalog or cache write resulted.",
+        "No catalog or cache write resulted.",
+      ));
     }
     // `completed` with a falsy value means the cache was NOT rewritten. Previously every
     // outcome exited 0, so a script could not tell a refreshed cache from a skipped one.
@@ -535,10 +575,7 @@ const commandRunners: Record<string, CommandRunner> = {
             return 1;
           }
         }
-        // Open the host the proxy actually binds — `localhost` only answers for
-        // loopback/wildcard binds, not a concrete LAN/IPv6 hostname.
-        const guiHost = deps.probeHostname(live?.hostname ?? config.hostname);
-        const guiUrl = `http://${guiHost === "127.0.0.1" ? "localhost" : guiHost}:${live?.port ?? config.port}`;
+        const guiUrl = selectDefaultGuiUrl(config, live, deps.probeHostname);
         console.log(`Opening ${guiUrl}`);
         const { openUrl } = await import("../lib/open-url");
         openUrl(guiUrl);
@@ -546,6 +583,13 @@ const commandRunners: Record<string, CommandRunner> = {
       },
     });
   },
+  hub: async deps => {
+    const { runHubCommand } = await import("./hub");
+    return runHubCommand(deps.args.slice(1), {
+      loadConfig: deps.loadConfig,
+      findLiveProxy: deps.findLiveProxy,
+    });
+  },
   service: async deps => {
     process.exitCode = 0;
     await deps.serviceCommand(...deps.args.slice(1));

package/src/cli/doctor.ts

@@ -56,6 +56,8 @@ import {
 import { collectStartupHealth, formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import {
   displayCodexRuntimePath,
+  effortClampAppliesToRuntime,
+  liveRemovedEfforts,
   loadLastEffortClamp,
   persistCodexRuntime,
   resolveAndPersistCodexRuntime,
@@ -1177,9 +1179,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
       console.log("       Suggested: set CODEX_CLI_PATH to the desired binary and run ocx sync.");
       console.log("       Optional: ocx doctor --fix-codex-runtime");
     }
+    // Doctor used to warn on any non-empty `removedEfforts`, while `ocx status` asked
+    // `effortClampAppliesToRuntime` — so the two could disagree about the same file, and doctor
+    // would tell an operator to install a newer Codex while the resolved runtime was already
+    // newer than the one the diagnostic described. Both surfaces now read the same predicate.
     const lastClamp = loadLastEffortClamp();
-    if (lastClamp && lastClamp.removedEfforts.length > 0) {
-      console.log(`  !!  ${lastClamp.removedEfforts.join(" and ")} were removed during catalog sync.`);
+    if (effortClampAppliesToRuntime(lastClamp, resolved.runtime)) {
+      const live = liveRemovedEfforts(lastClamp);
+      console.log(`  !!  ${live.join(" and ")} were removed during catalog sync.`);
       console.log("       Suggested: set CODEX_CLI_PATH to a newer Codex binary and run ocx sync.");
     }
   }

package/src/cli/ensure-desired-integrations.ts

@@ -13,6 +13,8 @@ import { stripGrokConfig, type GrokInjectResult } from "../grok/inject";
 import { removeDesktop3pStandardPivot } from "../claude/desktop-3p";
 import {
   claudeDesktopIntegrationEnabled,
+  grokIntegrationEnabled,
+  HUB_GATED_SKIP_MESSAGE,
   shouldSyncGrokOnStart,
 } from "../codex/desired-state";
 import type { OcxConfig } from "../types";
@@ -78,6 +80,14 @@ export async function ensureGrokFenceMatchesDesired(
 ): Promise<void> {
   const config = deps.loadConfig();
   const { log, error } = io(deps);
+  // A hub-gated skip is NOT "the user turned Grok off" (#4236). Stripping the managed block
+  // there deleted a fence the operator still wants — and `ocx ensure` reported it as the
+  // Grok toggle doing its job. Only an explicit OFF authorizes the strip; the gate just
+  // declines to write, and says which key would let it.
+  if (!shouldSyncGrokOnStart(config) && grokIntegrationEnabled(config)) {
+    log(`   ${HUB_GATED_SKIP_MESSAGE} ~/.grok/config.toml was left exactly as it is.`);
+    return;
+  }
   if (!shouldSyncGrokOnStart(config)) {
     try {
       const grok = deps.stripGrokConfig();

package/src/cli/gui-pair-client.ts

@@ -17,6 +17,7 @@ import {
   GUI_PAIR_NONCE_HEADER,
   GUI_PAIR_PATH,
   canonicalGuiBrowserOrigin,
+  canonicalHttpOrigin,
   createGuiPairCapability,
 } from "../lib/gui-pair-capability";
 import { directLocalHttpFetch } from "../server/direct-local-http";
@@ -52,18 +53,6 @@ function sameRuntime(left: RuntimePortState, right: RuntimePortState | null): bo
     && timingSafeEqual(leftSecret, rightSecret);
 }
 
-function canonicalHttpOrigin(value: unknown): string | null {
-  if (typeof value !== "string") return null;
-  try {
-    const parsed = new URL(value);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
-    if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) return null;
-    return parsed.origin;
-  } catch {
-    return null;
-  }
-}
-
 function parseCreatedResult(value: unknown, browserOrigin: string): GuiPairRequestResult | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   const record = value as Record<string, unknown>;

package/src/cli/help.ts

@@ -45,7 +45,7 @@ Usage:
   ocx sync [--restart-codex]  Fetch models from providers and inject into Codex config
   ocx sync-cache [--restart-codex]
                               Refresh Codex's model cache from the active catalog
-  ocx status                  Check proxy server status
+  ocx status                  Check proxy server status (on a hub: one block with its ports and token source)
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
   ocx doctor --reclaim-response-temps
                               Reclaim abandoned response-state temp files (works without a running proxy)
@@ -56,6 +56,8 @@ Usage:
   ocx logout <provider>       Remove a stored OAuth login
   ocx gui [pair --origin <browser-origin> [--json]]
                               Open the dashboard or create a single-use remote pairing grant
+  ocx hub invite [--json]     Print a ready-to-run \`ocx connect\` line for one more machine
+                              (hub only; see \`ocx help hub\` for the one-port topology)
   ocx update [--tag <tag>]    Update opencodex (keeps preview installs on @preview)
   ocx restart                  Stop and restart the proxy
   ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|keep-native-v1|threads|mode-hint)
@@ -99,6 +101,7 @@ Examples:
   ocx start                   Start on default port (10100)
   ocx start --port 8080       Start on custom port
   ocx help service            Show service command help
+  ocx help hub                Explain the hub topology, token file, and invites
   ocx sync                    Sync available models to Codex`);
 }