@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/cli/account-extended.ts

@@ -264,6 +264,7 @@ function refreshLine(row: FamilyRows["rows"][number]): string {
   const quotaText = row.quota ? quotaParts(row.quota).join(" ") : "";
   parts.push(quotaText.length > 0 ? quotaText : "quota: unknown");
   if (row.needsReauth) parts.push("needs-reauth");
+  if (row.validationPending) parts.push("validation-pending (routing disabled; open 'ocx gui' and click Refresh quotas after recovery)");
   return parts.filter(Boolean).join(" ");
 }
 
@@ -339,7 +340,7 @@ export async function cmdRefresh(args: string[], deps: AccountDeps): Promise<num
     } else console.log(`no quota report available for ${name}`);
     return 0;
   }
-  const result = await fetchCodexRows(deps, baseUrl, true);
+  const result = await fetchCodexRows(deps, baseUrl, true, true, { refreshAction: true });
   const failed = familyFailure(result, `failed to refresh ${name}`);
   if (failed !== null) return failed;
   if (wantsJson) console.log(JSON.stringify({ accounts: result.rows }, null, 2));

package/src/cli/account.ts

@@ -99,6 +99,7 @@ function statusText(row: AccountRow): string {
   if (row.paused) parts.push("paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
   if (row.needsReauth) parts.push("needs-reauth");
+  if (row.validationPending) parts.push("validation-pending");
   return parts.join(" ");
 }
 

package/src/cli/capabilities.ts

@@ -132,6 +132,34 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads /healthz plus local config; drives no management API route."],
   },
+  {
+    command: ["hub", "invite"],
+    summary: "Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.",
+    // Deliberately empty. The command DOES drive `POST /api/gui/pairing-grants` -- the attested
+    // local mint route `ocx gui pair` uses, authorized by a capability HMAC'd with the running
+    // proxy's own attestation secret rather than by the admin token, which is why it needs
+    // nothing exported in the shell. That route is answered in the composition root, ahead of
+    // `handleManagementAPI`, so it is not in MANAGEMENT_ROUTES; declaring it here would fail the
+    // capability/registry reconciliation rather than inform anyone. Widening the registry's scope
+    // to `src/server/index.ts` is its own change.
+    routes: [],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit code, expiresAt, dataUrl, managementUrl, and command." },
+      { name: "--data-url", value: "string", summary: "Advertise this data origin instead of hub.dataPublicOrigin or the bind address." },
+      { name: "--management-url", value: "string", summary: "Confirm the management origin; it must equal hub.managementPublicOrigin." },
+      { name: "--clients", value: "string", summary: "Pre-select codex and/or claude in the printed connect command." },
+    ],
+    mutates: true,
+    json: "envelope",
+    details: [
+      "Hub only: refuses when runtimeRole is not hub, and requires a running attested proxy.",
+      "The code is secret, single-use and short-lived; it is bound to hub.managementPublicOrigin and to the connecting machine's loopback browser origin.",
+      "The bound browser origin is always printed; when it is not http://localhost:10100 the warning names the port the connecting machine must use.",
+      "Refuses when the advertised data origin would be loopback (a loopback or wildcard bind with no hub.dataPublicOrigin and no --data-url) rather than printing a line that dials the other machine itself.",
+      "Prints no data-plane token. Remote machines receive their own revocable per-client key from the exchange.",
+      "Mints through the attested local pairing-grant route, the same one ocx gui pair uses; no admin token is read.",
+    ],
+  },
   {
     command: ["connect", "rotate"],
     summary: "Rotate the connected client's data key against the hub, with commit and abort.",
@@ -219,6 +247,18 @@ export const CAPABILITIES: readonly Capability[] = [
       "`--quota` shows cached Codex windows (including 5h); `--refresh` bypasses the server TTL.",
     ],
   },
+  {
+    command: ["account", "refresh"],
+    summary: "Refresh account quotas without model validation; pending Codex accounts require dashboard consent.",
+    routes: [
+      { method: "POST", path: "/api/codex-auth/accounts/refresh" },
+      { method: "GET", path: "/api/provider-quotas" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the refresh result as JSON." }],
+    mutates: true,
+    json: "payload",
+    details: ["CLI/admin-token refreshes only observe usage. After quota recovery, a human must click Refresh quotas in the dashboard to authorize model validation. Do not mint a GUI session to work around this consent boundary."],
+  },
   {
     command: ["usage"],
     summary: "Token and estimated-cost report over a time range.",
@@ -307,12 +347,13 @@ export const CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["logs"],
-    summary: "Recent request log rows, filterable by provider, model, conversation, and status.",
+    summary: "Recent request log rows, filterable by provider, model, conversation, account, and status.",
     routes: [{ method: "GET", path: "/api/logs" }],
     flags: [
       { name: "--provider", value: "string", summary: "Restrict to one provider, matching failover attempts too." },
       { name: "--model", value: "string", summary: "Restrict to one model id, matching failover attempts too." },
       { name: "--conversation", value: "string", summary: "Restrict to one conversation id (`--conversationId` is accepted too)." },
+      { name: "--account", value: "string", summary: "Restrict to one account log label (`main`, `p<hex6>`, `o<hex6>`), matching failover attempts too." },
       { name: "--status", value: "string", summary: "An exact code (429) or a class (5xx)." },
       { name: "--limit", value: "number", summary: "Row cap; defaults to 200." },
       { name: "--follow", value: "boolean", summary: "Poll for new rows; add --jsonl to emit JSONL." },
@@ -324,6 +365,7 @@ export const CAPABILITIES: readonly Capability[] = [
     details: [
       "`--provider` and `--model` both match a failover attempt, so a request is findable by what actually served it, not only by what was asked for.",
       "Rows print `conv=<id>` when the entry carries one, so a conversation filter can be told apart from an empty result.",
+      "Rows print `acct=<label>` when the account is known, so an `--account` filter can be told apart from an empty result.",
       "`--follow` deduplicates by row id and cannot be combined with `--json`.",
     ],
   },

package/src/cli/claude-agent-startup-sync.ts

@@ -1,5 +1,6 @@
 import type { OcxConfig } from "../types";
 import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { readCachedHubState } from "../client/hub-state";
 import { fetchClaudeContextWindows } from "./claude";
 import type { ReadinessGate } from "../server/readiness";
 
@@ -7,6 +8,30 @@ export interface ClaudeAgentStartupSyncDeps {
   fetchContextWindows?: typeof fetchClaudeContextWindows;
   injectAgentDefs?: typeof injectClaudeAgentDefs;
   warn?: (message: string) => void;
+  /** Seam for the hub roster lookup; the default reads only the on-disk cache. */
+  readHubRoster?: (config: OcxConfig) => readonly string[] | undefined;
+}
+
+/**
+ * The hub's roster for a connected client, from the CACHE only (#4236).
+ *
+ * Startup deliberately makes no network call for this. The roster is a convenience here — `ocx
+ * claude` does the live read on the path where it matters — and a hub round trip on every proxy
+ * start would put an offline hub in the way of a local launch. Undefined falls back to local
+ * `subagentModels`, which is what this path has always used.
+ */
+function cachedHubRoster(config: OcxConfig): readonly string[] | undefined {
+  if (config.runtimeRole !== "client" || !config.client) return undefined;
+  try {
+    const cached = readCachedHubState({
+      serverUrl: config.client.serverUrl,
+      apiKeyId: config.client.apiKeyId,
+      connectedAt: config.client.connectedAt,
+    });
+    return cached?.state.subagentModels;
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -70,7 +95,7 @@ export async function syncClaudeAgentDefsAtProxyStartup(
       // Startup remains best-effort. The next management mutation or `ocx claude` launch can
       // restore context markers after a transient catalog/Management API failure.
     }
-    return inject(config, windows);
+    return inject(config, windows, undefined, (deps.readHubRoster ?? cachedHubRoster)(config));
   } catch (error) {
     warn(`⚠ Claude agent definitions could not be synced at proxy startup: ${error instanceof Error ? error.message : String(error)}`);
     return null;

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;