@bitkyc08/opencodex 2.65.0 → 2.66.0-preview.20260925

package/src/cli/connect.ts

@@ -15,14 +15,21 @@ import {
   connectClient,
 } from "../client/connect";
 import { inspectClientRotationRecoveryGate, readClientConnectionState } from "../client/state";
+import { readClientLinkState } from "../client/link-state";
+import { teardownClientLink } from "../client/link-teardown";
+import { reapOrphanTunnel } from "../client/link-tunnel";
 import { readServiceApiTokenState } from "../lib/service-secrets";
 import type { ClientLifecycleLockDeps } from "../client/lifecycle-lock";
+import { linkKnownHostsPath } from "../link/paths";
+import { createSshRunner, type SshRunner } from "../link/ssh-runner";
+import type { OrphanTunnelResult } from "../client/link-tunnel";
 import { inspectRemoteDesktopStore } from "../claude/desktop-remote-store";
 import type { OcxConnectedClientId } from "../types";
 import {
   CliUsageError,
   csv,
   printData,
+  readSecretBytes,
   readSecretLine,
   rejectArgs,
   runCliAction,
@@ -37,6 +44,12 @@ import {
 export interface ClientCommandDeps extends RuntimeApiDeps {
   lifecycleLockDeps?: ClientLifecycleLockDeps;
   catalogProbeDeps?: ClientCatalogProbeDeps;
+  linkTeardownDeps?: {
+    runner?: Pick<SshRunner, "run">;
+    reapOrphanTunnel?: () => Promise<OrphanTunnelResult>;
+    knownHostsFile?: string;
+    timeoutMs?: number;
+  };
 }
 
 export interface ClientCatalogProbeDeps extends CatalogCompatibilityDeps {
@@ -54,6 +67,8 @@ export interface ClientCatalogProbeDeps extends CatalogCompatibilityDeps {
 }
 
 export const CONNECT_USAGE = `Usage:
+  ocx connect --link --key-stdin --tunnel-port <port> --link-id <id>
+      [--clients codex,claude] [--catalog-timeout <seconds>] [--no-sync]
   ocx connect <url> [--management-url <url>]
       (--pairing-code-stdin | --admin-token-stdin)
       [--clients codex,claude] [--management-transport direct|relay]
@@ -72,6 +87,8 @@ export type ClientConnectionStatus = {
   serverUrl?: string;
   managementUrl?: string;
   managementTransport?: "direct" | "relay";
+  transport?: "hub" | "link";
+  link?: { tunnelPort: number; linkId: string };
   protocolVersion?: number;
   apiKeyId?: string;
   selectedClients?: OcxConnectedClientId[];
@@ -199,6 +216,8 @@ export function collectClientConnectionStatus(
     serverUrl: state.value.serverUrl,
     managementUrl: state.value.managementUrl,
     managementTransport: state.value.managementTransport,
+    ...(state.value.transport ? { transport: state.value.transport } : {}),
+    ...(state.value.link ? { link: { ...state.value.link } } : {}),
     protocolVersion: state.value.protocolVersion,
     apiKeyId: state.value.apiKeyId,
     selectedClients: [...state.value.selectedClients],
@@ -221,6 +240,27 @@ function parseClients(raw: string | undefined): OcxConnectedClientId[] {
   return values as OcxConnectedClientId[];
 }
 
+async function readLinkCredential(deps: ClientCommandDeps): Promise<{ apiKeyId: string; key: string }> {
+  const raw = await readSecretBytes(deps, "link credential");
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("shape");
+    const record = parsed as Record<string, unknown>;
+    if (Object.keys(record).some(key => key !== "apiKeyId" && key !== "key")
+      || typeof record.apiKeyId !== "string" || !record.apiKeyId.trim()
+      || record.apiKeyId.length > 256 || typeof record.key !== "string"
+      || !/^ocx_data_[0-9a-f]{40}$/.test(record.key)) {
+      throw new Error("shape");
+    }
+    return { apiKeyId: record.apiKeyId, key: record.key };
+  } catch {
+    throw new CliUsageError("invalid link credential", CONNECT_USAGE);
+  } finally {
+    raw.fill(0);
+  }
+}
+
 /** Reads as a verdict, not a field dump: "ready" is the only word that means the client works. */
 function readinessLine(status: ClientConnectionStatus): string {
   const label = status.readiness === "ready"
@@ -290,6 +330,8 @@ function statusLines(status: ClientConnectionStatus): string[] {
     // Second line on purpose. The whole of #4207 is that a reader stopped at "connected" and
     // believed the client was usable, so the local verdict has to arrive before the hub detail.
     readinessLine(status),
+    `Transport: ${status.transport ?? "hub"}`,
+    ...(status.link ? [`Link: ${status.link.linkId} via tunnel port ${status.link.tunnelPort}`] : []),
     `Hub: ${status.serverUrl}`,
     `Management: ${status.managementUrl} (${status.managementTransport})`,
     `Protocol: ${status.protocolVersion}`,
@@ -323,7 +365,7 @@ async function runRotate(argv: string[], deps: ClientCommandDeps): Promise<void>
   ]);
 }
 
-async function runConnect(argv: string[], deps: ClientCommandDeps): Promise<void> {
+async function runHubConnect(argv: string[], deps: ClientCommandDeps): Promise<void> {
   const args = [...argv];
   const serverUrl = args.shift();
   if (!serverUrl || serverUrl.startsWith("--")) throw new CliUsageError("hub URL is required", CONNECT_USAGE);
@@ -375,6 +417,64 @@ async function runConnect(argv: string[], deps: ClientCommandDeps): Promise<void
   if (report.failure) throw new Error(report.failure);
 }
 
+async function runLinkConnect(argv: string[], deps: ClientCommandDeps): Promise<void> {
+  const args = [...argv];
+  const keyStdin = takeFlag(args, "--key-stdin");
+  const rawPort = takeIntegerOption(args, "--tunnel-port", { min: 1024 });
+  const linkId = takeOption(args, "--link-id");
+  const managementUrl = takeOption(args, "--management-url");
+  const managementTransport = takeOption(args, "--management-transport");
+  const pairing = takeFlag(args, "--pairing-code-stdin");
+  const admin = takeFlag(args, "--admin-token-stdin");
+  const clients = parseClients(takeOption(args, "--clients"));
+  const catalogTimeoutSeconds = takeIntegerOption(args, "--catalog-timeout", { min: 1 });
+  if (catalogTimeoutSeconds !== undefined && catalogTimeoutSeconds > 120) {
+    throw new CliUsageError("--catalog-timeout must be an integer between 1 and 120", CONNECT_USAGE);
+  }
+  const noSync = takeFlag(args, "--no-sync");
+  if (!keyStdin || rawPort === undefined || !linkId) {
+    throw new CliUsageError("link connect requires --key-stdin, --tunnel-port, and --link-id", CONNECT_USAGE);
+  }
+  if (managementUrl || managementTransport !== undefined || pairing || admin || args.some(value => !value.startsWith("--"))) {
+    throw new CliUsageError("link connect accepts no hub URL, management URL, management transport, pairing code, or admin token", CONNECT_USAGE);
+  }
+  if (rawPort > 65535 || !/^lnk_[0-9a-f]{16}$/.test(linkId)) {
+    throw new CliUsageError("invalid link transport", CONNECT_USAGE);
+  }
+  rejectArgs(args, CONNECT_USAGE, { redactValues: true });
+  const credential = await readLinkCredential(deps);
+  const connection = await connectClient({
+    serverUrl: `http://127.0.0.1:${rawPort}`,
+    managementUrl: `http://127.0.0.1:${rawPort}`,
+    credential: { kind: "link", ...credential },
+    selectedClients: clients,
+    managementTransport: "direct",
+    transport: "link",
+    link: { tunnelPort: rawPort, linkId },
+    noSync,
+    ...(catalogTimeoutSeconds === undefined ? {} : { catalogTimeoutMs: catalogTimeoutSeconds * 1_000 }),
+  }, {
+    fetchImpl: deps.fetchImpl,
+    lifecycleLockDeps: deps.lifecycleLockDeps,
+    catalogCompatibility: catalogObserver(deps.catalogProbeDeps),
+  }).catch((error: unknown) => {
+    throw terminalSafeError(error);
+  });
+  const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {});
+  const report = connectCompletionReport(connection, clients, readiness);
+  for (const line of report.lines) console.log(line);
+  if (report.failure) throw new Error(report.failure);
+}
+
+async function runConnect(argv: string[], deps: ClientCommandDeps): Promise<void> {
+  const args = [...argv];
+  if (takeFlag(args, "--link")) {
+    await runLinkConnect(args, deps);
+    return;
+  }
+  await runHubConnect(argv, deps);
+}
+
 async function runRevoke(argv: string[], deps: ClientCommandDeps): Promise<void> {
   const args = [...argv];
   const wantsJson = takeFlag(args, "--json");
@@ -408,15 +508,33 @@ export async function handleConnectCommand(argv: string[], deps: ClientCommandDe
   });
 }
 
-export async function handleDisconnectCommand(argv: string[], deps: Pick<ClientCommandDeps, "lifecycleLockDeps"> = {}): Promise<number> {
+export async function handleDisconnectCommand(
+  argv: string[],
+  deps: Pick<ClientCommandDeps, "lifecycleLockDeps" | "linkTeardownDeps"> = {},
+): 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 teardown = await teardownClientLink({
+      readSidecar: readClientLinkState,
+      connectedLinkId: () => {
+        const state = readClientConnectionState();
+        return state.kind === "connected" && state.value.transport === "link"
+          ? state.value.link?.linkId ?? null
+          : null;
+      },
+      reapOrphanTunnel: deps.linkTeardownDeps?.reapOrphanTunnel ?? (() => reapOrphanTunnel()),
+      runner: deps.linkTeardownDeps?.runner ?? createSshRunner(),
+      knownHostsFile: deps.linkTeardownDeps?.knownHostsFile ?? linkKnownHostsPath(),
+      timeoutMs: deps.linkTeardownDeps?.timeoutMs,
+    });
     const result = await disconnectClient({ keepCatalog }, deps);
     const payload = {
       ...result,
+      homeRevoke: teardown.homeRevoke,
+      tunnel: teardown.tunnel,
       revoke: {
         apiKeyId: result.apiKeyId,
         location: "Integrations → API Keys",
@@ -427,7 +545,13 @@ export async function handleDisconnectCommand(argv: string[], deps: Pick<ClientC
       ...(result.desktopRestoration === "standard_fallback"
         ? ["Previous Desktop settings were not recorded; the managed profile was switched to standard mode."] : []),
       ...(result.restartRequired ? ["Fully quit and reopen Claude Desktop; local cleanup cannot revoke an in-memory credential."] : []),
-      `The hub key ${result.apiKeyId} is still valid. Revoke it from Integrations → API Keys.`,
+      ...(teardown.homeRevoke === "failed" && teardown.linkId
+        ? [`Home revoke failed; run ocx link revoke --link-id ${teardown.linkId} on the home.`] : []),
+      ...(teardown.tunnel?.tunnel === "unresolved"
+        ? [`A link tunnel (pid ${teardown.tunnel.pid}) may still be running; stop it if it is.`] : []),
+      teardown.homeRevoke === "revoked"
+        ? `The home revoked link ${teardown.linkId} and its key ${result.apiKeyId}.`
+        : `The hub key ${result.apiKeyId} is still valid. Revoke it from Integrations → API Keys.`,
     ]);
   });
 }

package/src/cli/dispatch.ts

@@ -539,6 +539,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleConnectCommand } = await import("./connect");
     return await handleConnectCommand(deps.args.slice(1));
   },
+  link: async deps => {
+    const { runLinkCommand } = await import("./link");
+    return await runLinkCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
+  },
   "remote-workspace": async deps => {
     const { runRemoteWorkspaceCommand } = await import("./remote-workspace");
     return await runRemoteWorkspaceCommand(deps.args.slice(1));
@@ -892,6 +896,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleAccessCommand } = await import("./access");
     return await handleAccessCommand(["key", ...deps.args.slice(1)]);
   },
+  api: async deps => {
+    const { handleApiCommand } = await import("./api-protocols");
+    return await handleApiCommand(deps.args.slice(1));
+  },
   export: async deps => {
     const { handleExportCommand } = await import("./export-command");
     return await handleExportCommand(deps.args.slice(1));

package/src/cli/doctor.ts

@@ -42,7 +42,9 @@ import {
 } from "../codex/coordinator-doctor";
 import {
   inspectAbandonedResponseStateTemps,
+  inspectResponseSpillStorage,
   reclaimAbandonedResponseStateTemps,
+  type ResponseSpillDirInspection,
   type ResponseStateTempRecoveryResult,
 } from "../responses/state";
 import {
@@ -861,6 +863,34 @@ export function formatResponseTempLines(
   return lines;
 }
 
+/**
+ * Render the response-state spill section (testable without console capture).
+ *
+ * Always dry-run: doctor reports what the disk looks like, it never unlinks
+ * spill files. "Owned" counts union the live store and the persisted snapshot,
+ * so a file a restart would re-own is never reported as garbage.
+ */
+export function formatResponseSpillLines(result: ResponseSpillDirInspection): string[] {
+  // A truncated scan saw only a prefix of the directory, so zero orphans there is
+  // not a clean bill of health: the unscanned tail may still hold them.
+  if (result.orphanFiles === 0 && result.truncated) {
+    return [
+      `  !!  No orphaned response-state spill files in the first ${result.scanned} entries (${result.files} file(s), ${mb(result.bytes)} scanned).`,
+      "      Scan stopped at its entry budget; the rest of the directory was not checked.",
+    ];
+  }
+  if (result.orphanFiles === 0) {
+    return [`  ok  No orphaned response-state spill files (${result.files} file(s), ${mb(result.bytes)} on disk).`];
+  }
+  const lines = [
+    `  !!  ${result.orphanFiles} unreferenced response-state spill file(s), ${mb(result.orphanBytes)} reclaimable.`,
+    `      ${result.ownedFiles} file(s), ${mb(result.ownedBytes)} still owned by the store or the persisted snapshot.`,
+    "      The running proxy reclaims orphans on its periodic sweep; do not delete spill files manually.",
+  ];
+  if (result.truncated) lines.push("      Scan stopped at its entry budget; the real total is higher.");
+  return lines;
+}
+
 export function formatCoordinatorDoctorLines(diagnostic: CodexCoordinatorDiagnostic): string[] {
   const pathLine = diagnostic.path ? [`       path: ${diagnostic.path}`] : [];
   const evidenceLines = "evidence" in diagnostic && diagnostic.evidence
@@ -1299,6 +1329,9 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     reclaimTemps,
   )) console.log(line);
 
+  console.log("\nResponse-state spill files");
+  for (const line of formatResponseSpillLines(inspectResponseSpillStorage())) console.log(line);
+
   const orcaHome = collectOrcaCodexHomeDiagnostic();
   console.log("\nCodex app home targeting");
   console.log(`  ${orcaHome.mismatch ? "!! " : "ok "} Effective Codex home: ${orcaHome.effectiveCodexHome}`);

package/src/cli/help.ts

@@ -57,6 +57,7 @@ Usage:
                               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 link <sub>              Machine links over SSH (port|issue|revoke|status)
   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)
@@ -81,6 +82,7 @@ Usage:
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
+  ocx api <sub>               Protocol paths: vocabulary, request-path preview, and policy
   ocx export --client <id>    Print a client config wired to the running proxy (15 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply

package/src/cli/link.ts

@@ -0,0 +1,288 @@
+import { assertSshAlias } from "../link/ssh-argv";
+import { linkStorePath } from "../link/paths";
+import { isLinkPort } from "../link/ports";
+import { readLinkStore, type LinkDirection, type LinkStore } from "../link/store";
+import { findAvailablePort } from "../server/ports";
+import {
+  CliUsageError,
+  RuntimeApiError,
+  rejectArgs,
+  runCliAction,
+  runtimeBaseUrl,
+  runtimeRequest,
+  takeIntegerOption,
+  takeJsonFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+export const LINK_USAGE = `Usage:
+  ocx link port [--json]
+  ocx link issue --alias <alias> --tunnel-port <port> [--json]
+  ocx link status [--json]
+  ocx link revoke --link-id <id> [--json]`;
+
+type LinkState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
+type ListenerState = "off" | "listening" | "failed";
+
+export interface LinkStatusPayload {
+  role: "standalone" | "home" | "child";
+  listener: { state: ListenerState; port: number | null };
+  links: Array<{
+    id: string;
+    alias: string;
+    direction: LinkDirection;
+    state: LinkState;
+    since: string;
+    reason: string | null;
+    tunnelPort: number;
+  }>;
+  child: null | {
+    alias: string;
+    state: LinkState;
+    since: string;
+    reason: string | null;
+  };
+}
+
+export interface LinkIssuePayload {
+  linkId: string;
+  apiKeyId: string;
+  key: string;
+  listenerPort: number;
+}
+
+export interface LinkCliDeps extends RuntimeApiDeps {
+  choosePort?: () => Promise<number>;
+  readStore?: () => LinkStore;
+  readAdminToken?: () => string | null;
+}
+
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+const API_KEY_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/;
+const DATA_KEY = /^ocx_data_[0-9a-f]{40}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertExactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
+  const expected = new Set(keys);
+  const actual = Object.keys(value);
+  if (actual.length !== expected.size || actual.some(key => !expected.has(key))) {
+    throw new Error(`invalid link API response: ${label} fields`);
+  }
+}
+
+function validListenerPort(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65535;
+}
+
+function validString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function validNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+function validateStatus(value: unknown): LinkStatusPayload {
+  if (!isRecord(value)) throw new Error("invalid link API response: status object");
+  assertExactKeys(value, ["role", "listener", "links", "child"], "status");
+  if (value.role !== "standalone" && value.role !== "home" && value.role !== "child") {
+    throw new Error("invalid link API response: status role");
+  }
+  if (!isRecord(value.listener)) throw new Error("invalid link API response: listener");
+  assertExactKeys(value.listener, ["state", "port"], "listener");
+  if (value.listener.state !== "off" && value.listener.state !== "listening" && value.listener.state !== "failed") {
+    throw new Error("invalid link API response: listener state");
+  }
+  if (value.listener.port !== null && !validListenerPort(value.listener.port)) {
+    throw new Error("invalid link API response: listener port");
+  }
+  if (!Array.isArray(value.links)) throw new Error("invalid link API response: links");
+  const links = value.links.map((candidate, index) => {
+    if (!isRecord(candidate)) throw new Error(`invalid link API response: link ${index}`);
+    assertExactKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], `link ${index}`);
+    if (typeof candidate.id !== "string" || !LINK_ID.test(candidate.id)
+      || !validString(candidate.alias) || (candidate.direction !== "hub-initiated" && candidate.direction !== "client-initiated")
+      || (candidate.state !== "connecting" && candidate.state !== "connected" && candidate.state !== "reconnecting" && candidate.state !== "failed" && candidate.state !== "idle")
+      || !validString(candidate.since) || !validNullableString(candidate.reason) || !isLinkPort(candidate.tunnelPort)) {
+      throw new Error(`invalid link API response: link ${index} fields`);
+    }
+    return {
+      id: candidate.id,
+      alias: candidate.alias,
+      direction: candidate.direction,
+      state: candidate.state,
+      since: candidate.since,
+      reason: candidate.reason,
+      tunnelPort: candidate.tunnelPort,
+    } as LinkStatusPayload["links"][number];
+  });
+  let child: LinkStatusPayload["child"] = null;
+  if (value.child !== null) {
+    if (!isRecord(value.child)) throw new Error("invalid link API response: child");
+    assertExactKeys(value.child, ["alias", "state", "since", "reason"], "child");
+    if (!validString(value.child.alias)
+      || (value.child.state !== "connecting" && value.child.state !== "connected" && value.child.state !== "reconnecting" && value.child.state !== "failed" && value.child.state !== "idle")
+      || !validString(value.child.since) || !validNullableString(value.child.reason)) {
+      throw new Error("invalid link API response: child fields");
+    }
+    child = {
+      alias: value.child.alias,
+      state: value.child.state,
+      since: value.child.since,
+      reason: value.child.reason,
+    };
+  }
+  return {
+    role: value.role,
+    listener: { state: value.listener.state, port: value.listener.port },
+    links,
+    child,
+  };
+}
+
+function validateIssue(value: unknown): LinkIssuePayload {
+  if (!isRecord(value)) throw new Error("invalid link API response: issue object");
+  assertExactKeys(value, ["linkId", "apiKeyId", "key", "listenerPort"], "issue");
+  if (typeof value.linkId !== "string" || !LINK_ID.test(value.linkId)
+    || typeof value.apiKeyId !== "string" || !API_KEY_ID.test(value.apiKeyId)
+    || typeof value.key !== "string" || !DATA_KEY.test(value.key)
+    || !validListenerPort(value.listenerPort)) {
+    throw new Error("invalid link API response: issue fields");
+  }
+  return {
+    linkId: value.linkId,
+    apiKeyId: value.apiKeyId,
+    key: value.key,
+    listenerPort: value.listenerPort,
+  };
+}
+
+function validateRevoke(value: unknown, expectedLinkId: string): void {
+  if (value === null) return;
+  if (!isRecord(value)) throw new Error("invalid link API response: revoke object");
+  assertExactKeys(value, ["linkId"], "revoke");
+  if (value.linkId !== expectedLinkId) throw new Error("invalid link API response: revoke link id");
+}
+
+function localStatus(store: LinkStore): LinkStatusPayload {
+  const hasLinks = store.links.length > 0;
+  return {
+    role: hasLinks ? "home" : "standalone",
+    listener: {
+      state: hasLinks && store.listenerPort !== null ? "listening" : "off",
+      port: hasLinks ? store.listenerPort : null,
+    },
+    links: store.links.map(link => ({
+      id: link.id,
+      alias: link.alias,
+      direction: link.direction,
+      state: "idle",
+      since: link.createdAt,
+      reason: null,
+      tunnelPort: link.tunnelPort,
+    })),
+    child: null,
+  };
+}
+
+async function linkRequest<T>(path: string, init: RequestInit, deps: LinkCliDeps): Promise<T> {
+  const hasTokenOverride = deps.readAdminToken !== undefined;
+  const token = deps.readAdminToken?.() ?? null;
+  const headers = new Headers(init.headers);
+  if (hasTokenOverride) headers.set("x-opencodex-api-key", token ?? "");
+  const requestInit: RequestInit = { ...init, headers };
+  try {
+    return await runtimeRequest<T>(path, requestInit, deps);
+  } catch (error) {
+    if (error instanceof RuntimeApiError) {
+      // Never echo an API error body: issue responses contain a one-time data key. Only the error
+      // code survives, because callers branch on it and a code is never secret.
+      throw new RuntimeApiError(`Link management request failed (${error.status})`, error.status, errorCodeBody(error.body));
+    }
+    throw error;
+  }
+}
+
+function errorCodeBody(body: unknown): { error: { code: string } } | null {
+  if (!isRecord(body) || !isRecord(body.error)) return null;
+  const code = body.error.code;
+  return typeof code === "string" && /^[a-z_]{1,64}$/.test(code) ? { error: { code } } : null;
+}
+
+async function runPort(args: string[], deps: LinkCliDeps): Promise<void> {
+  takeJsonFlag(args);
+  rejectArgs(args, LINK_USAGE);
+  const port = await (deps.choosePort ?? (() => findAvailablePort(0, "127.0.0.1")))();
+  if (!isLinkPort(port)) throw new Error("port allocator returned an invalid link port");
+  console.log(JSON.stringify({ port }));
+}
+
+async function runIssue(args: string[], deps: LinkCliDeps): Promise<void> {
+  takeJsonFlag(args);
+  const alias = takeOption(args, "--alias");
+  const tunnelPort = takeIntegerOption(args, "--tunnel-port", { min: 1024 });
+  if (!alias || tunnelPort === undefined || !isLinkPort(tunnelPort)) {
+    throw new CliUsageError("issue requires --alias and --tunnel-port", LINK_USAGE);
+  }
+  try { assertSshAlias(alias); }
+  catch { throw new CliUsageError("--alias must be a valid SSH host alias", LINK_USAGE); }
+  rejectArgs(args, LINK_USAGE);
+  const result = validateIssue(await linkRequest<unknown>("/api/link/issue", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ alias, tunnelPort }),
+  }, deps));
+  console.log(JSON.stringify(result));
+}
+
+async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
+  takeJsonFlag(args);
+  rejectArgs(args, LINK_USAGE);
+  let baseUrl: string;
+  try {
+    baseUrl = await runtimeBaseUrl(deps);
+  } catch (error) {
+    if (!deps.baseUrl && error instanceof RuntimeApiError && error.status === 503) {
+      const store = (deps.readStore ?? (() => readLinkStore(linkStorePath())))();
+      console.log(JSON.stringify(localStatus(store)));
+      return;
+    }
+    throw error;
+  }
+  const result = validateStatus(await linkRequest<unknown>("/api/link/status", {}, { ...deps, baseUrl }));
+  console.log(JSON.stringify(result));
+}
+
+async function runRevoke(args: string[], deps: LinkCliDeps): Promise<void> {
+  takeJsonFlag(args);
+  const linkId = takeOption(args, "--link-id");
+  if (!linkId || !LINK_ID.test(linkId)) throw new CliUsageError("revoke requires a valid --link-id", LINK_USAGE);
+  rejectArgs(args, LINK_USAGE);
+  try {
+    const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}`, { method: "DELETE" }, deps);
+    validateRevoke(response, linkId);
+  } catch (error) {
+    // Revoke is idempotent: a link the Home no longer has is already revoked, and a Child retrying
+    // a join rollback depends on that answer being success. A 404 without this code comes from a
+    // listener that does not serve the management API and stays a failure.
+    const code = error instanceof RuntimeApiError && error.status === 404 ? errorCodeBody(error.body)?.error.code : undefined;
+    if (code !== "link_not_found") throw error;
+  }
+  console.log(JSON.stringify({ linkId }));
+}
+
+export async function runLinkCommand(rawArgs: string[], deps: LinkCliDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...rawArgs];
+    const command = args.shift();
+    if (command === "port") await runPort(args, deps);
+    else if (command === "issue") await runIssue(args, deps);
+    else if (command === "status") await runStatus(args, deps);
+    else if (command === "revoke") await runRevoke(args, deps);
+    else throw new CliUsageError("link requires one of: port, issue, status, revoke", LINK_USAGE);
+  });
+}

package/src/cli/registry.ts

@@ -130,6 +130,18 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Credentials are accepted only through stdin; argv and environment credential forms are not supported.",
     ],
   },
+  {
+    name: "link",
+    usage: "ocx link <port|issue|status|revoke>",
+    summary: "Allocate and manage a loopback remote home link.",
+    details: [
+      "Port: ocx link port [--json]",
+      "Issue: ocx link issue --alias <alias> --tunnel-port <port> [--json]",
+      "Status: ocx link status [--json]",
+      "Revoke: ocx link revoke --link-id <id> [--json]",
+      "Issue, status, and revoke use the running proxy's loopback management API and admin token.",
+    ],
+  },
   {
     name: "remote-workspace",
     usage: "ocx remote-workspace <pair|agent|status>",
@@ -391,6 +403,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     ],
   },
   { name: "api-key", usage: "ocx api-key <list|create|rotate|remove> ...", summary: "Alias of ocx access key." },
+  {
+    name: "api",
+    usage: "ocx api <protocols|explain|policy> ...",
+    summary: "Inspect protocol paths, preview a request path, and read or change the protocol policy.",
+    details: [
+      "protocols [--provider <name>]   Contract version, API surfaces, protocol settings and feature vocabulary.",
+      "explain --model <id> --inbound <responses|chat|messages> [--feature <key>]...   Preview the request path; sends nothing upstream.",
+      "policy                          Read the protocol policy; with --messages, --unrepresentable or --rollout <switch>=<on|off> it changes config.",
+      "Every rollout switch defaults off. `ocx api policy` writes only when a setting flag is given.",
+    ],
+  },
   {
     name: "export",
     usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside|raycast|omo|cline> [--json] [--out <path>] [--force]",