@bitkyc08/opencodex 2.50.0 → 2.52.0-preview.20260911

package/src/cli/dispatch.ts

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

package/src/cli/doctor.ts

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

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

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

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

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

package/src/cli/help.ts

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

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