@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/cli/observe.ts

@@ -17,7 +17,7 @@ import { redactSecretString } from "../lib/redact";
 
 const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
-      [--conversation <id>] [--limit <n>] [--follow] [--json|--jsonl]
+      [--conversation <id>] [--account <label>] [--limit <n>] [--follow] [--json|--jsonl]
   ocx logs explain <request-id> [--json]
   ocx logs rebuild-index
   ocx logs index-status
@@ -58,7 +58,14 @@ function formatLog(row: LogEntry): string {
   const conversation = typeof row.conversationId === "string" && row.conversationId.length > 0
     ? `conv=${row.conversationId}`
     : "";
-  return [time, String(status), route, duration, conversation].filter(Boolean).join("  ");
+  // The account label is printed for the same reason, and for one more: it is the answer to
+  // "which of my accounts served this?" (#4057). It is only ever the stable non-PII label the
+  // proxy already persists (`main`, `p<hex6>`, `o<hex6>`) — never an email, a key, or an
+  // upstream account id. Rows from a single-account provider carry no label and print none.
+  const account = typeof row.accountLogLabel === "string" && row.accountLogLabel.length > 0
+    ? `acct=${row.accountLogLabel}`
+    : "";
+  return [time, String(status), route, duration, account, conversation].filter(Boolean).join("  ");
 }
 
 async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -72,6 +79,9 @@ async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   // Both spellings, because the server accepts both (`request-log.ts:1032`) and an operator
   // should not have to remember which one this surface wanted.
   const conversationId = takeOption(args, "--conversation") ?? takeOption(args, "--conversationId");
+  // Server-side, so `--limit` caps the rows that MATCHED rather than the rows scanned; a
+  // client-side filter after a 200-row cap would silently hide older matches.
+  const account = takeOption(args, "--account");
   const limit = takeIntegerOption(args, "--limit", { min: 1 }) ?? 200;
   rejectArgs(args, USAGE);
   if (wantsJson && wantsJsonl) throw new CliUsageError("--json and --jsonl cannot be combined", USAGE);
@@ -80,7 +90,7 @@ async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   }
   let seen = new Set<string>();
   do {
-    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, conversationId, limit })}`, {}, deps);
+    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, conversationId, account, limit })}`, {}, deps);
     const rows = logRows(data);
     if (!follow && wantsJson) printData(data, true);
     else {

package/src/cli/registry.ts

@@ -64,9 +64,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx service [install|repair|restart|start|stop|status|uninstall|remove]",
     summary: "Run as a background service.",
     details: [
-      "With no subcommand, installs when absent or repairs/restarts an existing service.",
-      "`restart` aliases `repair`; healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
-      "Use `ocx service status` to see diagnostics and log paths.",
+      "With no subcommand, installs when absent or repairs an existing service.",
+      "`repair` refreshes the definition and reloads the manager only when something changed, so repairing a healthy service is not an outage.",
+      "`restart` is the same refresh but always restarts: on macOS an unchanged, already-loaded job is kickstarted in place. Healthy Windows tasks are reused, while stale definitions may re-register and elevate.",
+      "Use `ocx service status` to see diagnostics and log paths. On macOS it reports four states:",
+      "loaded from the current plist, loaded from an OLDER plist (repair), not loaded (repair), or",
+      "`launchd state could not be verified` -- which is an unanswerable probe, NOT a down service.",
+      "Data-plane token: nothing has to be exported by hand. On a non-loopback hostname install/repair uses",
+      "OPENCODEX_API_AUTH_TOKEN when set, otherwise reuses the existing owner-only ~/.opencodex/service-api-token,",
+      "otherwise generates one; the launch wrapper reads that file at start and the value never enters a plist,",
+      "a unit file, or argv. An ADMIN token in OPENCODEX_API_AUTH_TOKEN is refused -- unset it and rerun.",
+      "Repair and restart never ask for the environment variable again once the token file exists.",
     ],
   },
   {
@@ -155,6 +163,38 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "The printed grant is secret, single-use, short-lived, and must not be persisted.",
     ],
   },
+  {
+    name: "hub",
+    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]",
+    summary: "Hub-side commands. `invite` prints a ready-to-run `ocx connect` line for one more machine.",
+    details: [
+      "Topology: a hub serves ONE port. Remote machines dial `hostname:port` with their own per-client",
+      "key; the hub's own local processes dial `127.0.0.1:<same port>` with no credential, through the",
+      "loopback companion listener enabled by `unauthenticatedLoopbackListener: {\"enabled\": true}`.",
+      "The browser-facing management plane is separate: a loopback-only ingress published by an",
+      "operator-owned HTTPS frontend (Tailscale Serve) and advertised as hub.managementPublicOrigin.",
+      "",
+      "Nothing needs to be exported by hand. `ocx service install` provisions an owner-only data-plane",
+      "token at ~/.opencodex/service-api-token and the launch wrapper reads it at start; the value never",
+      "enters a plist, a unit file, argv, or the environment you typed in. Never copy that file to another",
+      "machine -- every client gets its own revocable key from the pairing exchange.",
+      "",
+      "invite requires a running hub and mints a single-use, short-lived pairing code through the same",
+      "attested local route `ocx gui pair` uses, then prints the exact command to run on the other",
+      "machine. The code is bound to hub.managementPublicOrigin and to the connecting machine's local",
+      "browser origin (`http://localhost:10100` unless corsAllowOrigins names another loopback origin);",
+      "the bound origin is always printed, and a different one names the port the client needs.",
+      "--data-url overrides the advertised data origin; hub.dataPublicOrigin is the persistent form, and",
+      "the fallback is http://<bind address>:<port>. A loopback or wildcard bind has no such address, so",
+      "invite refuses instead of advertising http://localhost:<port>, which would tell the other machine",
+      "to dial itself and spend the code.",
+      "--management-url is a CONFIRMATION, not an override: the grant is bound to",
+      "hub.managementPublicOrigin, so a differing value is refused instead of printed.",
+      "--clients chooses which client configs the printed ocx connect line will point at the hub.",
+      "--json emits { code, expiresAt, dataUrl, managementUrl, command }. Do not persist the code.",
+      "Hub state, including the data token and the companion listener, is reported by `ocx status`.",
+    ],
+  },
   {
     name: "update",
     usage: "ocx update [--tag latest|preview]",

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