@bitkyc08/opencodex 2.49.0 → 2.51.0

package/src/cli/hub.ts

@@ -0,0 +1,367 @@
+import type { OcxConfig, OcxConnectedClientId } from "../types";
+import { canonicalGuiBrowserOrigin, canonicalHttpOrigin } from "../lib/gui-pair-capability";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import {
+  requestBoundGuiPairingGrant,
+  type GuiPairClientDeps,
+  type GuiPairRequestResult,
+} from "./gui-pair-client";
+import type { RuntimeApiDeps } from "./runtime-api";
+
+export const HUB_USAGE =
+  "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]";
+
+const PAIRING_WARNING = "Pairing codes are secret, single-use, and expire quickly. Do not save them.";
+
+/**
+ * The default browser origin a connecting machine presents.
+ *
+ * `ocx connect --pairing-code-stdin` exchanges the code with `Origin:` set by `localGuiOrigin()`
+ * in `src/client/connect.ts` — `http://localhost:<that machine's configured port>`, which on a
+ * fresh client is the default 10100. The hub cannot observe the other machine's port, so the
+ * grant is bound to this origin unless `corsAllowOrigins` names a different loopback one.
+ */
+const DEFAULT_CLIENT_BROWSER_ORIGIN = "http://localhost:10100";
+
+export interface HubCommandDeps extends RuntimeApiDeps {
+  loadConfig: () => OcxConfig;
+  findLiveProxy?: () => Promise<LiveProxy | null>;
+  requestPairingGrant?: (
+    target: LiveProxy,
+    browserOrigin: string,
+    deps?: GuiPairClientDeps,
+  ) => Promise<GuiPairRequestResult>;
+}
+
+export interface HubInviteOptions {
+  json: boolean;
+  dataUrl?: string;
+  managementUrl?: string;
+  clients?: string;
+}
+
+export interface HubInvitePayload {
+  code: string;
+  expiresAt: string;
+  dataUrl: string;
+  managementUrl: string;
+  command: string;
+}
+
+function isLoopbackOrigin(origin: string): boolean {
+  try {
+    const host = new URL(origin).hostname.toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+  } catch {
+    return false;
+  }
+}
+
+/** Loopback or HTTPS, the rule `consumeGuiPairingGrant` enforces on the hub side. */
+export function pairingOriginUsable(origin: string): boolean {
+  try {
+    return new URL(origin).protocol === "https:" || isLoopbackOrigin(origin);
+  } catch {
+    return false;
+  }
+}
+
+export function parseHubInviteArgs(args: string[]): HubInviteOptions | null {
+  const options: HubInviteOptions = { json: false };
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]!;
+    if (arg === "--json" && !options.json) {
+      options.json = true;
+      continue;
+    }
+    if (arg === "--data-url" || arg === "--management-url" || arg === "--clients") {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) return null;
+      const key = arg === "--data-url" ? "dataUrl" : arg === "--management-url" ? "managementUrl" : "clients";
+      if (options[key] !== undefined) return null;
+      options[key] = value;
+      continue;
+    }
+    return null;
+  }
+  return options;
+}
+
+export function parseInviteClients(raw: string | undefined): OcxConnectedClientId[] | null {
+  if (raw === undefined) return [];
+  const values = raw.split(",").map(value => value.trim()).filter(Boolean);
+  if (values.length < 1 || values.some(value => value !== "codex" && value !== "claude")) return null;
+  return values as OcxConnectedClientId[];
+}
+
+/**
+ * The browser origin the grant is bound to, or null when the hub admits none.
+ *
+ * `createGuiPairingGrant` accepts only `hub.managementPublicOrigin` itself or an entry of
+ * `corsAllowOrigins`, so this picks from exactly that set rather than guessing: the default
+ * client origin when it is admitted, otherwise the first admitted loopback origin. A hub whose
+ * allow-list names no loopback origin cannot pair a remote `ocx connect` at all, and saying so
+ * here is better than minting a code the exchange will reject.
+ */
+export function selectInviteBrowserOrigin(config: OcxConfig): string | null {
+  const allowed = [
+    canonicalGuiBrowserOrigin(config.hub?.managementPublicOrigin ?? ""),
+    ...(config.corsAllowOrigins ?? []).map(value => canonicalGuiBrowserOrigin(value)),
+  ].filter((value): value is string => Boolean(value));
+  if (allowed.includes(DEFAULT_CLIENT_BROWSER_ORIGIN)) return DEFAULT_CLIENT_BROWSER_ORIGIN;
+  return allowed.find(origin => isLoopbackOrigin(origin)) ?? null;
+}
+
+/** `http://<bind address>:<port>` — right for a plain tailnet/LAN bind with no TLS frontend. */
+export function derivedHubDataOrigin(hostname: string | undefined, port: number): string {
+  const host = probeHostname(hostname);
+  return `http://${host === "127.0.0.1" ? "localhost" : host}:${port}`;
+}
+
+/**
+ * The `ocx config set` lines that will actually work on THIS config.
+ *
+ * `setPath` in `src/cli/config-command.ts` walks only parents that already exist, so
+ * `ocx config set hub.<field> …` exits with `config parent path not found: hub` on a config
+ * that has no `hub` object yet — which is exactly the config that needs the advice. Create the
+ * parent first, the way `guides/remote-hub.md` does, and only when it is actually missing, so
+ * the operator can paste the lines verbatim either way.
+ */
+export function configSetHubLines(
+  config: Pick<OcxConfig, "hub">,
+  field: "managementPublicOrigin" | "dataPublicOrigin",
+  example: string,
+): string[] {
+  const set = `ocx config set hub.${field} '${JSON.stringify(example)}'`;
+  return config.hub ? [set] : ["ocx config set hub '{}'", set];
+}
+
+/**
+ * A `corsAllowOrigins` line that ADDS an origin instead of replacing the list.
+ *
+ * `ocx config set corsAllowOrigins '[…]'` overwrites the array, so printing a one-element
+ * literal tells an operator with an existing allow-list to delete it. The already-configured
+ * entries are known here, so the suggested value carries them.
+ */
+export function appendCorsAllowOriginsCommand(
+  config: Pick<OcxConfig, "corsAllowOrigins">,
+  origin: string,
+): string {
+  const current = config.corsAllowOrigins ?? [];
+  const next = current.includes(origin) ? current : [...current, origin];
+  return `ocx config set corsAllowOrigins '${JSON.stringify(next)}'`;
+}
+
+export type HubDataOriginResolution =
+  | { kind: "usable"; dataUrl: string; source: "flag" | "config" | "derived" }
+  /** The bind address can only be spelled as loopback, so there is nothing to advertise. */
+  | { kind: "loopback-derived"; dataUrl: string; bindHostname: string };
+
+/**
+ * The data origin to advertise, or a refusal.
+ *
+ * `derivedHubDataOrigin` maps a loopback bind AND every wildcard spelling to
+ * `http://localhost:<port>` (via `probeHostname`), which on the other machine means "dial
+ * yourself". Printing it burns the single-use code on a connect that cannot succeed, so a
+ * derived loopback origin is a refusal rather than a value. A wildcard bind is refused the same
+ * way on purpose: nothing in this repo derives a tailnet or LAN address, and guessing one from
+ * `os.networkInterfaces()` would advertise an interface the operator never chose.
+ *
+ * An explicit `--data-url` or `hub.dataPublicOrigin` is never second-guessed — a loopback data
+ * origin is legitimate when the "other machine" is reached through an SSH tunnel.
+ */
+export function resolveHubDataOrigin(
+  override: string | null,
+  configured: string | undefined,
+  bindHostname: string | undefined,
+  port: number,
+): HubDataOriginResolution {
+  if (override) return { kind: "usable", dataUrl: override, source: "flag" };
+  const fromConfig = canonicalHttpOrigin(configured);
+  if (fromConfig) return { kind: "usable", dataUrl: fromConfig, source: "config" };
+  const derived = derivedHubDataOrigin(bindHostname, port);
+  if (!isLoopbackOrigin(derived)) return { kind: "usable", dataUrl: derived, source: "derived" };
+  const trimmed = (bindHostname ?? "").trim();
+  return { kind: "loopback-derived", dataUrl: derived, bindHostname: trimmed || "127.0.0.1" };
+}
+
+/** Wildcards and loopback fail for different reasons; say which one this hub has. */
+function bindAddressPhrase(bindHostname: string): string {
+  return bindHostname === "0.0.0.0" || bindHostname === "::" || bindHostname === "[::]"
+    ? `the bind address ${bindHostname} is a wildcard, which names no address another machine can dial`
+    : `the bind address ${bindHostname} is loopback-only`;
+}
+
+/**
+ * What an operator has to know about the origin the grant actually got bound to.
+ *
+ * `selectInviteBrowserOrigin` falls back to the first admitted loopback origin when
+ * `http://localhost:10100` is not admitted, and a remote `ocx connect` sends
+ * `Origin: http://localhost:<its own configured port>` — so a grant bound to anything else is
+ * refused at the exchange and the single-use code is spent with nothing printed to explain it.
+ * Always stating the bound origin, and naming the port the client needs when it differs, is the
+ * difference between a fixable failure and a mystery.
+ */
+export function inviteBoundOriginNotes(
+  browserOrigin: string,
+  config: Pick<OcxConfig, "corsAllowOrigins">,
+): string[] {
+  const notes = [`Bound browser origin: ${browserOrigin} — the connecting machine must present exactly this.`];
+  if (browserOrigin === DEFAULT_CLIENT_BROWSER_ORIGIN) return notes;
+  const parsed = new URL(browserOrigin);
+  const port = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
+  notes.push(
+    `That is NOT ${DEFAULT_CLIENT_BROWSER_ORIGIN}, which is what an unconfigured client sends: the other machine `
+      + `must already be running on port ${port} ('ocx config set port ${port}' there) before it runs the line `
+      + "below, or the hub refuses the exchange and the code is spent.",
+  );
+  notes.push(
+    "To accept a default client instead, admit its origin on this hub: "
+      + appendCorsAllowOriginsCommand(config, DEFAULT_CLIENT_BROWSER_ORIGIN),
+  );
+  return notes;
+}
+
+export function hubInviteCommand(
+  code: string,
+  dataUrl: string,
+  managementUrl: string,
+  clients: OcxConnectedClientId[],
+): string {
+  const clientsFlag = clients.length > 0 ? ` --clients ${clients.join(",")}` : "";
+  return `echo '${code}' | ocx connect ${dataUrl} --management-url ${managementUrl}${clientsFlag} --pairing-code-stdin`;
+}
+
+async function runInvite(args: string[], deps: HubCommandDeps): Promise<number> {
+  const options = parseHubInviteArgs(args);
+  if (!options) {
+    console.error(`Usage: ${HUB_USAGE}`);
+    return 1;
+  }
+  const clients = parseInviteClients(options.clients);
+  if (!clients) {
+    console.error("--clients must contain codex and/or claude.");
+    return 1;
+  }
+  const config = deps.loadConfig();
+  if (config.runtimeRole !== "hub") {
+    console.error(
+      `ocx hub invite runs on a hub; this machine's runtimeRole is "${config.runtimeRole ?? "standalone"}". `
+        + "A client machine runs 'ocx connect' with the code its hub printed.",
+    );
+    return 1;
+  }
+  // The grant's server origin IS hub.managementPublicOrigin (createGuiPairingGrant reads it,
+  // and the exchange compares the request's management origin against it), so an invite that
+  // advertised anything else would hand out a code the hub then refuses.
+  const managementPublic = canonicalHttpOrigin(config.hub?.managementPublicOrigin);
+  if (!managementPublic) {
+    console.error(
+      "hub.managementPublicOrigin is not set, so there is no origin to pair against. Set the exact "
+        + "browser-visible HTTPS origin:",
+    );
+    for (const line of configSetHubLines(config, "managementPublicOrigin", "https://hub.tailnet.ts.net")) {
+      console.error(`  ${line}`);
+    }
+    return 1;
+  }
+  const managementOverride = options.managementUrl === undefined ? null : canonicalHttpOrigin(options.managementUrl);
+  if (options.managementUrl !== undefined && !managementOverride) {
+    console.error("--management-url must be a bare http(s) origin with no path, query, or credentials.");
+    return 1;
+  }
+  if (managementOverride && managementOverride !== managementPublic) {
+    console.error(
+      `--management-url ${managementOverride} does not match hub.managementPublicOrigin ${managementPublic}. `
+        + "The pairing code is bound to the configured origin, so the other machine would be refused.",
+    );
+    return 1;
+  }
+  if (!pairingOriginUsable(managementPublic)) {
+    console.error(
+      `hub.managementPublicOrigin ${managementPublic} is non-loopback plain HTTP, which cannot carry a `
+        + "pairing code. Put management behind an HTTPS frontend (Tailscale Serve) and set that origin.",
+    );
+    return 1;
+  }
+  const dataOverride = options.dataUrl === undefined ? null : canonicalHttpOrigin(options.dataUrl);
+  if (options.dataUrl !== undefined && !dataOverride) {
+    console.error("--data-url must be a bare http(s) origin with no path, query, or credentials.");
+    return 1;
+  }
+  const browserOrigin = selectInviteBrowserOrigin(config);
+  if (!browserOrigin) {
+    // `ocx config set corsAllowOrigins` REPLACES the array, so the suggested value carries the
+    // entries this hub already has -- a one-element literal would tell the operator to drop them.
+    console.error(
+      "No loopback browser origin is admitted for pairing. Add the connecting machine's local origin "
+        + "(this keeps the entries already configured; 'ocx config get corsAllowOrigins' shows them): "
+        + appendCorsAllowOriginsCommand(config, DEFAULT_CLIENT_BROWSER_ORIGIN),
+    );
+    return 1;
+  }
+  const target = await (deps.findLiveProxy ?? findLiveProxy)();
+  if (!target) {
+    console.error("No running attested OpenCodex hub was found. Check 'ocx service status', then 'ocx service repair'.");
+    return 1;
+  }
+  const resolved = resolveHubDataOrigin(
+    dataOverride,
+    config.hub?.dataPublicOrigin,
+    target.hostname ?? config.hostname,
+    target.port,
+  );
+  if (resolved.kind === "loopback-derived") {
+    console.error(
+      `The advertised data origin would be ${resolved.dataUrl} — this machine's own loopback — because `
+        + `${bindAddressPhrase(resolved.bindHostname)}, and nothing here guesses a tailnet or LAN address. `
+        + "The other machine would dial itself and the single-use code would be spent for nothing. Name the "
+        + "origin remote machines reach this hub's data plane on:",
+    );
+    for (const line of configSetHubLines(config, "dataPublicOrigin", "https://hub.tailnet.ts.net:8443")) {
+      console.error(`  ${line}`);
+    }
+    console.error("  ...or, for this invite only: ocx hub invite --data-url https://hub.tailnet.ts.net:8443");
+    return 1;
+  }
+  const dataUrl = resolved.dataUrl;
+  const result = await (deps.requestPairingGrant ?? requestBoundGuiPairingGrant)(target, browserOrigin, {
+    ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+  });
+  if (result.kind !== "created") {
+    console.error(`Minting a pairing code failed (${result.reason}).`);
+    return 1;
+  }
+  const payload: HubInvitePayload = {
+    code: result.grant,
+    expiresAt: new Date(result.expiresAt).toISOString(),
+    dataUrl,
+    managementUrl: managementPublic,
+    command: hubInviteCommand(result.grant, dataUrl, managementPublic, clients),
+  };
+  // Always, in both modes: the grant is bound to ONE browser origin and the operator cannot
+  // see which from the printed command (#4236 review).
+  for (const note of inviteBoundOriginNotes(browserOrigin, config)) console.error(note);
+  if (options.json) {
+    console.log(JSON.stringify(payload));
+    console.error(PAIRING_WARNING);
+    return 0;
+  }
+  // Remaining time, not the constant TTL: the number an operator reads has to be the one
+  // they actually have left by the time the line is printed.
+  const ttlSeconds = Math.max(0, Math.round((result.expiresAt - Date.now()) / 1000));
+  console.log(`Pairing code for one machine — single-use, expires in ${ttlSeconds}s (${payload.expiresAt}).`);
+  console.log("");
+  console.log("# Run on the other machine:");
+  console.log(payload.command);
+  console.error(PAIRING_WARNING);
+  return 0;
+}
+
+export async function runHubCommand(args: string[], deps: HubCommandDeps): Promise<number> {
+  if (args[0] !== "invite") {
+    console.error(`Usage: ${HUB_USAGE}`);
+    return 1;
+  }
+  return runInvite(args.slice(1), deps);
+}

package/src/cli/index.ts

@@ -48,7 +48,7 @@ import {
   pendingTeardownPathFor,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
-import { collectStatus, unusedProxyWarningLines } from "./status";
+import { collectStatus, hubStatusLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
 import { endpointsToProve, everyEndpointProvenDown, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
 
@@ -66,10 +66,11 @@ import { dispatchCommand , decideStartWithLiveOwner } from "./dispatch";
 import { findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { createReadinessGate } from "../server/readiness";
+import { isApiAuthRequired } from "../server/auth-cors";
 import { runReady, type ReadyArgs } from "./ready";
 import { runCli } from "./root";
-import { isProcessAlive, ProxyOwnershipRefusedError, stopProxy } from "../lib/process-control";
-import { loadServiceTokenFromFile } from "../lib/service-secrets";
+import { isProcessAlive, ProxyOwnershipRefusedError, refusalNextStep, stopProxy } from "../lib/process-control";
+import { startupDataPlaneToken } from "../lib/service-secrets";
 import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
 import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
@@ -81,8 +82,11 @@ import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
 import {
+  HUB_GATED_SKIP_MESSAGE,
+  localClientSkipReason,
   shouldSyncGrokOnStart,
   syncCodexOnStartIfEnabled,
+  type LocalClientSkipReason,
 } from "../codex/desired-state";
 import {
   reconcileClientStartupBeforeReady,
@@ -174,6 +178,19 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
+/**
+ * The one startup line for "nothing was written to Codex".
+ *
+ * Two very different facts reached it: the user's own OFF switch, and a hub declining to
+ * rewrite its own local clients. Printing the toggle's wording for the gate is what made
+ * operators hunt for a switch they never set (#4236).
+ */
+function startupLeftCodexNativeLine(reason: LocalClientSkipReason): string {
+  return reason === "hub-gated"
+    ? `   ${HUB_GATED_SKIP_MESSAGE} Startup left Codex native.`
+    : "   Codex integration OFF; startup left Codex native.";
+}
+
 /** Argv for detached `start`, optionally hard-pinning the listen port. */
 function startArgv(port?: number): string[] {
   const args = ["start"];
@@ -190,6 +207,10 @@ async function chooseListenPort(
   const config = loadConfig();
   const preferred = requestedPort ?? config.port ?? 10100;
   const hardPin = requestedPort !== undefined && requestedPort > 0;
+  // Only an EXPLICITLY ported listener reserves a port. The companion form (`{enabled:true}`
+  // with no port) deliberately shares the public port on 127.0.0.1, so treating it as a
+  // reservation — via `effectiveLoopbackListenerPort` — would refuse every start on a
+  // one-port hub and hop the public listener onto an ephemeral port (#4236).
   const reservedLoopbackPort = config.unauthenticatedLoopbackListener?.enabled
     ? config.unauthenticatedLoopbackListener.port
     : undefined;
@@ -271,10 +292,16 @@ async function findProxyOwnerBeforeJournalRecovery(
 }
 
 async function handleStart(options: { block?: boolean } = {}) {
-  // Native (WinSW) service mode has no batch wrapper to read the service token file
-  // into the environment, so the app loads it here before the server binds. The server
+  // Native (WinSW) service mode has no batch wrapper to read the service token file into
+  // the environment, and a FOREGROUND `ocx start` has no wrapper at all — so the app loads
+  // the token here, before the server binds, with the same precedence the launchd plist and
+  // the systemd unit use when they cat the file into the environment. Without the second
+  // source, `ocx start` refused to bind a non-loopback hostname (assertServerAuthConfig)
+  // that the installed service on the same machine was serving happily (#4236). The server
   // auth path reads OPENCODEX_API_AUTH_TOKEN from the environment.
-  const serviceToken = loadServiceTokenFromFile(process.env);
+  const serviceToken = startupDataPlaneToken(process.env, {
+    authRequired: isApiAuthRequired(loadConfig()),
+  });
   if (serviceToken) process.env.OPENCODEX_API_AUTH_TOKEN = serviceToken;
   // The service wrapper (and WinSW via OCX_API_TOKEN_FILE) can still export a colliding
   // token that install now refuses to write. Refuse it here too, before bind, so an
@@ -513,7 +540,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       }
     },
   );
-  if (!startupSync.ran) console.log("   Codex integration OFF; startup left Codex native.");
+  if (!startupSync.ran) console.log(startupLeftCodexNativeLine(localClientSkipReason(config)));
   await refreshOwnedRaycastCatalog(config, port);
   // #1046: one warning per startup, after BOTH writes. The server's cache
   // invalidation happens first and the catalog sync second, so the mtime is only
@@ -579,7 +606,9 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
         console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
         return null;
       });
-      if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
+      if (synced?.status === "skipped") {
+        console.log(startupLeftCodexNativeLine(synced.skippedReason ?? "desired_disabled"));
+      }
       // Do not refresh Raycast from saved config here: live bind/admission and
       // secondary-listener settings may differ. Explicit sync or server startup
       // owns catalog refresh; ensure must not overwrite a working destination.
@@ -626,7 +655,9 @@ async function handleEnsure(options: { existingIsSuccess?: boolean } = {}): Prom
     console.error(`⚠️  Model sync skipped: ${e instanceof Error ? e.message : String(e)}`);
     return null;
   });
-  if (synced?.status === "skipped") console.log("   Codex integration OFF; startup left Codex native.");
+  if (synced?.status === "skipped") {
+    console.log(startupLeftCodexNativeLine(synced.skippedReason ?? "desired_disabled"));
+  }
   // The child performs Raycast refresh with its actual startup config. The
   // parent's pre-spawn snapshot is not authoritative for a client-file write.
   // The child opens /healthz before its best-effort roster reconcile. Await the same idempotent
@@ -952,7 +983,12 @@ async function handleStop() {
       if (detail) console.error(`   ${detail}`);
       if (err instanceof ProxyOwnershipRefusedError) {
         ownershipBlocked = true;
-        console.error("   Skipping shared teardown (native Codex restore, Grok config): the foreign proxy is still running.");
+        // Every refusal `POST /api/stop` produces is written for an API client, so it
+        // recommends `ocx stop` — the command printing it. Following that advice returns
+        // the operator to this exact message, which is the loop #4169 was filed for. The
+        // service manager was already asked to stop above, so name what is actually left.
+        console.error(`   ${refusalNextStep(err.code)}`);
+        console.error("   Skipping shared teardown (native Codex restore, Grok config): the refusing proxy is still running.");
       }
     }
   } else {
@@ -979,7 +1015,9 @@ async function handleStop() {
         if (detail) console.error(`   ${detail}`);
         if (err instanceof ProxyOwnershipRefusedError) {
           ownershipBlocked = true;
-          console.error("   Skipping shared teardown (native Codex restore, Grok config): the foreign proxy is still running.");
+          // Same loop as the tracked-pid path above: the refusal recommends this command.
+          console.error(`   ${refusalNextStep(err.code)}`);
+          console.error("   Skipping shared teardown (native Codex restore, Grok config): the refusing proxy is still running.");
         }
       }
     } else if (live) {
@@ -1345,12 +1383,22 @@ async function handleStatus() {
     return;
   }
 
+  // First line of the report, above the proxy line, deliberately (#4236): on a connected client
+  // the provider/login/model lines describe the HUB, and the lines that describe this machine
+  // are tagged `(local)`. A reader who sees neither draws the wrong conclusion from a correct
+  // report — an agent read `xai ✗ not logged in` off a client and decided the hub could not
+  // serve grok.
+  const remoteHubBanner = remoteHubBannerLine(status.json.remoteHub);
+  if (remoteHubBanner) console.log(remoteHubBanner);
+  // `(local)` only while connected: on a standalone install every line is local, and tagging
+  // them all would be noise that trains the reader to skip the tag.
+  const local = status.json.remoteHub.connected ? " (local)" : "";
   if (status.json.proxy.pid || status.json.proxy.health.ok) {
-    console.log(`✅ Proxy: ${status.proxyLabel}`);
+    console.log(`✅ Proxy: ${status.proxyLabel}${local}`);
   } else {
-    console.log(`❌ Proxy: ${status.proxyLabel}`);
+    console.log(`❌ Proxy: ${status.proxyLabel}${local}`);
   }
-  console.log(`   Health: ${status.healthLabel}`);
+  console.log(`   Health: ${status.healthLabel}${local}`);
   if (status.json.claudeDesktop.desiredEnabled && !status.json.claudeDesktop.policy.ok) {
     console.log(`   ⚠️  Claude Desktop 3P health: ${status.json.claudeDesktop.policy.status}`);
     console.log(`      ${status.json.claudeDesktop.policy.message}`);
@@ -1390,25 +1438,31 @@ async function handleStatus() {
       ? "     Restart with 'ocx start', or refresh the installed service: 'ocx service repair'."
       : "     Restart with 'ocx start', or install the persistent service: 'ocx service install'.");
   }
-  console.log(`   Dashboard: ${status.json.dashboard.url}`);
-  console.log(`   Config: ${status.json.paths.config}`);
-  console.log(`   PID file: ${status.json.paths.pid}`);
-  console.log(`   Runtime: ${status.json.paths.runtime}`);
-  console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}`);
-  console.log(`   Default provider: ${status.json.defaultProvider}`);
+  console.log(`   Dashboard: ${status.json.dashboard.url}${local}`);
+  console.log(`   Config: ${status.json.paths.config}${local}`);
+  console.log(`   PID file: ${status.json.paths.pid}${local}`);
+  console.log(`   Runtime: ${status.json.paths.runtime}${local}`);
+  console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}${local}`);
+  // On a client this is the local default, which routing does not use — the hub applies its own.
+  console.log(`   Default provider: ${status.json.defaultProvider}${local}`);
+  // One block rather than six scattered lines, and only on a hub: `hubStatusLines` owns the
+  // sentences so they are testable without spawning the CLI. It prints no token value.
+  if (status.json.hub) {
+    for (const line of hubStatusLines(status.json.hub)) console.log(`   ${line}`);
+  }
   console.log(`   Remote hub: ${status.json.connection.state}${status.json.connection.serverUrl ? ` (${status.json.connection.serverUrl})` : ""}`);
   if (status.json.connection.state === "invalid" || status.json.connection.state === "mismatched") {
     console.log(`   ⚠️  ${status.json.connection.reason}`);
   }
-  console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}`);
-  console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}`);
-  console.log(`   ${formatStartupRoutingDetail(status.json.startup)}`);
-  console.log(`   Service: ${status.json.service.summary}`);
-  console.log(`   ${status.json.codexShim.summary}`);
-  console.log(`   Codex runtime: ${status.json.codexRuntime.path}`);
-  console.log(`   Codex version: ${status.json.codexRuntime.version ?? "unknown"}`);
-  console.log(`   Codex source: ${status.json.codexRuntime.source}`);
-  console.log(`   Codex home: ${status.json.codexHome.effectiveCodexHome}`);
+  console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}${local}`);
+  console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}${local}`);
+  console.log(`   ${formatStartupRoutingDetail(status.json.startup)}${local}`);
+  console.log(`   Service: ${status.json.service.summary}${local}`);
+  console.log(`   ${status.json.codexShim.summary}${local}`);
+  console.log(`   Codex runtime: ${status.json.codexRuntime.path}${local}`);
+  console.log(`   Codex version: ${status.json.codexRuntime.version ?? "unknown"}${local}`);
+  console.log(`   Codex source: ${status.json.codexRuntime.source}${local}`);
+  console.log(`   Codex home: ${status.json.codexHome.effectiveCodexHome}${local}`);
   if (status.json.codexHome.warning) {
     console.log(`   ⚠️  ${status.json.codexHome.warning}`);
     console.log(`      Action: ${status.json.codexHome.action}`);
@@ -1428,9 +1482,23 @@ async function handleStatus() {
     }
   }
   const { collectOAuthHealthEntriesForCli, oauthLoginSummary } = await import("../oauth");
+  const { emailMaskingEnabled } = await import("../lib/privacy");
   const { formatOAuthHealthForStatus } = await import("./status-oauth");
-  console.log(`   OAuth logins:`);
-  for (const e of oauthLoginSummary()) {
+  // On a connected client the HUB's providers and logins come first, because they are the ones
+  // that decide what a request can route to. The local block still prints — an operator debugging
+  // a half-migrated machine needs to see it — but under a heading that says it is not in use, and
+  // below the hub's, so the hub's is what a reader (or an agent) encounters first (#4236).
+  for (const line of remoteHubStatusLines(status.json.remoteHub)) console.log(`   ${line}`);
+  if (status.json.remoteHub.connected) {
+    console.log(status.json.remoteHub.stateSource === "unavailable"
+      ? "   Local-only credential state (this is NOT the hub's; the hub's state could not be read):"
+      : "   Local-only (not used for routing while connected):");
+  }
+  console.log(`   OAuth logins${local}:`);
+  // The operator's own `privacy.maskEmails` decision applies to the CLI too: `ocx status` is not
+  // the dashboard, but it reads the same stored addresses, and a flag that only moved one of the
+  // two would leave the operator unable to tell which surface they had configured.
+  for (const e of oauthLoginSummary(emailMaskingEnabled(loadConfig()))) {
     console.log(`     ${e.provider.padEnd(10)} ${e.loggedIn ? `✓ logged in${e.email ? ` (${e.email})` : ""}` : "✗ not logged in"}`);
   }
   const oauthHealthBlock = formatOAuthHealthForStatus(await collectOAuthHealthEntriesForCli());

package/src/cli/launcher-context.ts

@@ -1,5 +1,5 @@
 /**
- * Trusted facts captured by the plain-Node npm launcher before Bun auto-loads
+ * Trusted facts captured by the plain-Node package launcher before Bun auto-loads
  * project dotenv files. The random proof travels in argv while the context
  * travels in the environment, so a project `.env` cannot forge the pair during
  * an ordinary `ocx ...` invocation.

package/src/cli/models-runtime.ts

@@ -21,7 +21,7 @@ import { MAX_COST4_RATE } from "../usage/expected-prices";
 import { isValidCost4Rate } from "../usage/user-cost-overlays";
 
 const USAGE = `Usage:
-  ocx models live [--provider <name>] [--json]
+  ocx models live [--provider <name>] [--free-only] [--json]
   ocx models price <provider/model> [--json]
   ocx models set-price <provider/model> --input N --output N [--cache-read N] [--cache-write N] [--json]
   ocx models set-price <provider/model> --auto [--json]
@@ -52,17 +52,22 @@ type ModelRow = {
   custom?: boolean;
   customId?: string;
   displayName?: string;
+  pricingStatus?: "free" | "paid";
 };
 
 async function live(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
   const provider = takeOption(args, "--provider");
+  // Absent pricingStatus means the provider published no usable per-token pair, so it is
+  // excluded here for the same fail-closed reason the classifier omits it (#3666).
+  const freeOnly = takeFlag(args, "--free-only");
   rejectArgs(args, USAGE);
   const rows = await runtimeRequest<ModelRow[]>("/api/models", {}, deps);
-  const filtered = provider ? rows.filter(row => row.provider === provider) : rows;
+  const byProvider = provider ? rows.filter(row => row.provider === provider) : rows;
+  const filtered = freeOnly ? byProvider.filter(row => row.pricingStatus === "free") : byProvider;
   printData(filtered, wantsJson, filtered.map(row => {
-    const flags = [row.native ? "native" : "routed", row.custom ? "custom" : "", row.initialSelectionPending ? "initial discovery pending" : row.disabled ? "disabled" : "enabled"].filter(Boolean);
+    const flags = [row.native ? "native" : "routed", row.custom ? "custom" : "", row.pricingStatus === "free" ? "free" : "", row.initialSelectionPending ? "initial discovery pending" : row.disabled ? "disabled" : "enabled"].filter(Boolean);
     return `${row.namespaced ?? `${row.provider}/${row.id}`}  [${flags.join(", ")}]`;
   }));
 }