@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/cli/connect.ts

@@ -0,0 +1,226 @@
+import { existsSync, lstatSync } from "node:fs";
+import { DEFAULT_CATALOG_PATH } from "../codex/paths";
+import {
+  disconnectClient,
+  revokeConnectedClientKey,
+  rotateConnectedClientKey,
+  connectClient,
+} from "../client/connect";
+import { inspectClientRotationRecoveryGate, readClientConnectionState } from "../client/state";
+import { readServiceApiTokenState } from "../lib/service-secrets";
+import type { OcxConnectedClientId } from "../types";
+import {
+  CliUsageError,
+  csv,
+  printData,
+  readSecretLine,
+  rejectArgs,
+  runCliAction,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+export const CONNECT_USAGE = `Usage:
+  ocx connect <url> [--management-url <url>]
+      (--pairing-code-stdin | --admin-token-stdin)
+      [--clients codex,claude] [--management-transport direct|relay]
+      [--no-sync]
+  ocx connect status [--json]
+  ocx connect rotate (--pairing-code-stdin | --admin-token-stdin)
+      [--json]
+  ocx connect revoke --admin-token-stdin [--json]`;
+
+export const DISCONNECT_USAGE = `Usage:
+  ocx disconnect [--keep-catalog] [--json]`;
+
+export type ClientConnectionStatus = {
+  state: "disconnected" | "connected" | "invalid" | "mismatched";
+  reason?: string;
+  serverUrl?: string;
+  managementUrl?: string;
+  managementTransport?: "direct" | "relay";
+  protocolVersion?: number;
+  apiKeyId?: string;
+  selectedClients?: OcxConnectedClientId[];
+  connectedAt?: string;
+  catalogSyncedAt?: string;
+  catalogAgeSeconds?: number;
+  catalog: "present" | "missing" | "unsafe";
+  token: "owned" | "missing" | "changed" | "unsafe";
+  rotation: "clean" | "orphan-cleaned" | "recovery-required" | "unsafe";
+};
+
+export function collectClientConnectionStatus(now = Date.now()): ClientConnectionStatus {
+  const state = readClientConnectionState();
+  const tokenState = readServiceApiTokenState();
+  const rotation = inspectClientRotationRecoveryGate(state).kind;
+  let catalog: ClientConnectionStatus["catalog"] = "missing";
+  if (existsSync(DEFAULT_CATALOG_PATH)) {
+    try {
+      const stat = lstatSync(DEFAULT_CATALOG_PATH);
+      catalog = !stat.isSymbolicLink() && stat.isFile() ? "present" : "unsafe";
+    } catch {
+      catalog = "unsafe";
+    }
+  }
+  if (state.kind !== "connected") {
+    return {
+      state: state.kind,
+      ...(state.kind === "invalid" || state.kind === "mismatched" ? { reason: state.reason } : {}),
+      catalog,
+      token: tokenState.kind === "absent" ? "missing" : tokenState.kind === "unsafe" ? "unsafe" : "changed",
+      rotation,
+    };
+  }
+  const catalogAgeSeconds = state.value.catalogSyncedAt
+    ? Math.max(0, Math.floor((now - Date.parse(state.value.catalogSyncedAt)) / 1000))
+    : undefined;
+  const token = tokenState.kind === "absent"
+    ? "missing"
+    : tokenState.kind === "unsafe"
+      ? "unsafe"
+      : tokenState.fingerprint === state.value.tokenFingerprint ? "owned" : "changed";
+  return {
+    state: "connected",
+    serverUrl: state.value.serverUrl,
+    managementUrl: state.value.managementUrl,
+    managementTransport: state.value.managementTransport,
+    protocolVersion: state.value.protocolVersion,
+    apiKeyId: state.value.apiKeyId,
+    selectedClients: [...state.value.selectedClients],
+    connectedAt: state.value.connectedAt,
+    ...(state.value.catalogSyncedAt ? { catalogSyncedAt: state.value.catalogSyncedAt } : {}),
+    ...(catalogAgeSeconds !== undefined ? { catalogAgeSeconds } : {}),
+    catalog,
+    token,
+    rotation,
+  };
+}
+
+function parseClients(raw: string | undefined): OcxConnectedClientId[] {
+  const values = csv(raw) ?? ["codex", "claude"];
+  if (values.length < 1 || values.some(value => value !== "codex" && value !== "claude")) {
+    throw new CliUsageError("--clients must contain codex and/or claude", CONNECT_USAGE);
+  }
+  return values as OcxConnectedClientId[];
+}
+
+function statusLines(status: ClientConnectionStatus): string[] {
+  if (status.state !== "connected") {
+    return [`Connection: ${status.state}${status.reason ? ` (${status.reason})` : ""}`];
+  }
+  return [
+    "Connection: connected",
+    `Hub: ${status.serverUrl}`,
+    `Management: ${status.managementUrl} (${status.managementTransport})`,
+    `Protocol: ${status.protocolVersion}`,
+    `API key id: ${status.apiKeyId}`,
+    `Clients: ${status.selectedClients?.join(", ")}`,
+    `Token file: ${status.token}`,
+    `Key rotation: ${status.rotation}`,
+    `Catalog: ${status.catalog}${status.catalogAgeSeconds !== undefined ? ` (${status.catalogAgeSeconds}s old)` : ""}`,
+  ];
+}
+
+async function runRotate(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const pairing = takeFlag(args, "--pairing-code-stdin");
+  const admin = takeFlag(args, "--admin-token-stdin");
+  if (Number(pairing) + Number(admin) !== 1) {
+    throw new CliUsageError("choose exactly one of --pairing-code-stdin or --admin-token-stdin", CONNECT_USAGE);
+  }
+  rejectArgs(args, CONNECT_USAGE, { redactValues: true });
+  const value = new TextEncoder().encode(await readSecretLine(deps, pairing ? "pairing code" : "admin token"));
+  const connection = await rotateConnectedClientKey({
+    credential: { kind: pairing ? "pairing-grant" : "admin", value },
+  }, { fetchImpl: deps.fetchImpl });
+  printData({ apiKeyId: connection.apiKeyId, rotation: "committed" }, wantsJson, [
+    `Rotated connected API key ${connection.apiKeyId}; the previous key is no longer admitted.`,
+  ]);
+}
+
+async function runConnect(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const serverUrl = args.shift();
+  if (!serverUrl || serverUrl.startsWith("--")) throw new CliUsageError("hub URL is required", CONNECT_USAGE);
+  const managementUrl = takeOption(args, "--management-url");
+  const clients = parseClients(takeOption(args, "--clients"));
+  const managementTransport = takeOption(args, "--management-transport") ?? "direct";
+  if (managementTransport !== "direct" && managementTransport !== "relay") {
+    throw new CliUsageError("--management-transport must be direct or relay", CONNECT_USAGE);
+  }
+  const pairing = takeFlag(args, "--pairing-code-stdin");
+  const admin = takeFlag(args, "--admin-token-stdin");
+  const noSync = takeFlag(args, "--no-sync");
+  if (Number(pairing) + Number(admin) !== 1) {
+    throw new CliUsageError("choose exactly one of --pairing-code-stdin or --admin-token-stdin", CONNECT_USAGE);
+  }
+  rejectArgs(args, CONNECT_USAGE, { redactValues: true });
+  const secret = await readSecretLine(deps, pairing ? "pairing code" : "admin token");
+  const value = new TextEncoder().encode(secret);
+  const connection = await connectClient({
+    serverUrl,
+    ...(managementUrl ? { managementUrl } : {}),
+    credential: { kind: pairing ? "pairing-grant" : "admin", value },
+    selectedClients: clients,
+    managementTransport,
+    noSync,
+  }, { fetchImpl: deps.fetchImpl });
+  console.log(`Connected to ${connection.serverUrl} as key ${connection.apiKeyId}.`);
+}
+
+async function runRevoke(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const admin = takeFlag(args, "--admin-token-stdin");
+  if (!admin) throw new CliUsageError("revoke requires --admin-token-stdin", CONNECT_USAGE);
+  rejectArgs(args, CONNECT_USAGE, { redactValues: true });
+  const value = new TextEncoder().encode(await readSecretLine(deps, "admin token"));
+  const result = await revokeConnectedClientKey({ kind: "admin", value }, { fetchImpl: deps.fetchImpl });
+  printData(result, wantsJson, [`Revoked connected API key ${result.apiKeyId}. Disconnect this client next.`]);
+}
+
+export async function handleConnectCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    if (argv[0] === "status") {
+      const args = argv.slice(1);
+      const wantsJson = takeFlag(args, "--json");
+      rejectArgs(args, CONNECT_USAGE, { redactValues: true });
+      const status = collectClientConnectionStatus();
+      printData(status, wantsJson, statusLines(status));
+      return;
+    }
+    if (argv[0] === "revoke") {
+      await runRevoke(argv.slice(1), deps);
+      return;
+    }
+    if (argv[0] === "rotate") {
+      await runRotate(argv.slice(1), deps);
+      return;
+    }
+    await runConnect(argv, deps);
+  });
+}
+
+export async function handleDisconnectCommand(argv: string[]): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const keepCatalog = takeFlag(args, "--keep-catalog");
+    const wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, DISCONNECT_USAGE, { redactValues: true });
+    const result = await disconnectClient({ keepCatalog });
+    const payload = {
+      ...result,
+      revoke: {
+        apiKeyId: result.apiKeyId,
+        location: "Integrations → API Keys",
+      },
+    };
+    printData(payload, wantsJson, [
+      "Disconnected locally; native Codex state was restored.",
+      `The hub key ${result.apiKeyId} is still valid. Revoke it from Integrations → API Keys.`,
+    ]);
+  });
+}

package/src/cli/dispatch.ts

@@ -23,6 +23,7 @@ import { stripGrokConfig } from "../grok/inject";
 import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
 import { isJsonOption, takeFlag } from "./runtime-api";
+import type { ClientConnectionState } from "../client/state";
 
 export interface CliDispatchDeps {
   args: string[];
@@ -59,6 +60,13 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   start: async deps => {
+    const { readClientConnectionState } = await import("../client/state");
+    const clientState = readClientConnectionState();
+    await reconcileClientJournalBeforeLifecycle(clientState);
+    if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
+      console.error(`Client state is ${clientState.kind}: ${clientState.reason}`);
+      return 1;
+    }
     await deps.handleStart();
     return Number(process.exitCode ?? 0);
   },
@@ -245,6 +253,15 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   ensure: async deps => {
+    const { readClientConnectionState } = await import("../client/state");
+    const clientState = readClientConnectionState();
+    await reconcileClientJournalBeforeLifecycle(clientState);
+    if (clientState.kind !== "disconnected") {
+      console.error(clientState.kind === "connected"
+        ? "Client mode does not start a local provider proxy; use 'ocx sync'."
+        : `Client state is ${clientState.kind}: ${clientState.reason}`);
+      return 1;
+    }
     await deps.handleEnsure();
     return Number(process.exitCode ?? 0);
   },
@@ -317,6 +334,31 @@ const commandRunners: Record<string, CommandRunner> = {
     // Separate flag on purpose: --restart-codex promises app-server-only scope,
     // and quitting the desktop app ends live conversations.
     const restartDesktopApp = syncArgs.includes("--restart-desktop-app");
+    const { readClientConnectionState } = await import("../client/state");
+    const clientState = readClientConnectionState();
+    if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
+      console.error(`Client state is ${clientState.kind}: ${clientState.reason}`);
+      return 1;
+    }
+    if (clientState.kind === "connected") {
+      try {
+        const { syncConnectedClient } = await import("../client/connect");
+        const result = await syncConnectedClient({ restartCodex });
+        console.log(result.stale
+          ? "Hub unavailable; retained and applied the last-known-good remote catalog (stale)."
+          : "Remote hub catalog synchronized.");
+        await handleConnectedSyncCatalogWrite(result, restartCodex, restartDesktopApp);
+        // `process.exitCode` rather than a literal 0, for the same reason every other
+        // runner does it (tests/cli-transport-honesty.test.ts): the catalog-write helper
+        // drives app-server restarts, and one of those recording a failure must not be
+        // erased by the value this runner returns. It reads 0 on the ordinary path. Node
+        // types it as `number | string`; only a numeric code means anything here.
+        return typeof process.exitCode === "number" ? process.exitCode : 0;
+      } catch (error) {
+        console.error(`Connected sync failed without local fallback: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+      }
+    }
     const live = await deps.findLiveProxy();
     const synced = await syncModelsToCodex(
       live?.port,
@@ -372,6 +414,14 @@ const commandRunners: Record<string, CommandRunner> = {
     const { cmdV2 } = await import("./v2");
     return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
   },
+  connect: async deps => {
+    const { handleConnectCommand } = await import("./connect");
+    return await handleConnectCommand(deps.args.slice(1));
+  },
+  disconnect: async deps => {
+    const { handleDisconnectCommand } = await import("./connect");
+    return await handleDisconnectCommand(deps.args.slice(1));
+  },
   "sync-cache": async deps => {
     const cacheArgs = deps.args.slice(1);
     const restartCodex = cacheArgs.includes("--restart-codex");
@@ -451,27 +501,34 @@ const commandRunners: Record<string, CommandRunner> = {
     return ok ? 0 : 1;
   },
   gui: async deps => {
-    const config = deps.loadConfig();
-    // Identity-checked liveness (not the pid file + a fixed sleep): finds a fallback-port
-    // proxy and waits until the spawned one actually answers before opening the browser.
-    let live = await deps.findLiveProxy();
-    if (!live) {
-      console.log("Proxy not running. Starting...");
-      deps.spawnDetached(deps.startArgv((config.port ?? 10100) > 0 ? (config.port ?? 10100) : undefined));
-      live = await deps.waitForProxy();
-      if (!live) {
-        console.error("❌ Proxy did not become healthy after starting. Not opening the GUI.");
-        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}`;
-    console.log(`Opening ${guiUrl}`);
-    const { openUrl } = await import("../lib/open-url");
-    openUrl(guiUrl);
-    return 0;
+    const { runGuiCommand } = await import("./gui");
+    return runGuiCommand(deps.args.slice(1), {
+      loadConfig: deps.loadConfig,
+      findLiveProxy: deps.findLiveProxy,
+      openDefaultGui: async () => {
+        const config = deps.loadConfig();
+        // Identity-checked liveness (not the pid file + a fixed sleep): finds a fallback-port
+        // proxy and waits until the spawned one actually answers before opening the browser.
+        let live = await deps.findLiveProxy();
+        if (!live) {
+          console.log("Proxy not running. Starting...");
+          deps.spawnDetached(deps.startArgv((config.port ?? 10100) > 0 ? (config.port ?? 10100) : undefined));
+          live = await deps.waitForProxy();
+          if (!live) {
+            console.error("❌ Proxy did not become healthy after starting. Not opening the GUI.");
+            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}`;
+        console.log(`Opening ${guiUrl}`);
+        const { openUrl } = await import("../lib/open-url");
+        openUrl(guiUrl);
+        return 0;
+      },
+    });
   },
   service: async deps => {
     process.exitCode = 0;
@@ -779,6 +836,34 @@ export const DISPATCH_ALIASES: ReadonlyMap<string, string> = aliasTargets;
 
 /** Resolve the runner key for a command, following registry aliases to the
  * canonical runner. Returns undefined when the command is unknown. */
+/** What `handleStart` does about a live proxy it found before binding. */
+export type StartOwnerDecision = "refuse" | "service-stay-out" | "sibling";
+
+/**
+ * Pure decision for `handleStart` when the pre-bind probe found a live proxy.
+ *
+ * The #3106 guard exists so a bare `start` cannot shadow a healthy configured-port
+ * proxy with an ephemeral-port copy. An interactive `--port X` naming a DIFFERENT
+ * port than the live proxy's is an explicit sibling request, not that shadow — and
+ * refusing it also broke every spawned-launcher test on a machine running a real
+ * proxy, because the probe reaches the machine-global port across sandbox homes.
+ * The service wrapper always passes the configured port and keeps its exact
+ * stay-out-of-the-way semantics: it never takes the sibling path.
+ */
+export function decideStartWithLiveOwner(input: {
+  livePort: number;
+  requestedPort: number | undefined;
+  ocxService: string | undefined;
+}): StartOwnerDecision {
+  const sibling = input.requestedPort !== undefined
+    && input.requestedPort !== input.livePort
+    // Only the exact "1" sentinel is service context — the same check syncCleanup
+    // uses — so an env value like "0" or "false" cannot reach the stay-out path.
+    && input.ocxService !== "1";
+  if (sibling) return "sibling";
+  return input.ocxService === "1" ? "service-stay-out" : "refuse";
+}
+
 export function resolveDispatchCommand(command: string | undefined): string | undefined {
   if (command === undefined) return undefined;
   if (Object.prototype.hasOwnProperty.call(commandRunners, command)) return command;
@@ -847,3 +932,23 @@ async function handleDesktopAppRestart(log: Pick<Console, "log" | "error">): Pro
       }
   }
 }
+
+async function handleConnectedSyncCatalogWrite(
+  result: { catalogWritten: boolean; cacheSynced: boolean },
+  restartCodex: boolean,
+  restartDesktopApp: boolean,
+): Promise<void> {
+  if (!result.catalogWritten && !result.cacheSynced) return;
+  afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+  if (restartDesktopApp) await handleDesktopAppRestart(console);
+}
+
+async function reconcileClientJournalBeforeLifecycle(
+  state: ClientConnectionState,
+): Promise<void> {
+  if (state.kind === "disconnected") return;
+  const { reconcileJournal } = await import("../codex/journal");
+  reconcileJournal(state.kind === "connected"
+    ? { activeClientApiKeyId: state.value.apiKeyId }
+    : undefined);
+}

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

@@ -0,0 +1,170 @@
+import { readRuntimePort, type RuntimePortState } from "../config/process-state";
+import { timingSafeEqual } from "node:crypto";
+import {
+  LOCAL_ATTESTATION_CHALLENGE_HEADER,
+  LOCAL_ATTESTATION_PROOF_HEADER,
+  createLocalAttestationChallenge,
+  verifyLocalAttestationProof,
+} from "../lib/local-management-attestation";
+import {
+  GUI_PAIR_BROWSER_ORIGIN_HEADER,
+  GUI_PAIR_CAPABILITY_HEADER,
+  GUI_PAIR_CAPABILITY_TTL_MS,
+  GUI_PAIR_CAPABILITY_VERSION,
+  GUI_PAIR_EXPECTED_PID_HEADER,
+  GUI_PAIR_EXPIRES_AT_HEADER,
+  GUI_PAIR_METHOD,
+  GUI_PAIR_NONCE_HEADER,
+  GUI_PAIR_PATH,
+  canonicalGuiBrowserOrigin,
+  createGuiPairCapability,
+} from "../lib/gui-pair-capability";
+import { directLocalHttpFetch } from "../server/direct-local-http";
+import {
+  isOpencodexHealthz,
+  probeHostname,
+  type HealthzIdentity,
+  type LiveProxy,
+} from "../server/proxy-liveness";
+
+export type GuiPairRequestResult =
+  | { kind: "created"; grant: string; browserOrigin: string; serverOrigin: string; expiresAt: number }
+  | { kind: "unavailable"; reason: "unattested-target" | "runtime-mismatch" | "attestation" | "capability" | "transport" | "rejected" };
+
+export interface GuiPairClientDeps {
+  fetchImpl?: typeof fetch;
+  readRuntime?: (pid: number) => RuntimePortState | null;
+  createChallenge?: () => string;
+  now?: () => number;
+  timeoutMs?: number;
+}
+
+const GUI_PAIR_REQUEST_TIMEOUT_MS = 10_000;
+
+function sameRuntime(left: RuntimePortState, right: RuntimePortState | null): boolean {
+  const leftSecret = Buffer.from(left.attestationSecret ?? "");
+  const rightSecret = Buffer.from(right?.attestationSecret ?? "");
+  return !!right?.attestationSecret
+    && right.pid === left.pid
+    && right.port === left.port
+    && right.hostname === left.hostname
+    && leftSecret.length === rightSecret.length
+    && 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>;
+  if (
+    typeof record.grant !== "string"
+    || !/^ocx_pair_[A-Za-z0-9_-]{43}$/.test(record.grant)
+    || canonicalGuiBrowserOrigin(record.browserOrigin) !== browserOrigin
+    || typeof record.expiresAt !== "number"
+    || !Number.isSafeInteger(record.expiresAt)
+  ) return null;
+  const serverOrigin = canonicalHttpOrigin(record.serverOrigin);
+  if (!serverOrigin) return null;
+  return {
+    kind: "created",
+    grant: record.grant,
+    browserOrigin,
+    serverOrigin,
+    expiresAt: record.expiresAt,
+  };
+}
+
+export async function requestBoundGuiPairingGrant(
+  target: LiveProxy,
+  browserOrigin: string,
+  deps: GuiPairClientDeps = {},
+): Promise<GuiPairRequestResult> {
+  if (target.source !== "runtime" || target.pid === null || target.pid <= 0) {
+    return { kind: "unavailable", reason: "unattested-target" };
+  }
+  const canonicalOrigin = canonicalGuiBrowserOrigin(browserOrigin);
+  if (!canonicalOrigin || canonicalOrigin !== browserOrigin) {
+    return { kind: "unavailable", reason: "capability" };
+  }
+  const readRuntime = deps.readRuntime ?? readRuntimePort;
+  const runtime = readRuntime(target.pid);
+  if (!runtime?.attestationSecret || runtime.pid !== target.pid || runtime.port !== target.port) {
+    return { kind: "unavailable", reason: "runtime-mismatch" };
+  }
+  const fetchImpl = deps.fetchImpl ?? directLocalHttpFetch;
+  const timeoutMs = deps.timeoutMs ?? GUI_PAIR_REQUEST_TIMEOUT_MS;
+  const challenge = (deps.createChallenge ?? createLocalAttestationChallenge)();
+  const baseUrl = `http://${probeHostname(target.hostname)}:${target.port}`;
+  let proofResponse: Response;
+  try {
+    proofResponse = await fetchImpl(`${baseUrl}/healthz`, {
+      headers: { [LOCAL_ATTESTATION_CHALLENGE_HEADER]: challenge },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    return { kind: "unavailable", reason: "transport" };
+  }
+  const body = await proofResponse.json().catch(() => null) as HealthzIdentity | null;
+  if (
+    !proofResponse.ok
+    || !isOpencodexHealthz(body)
+    || body?.pid !== target.pid
+    || body?.port !== target.port
+    || !verifyLocalAttestationProof(
+      runtime.attestationSecret,
+      challenge,
+      target.pid,
+      target.port,
+      proofResponse.headers.get(LOCAL_ATTESTATION_PROOF_HEADER),
+    )
+  ) return { kind: "unavailable", reason: "attestation" };
+  if (body.guiPairCapability !== GUI_PAIR_CAPABILITY_VERSION) {
+    return { kind: "unavailable", reason: "capability" };
+  }
+  if (!sameRuntime(runtime, readRuntime(target.pid))) {
+    return { kind: "unavailable", reason: "runtime-mismatch" };
+  }
+  const expiresAt = (deps.now ?? Date.now)() + GUI_PAIR_CAPABILITY_TTL_MS;
+  const capability = createGuiPairCapability(
+    runtime.attestationSecret,
+    challenge,
+    GUI_PAIR_METHOD,
+    GUI_PAIR_PATH,
+    browserOrigin,
+    target.pid,
+    target.port,
+    expiresAt,
+  );
+  if (!capability) return { kind: "unavailable", reason: "capability" };
+  let response: Response;
+  try {
+    response = await fetchImpl(`${baseUrl}${GUI_PAIR_PATH}`, {
+      method: GUI_PAIR_METHOD,
+      headers: {
+        "Content-Length": "0",
+        [GUI_PAIR_EXPECTED_PID_HEADER]: String(target.pid),
+        [GUI_PAIR_NONCE_HEADER]: challenge,
+        [GUI_PAIR_EXPIRES_AT_HEADER]: String(expiresAt),
+        [GUI_PAIR_BROWSER_ORIGIN_HEADER]: browserOrigin,
+        [GUI_PAIR_CAPABILITY_HEADER]: capability,
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    return { kind: "unavailable", reason: "transport" };
+  }
+  if (!response.ok) return { kind: "unavailable", reason: "rejected" };
+  const result = parseCreatedResult(await response.json().catch(() => null), browserOrigin);
+  return result ?? { kind: "unavailable", reason: "rejected" };
+}

package/src/cli/gui.ts

@@ -0,0 +1,87 @@
+import type { OcxConfig } from "../types";
+import { canonicalGuiBrowserOrigin } from "../lib/gui-pair-capability";
+import { findLiveProxy, type LiveProxy } from "../server/proxy-liveness";
+import {
+  requestBoundGuiPairingGrant,
+  type GuiPairClientDeps,
+  type GuiPairRequestResult,
+} from "./gui-pair-client";
+import type { RuntimeApiDeps } from "./runtime-api";
+
+const GUI_USAGE = "ocx gui [pair --origin <browser-origin> [--json]]";
+const PAIRING_WARNING = "Pairing grants are secret, single-use, and expire quickly. Do not save them.";
+
+export interface GuiCommandDeps extends RuntimeApiDeps {
+  openDefaultGui: () => Promise<number>;
+  loadConfig: () => OcxConfig;
+  findLiveProxy?: () => Promise<LiveProxy | null>;
+  requestPairingGrant?: (
+    target: LiveProxy,
+    browserOrigin: string,
+    deps?: GuiPairClientDeps,
+  ) => Promise<GuiPairRequestResult>;
+}
+
+function allowedPairingOrigin(origin: string, config: OcxConfig): boolean {
+  if (config.runtimeRole !== "hub") return false;
+  if (canonicalGuiBrowserOrigin(config.hub?.managementPublicOrigin) === origin) return true;
+  return (config.corsAllowOrigins ?? []).some(value => canonicalGuiBrowserOrigin(value) === origin);
+}
+
+function parsePairArgs(args: string[]): { origin: string; json: boolean } | null {
+  let origin: string | undefined;
+  let json = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]!;
+    if (arg === "--json" && !json) {
+      json = true;
+      continue;
+    }
+    if (arg === "--origin" && origin === undefined) {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) return null;
+      origin = value;
+      continue;
+    }
+    return null;
+  }
+  return origin ? { origin, json } : null;
+}
+
+export async function runGuiCommand(args: string[], deps: GuiCommandDeps): Promise<number> {
+  if (args.length === 0) return deps.openDefaultGui();
+  if (args[0] !== "pair") {
+    console.error(`Usage: ${GUI_USAGE}`);
+    return 1;
+  }
+  const parsed = parsePairArgs(args.slice(1));
+  const canonicalOrigin = parsed ? canonicalGuiBrowserOrigin(parsed.origin) : null;
+  if (!parsed || !canonicalOrigin || canonicalOrigin !== parsed.origin) {
+    console.error(`Usage: ${GUI_USAGE}`);
+    return 1;
+  }
+  const config = deps.loadConfig();
+  if (!allowedPairingOrigin(canonicalOrigin, config)) {
+    console.error("The pairing origin is not enabled by hub.managementPublicOrigin or corsAllowOrigins.");
+    return 1;
+  }
+  const target = await (deps.findLiveProxy ?? findLiveProxy)();
+  if (!target) {
+    console.error("No running attested OpenCodex proxy is available for GUI pairing.");
+    return 1;
+  }
+  const result = await (deps.requestPairingGrant ?? requestBoundGuiPairingGrant)(target, canonicalOrigin, {
+    ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+  });
+  if (result.kind !== "created") {
+    console.error(`GUI pairing failed (${result.reason}).`);
+    return 1;
+  }
+  if (parsed.json) {
+    console.log(JSON.stringify({ ...result, warning: PAIRING_WARNING }));
+  } else {
+    console.log(result.grant);
+    console.error(PAIRING_WARNING);
+  }
+  return 0;
+}