@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/cli/integration-plan-dto.ts

@@ -26,6 +26,7 @@ export const FILE_INTEGRATION_CLIENTS = [
   "commandcode",
   "kilo",
   "droid",
+  "qoder",
 ] as const;
 
 export const INTEGRATION_REFUSAL_REASONS: ReadonlySet<string> = new Set<IntegrationRefusalReason>([
@@ -65,6 +66,7 @@ const PLAN_SCHEMA_PATHS = new Set([
   "settings.providers.opencodex",
   "catalog.providers.opencodex",
   "customModels.*",
+  "modelConfigs.customModels.*",
   // ZCode reads its providers from a second file; a plan for it publishes that
   // file's templates, and a path missing here is rejected as an invalid preview.
   "config.providerConfigRules.providerRules.[providerId=opencodex]",

package/src/cli/link-child.ts

@@ -0,0 +1,104 @@
+/**
+ * Management commands on a Remote Link Child (#6957).
+ *
+ * A link Child's listener serves no management API, and the Home owns every setting that decides
+ * routing. Each management command therefore does one of two things: an allowlisted read goes
+ * to the Home through the connection-bound link relay, and anything else is refused with the one
+ * message `linkChildManagementRefusal` builds, which names the Home and the link.
+ */
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { readServiceApiTokenState } from "../lib/service-secrets";
+import { linkChildManagementRefusal, linkManagementReadAllowed } from "../link/management-routes";
+import { readClientConnectionState } from "../client/state";
+import { fetchLinkHomeManagement, linkHomePhrase, type LinkHomeDeps } from "../client/link-home";
+import type { OcxClientConnectionConfig } from "../types";
+
+const RESPONSE_MAX_BYTES = 32 * 1024 * 1024;
+
+export interface LinkChildContext {
+  connection: OcxClientConnectionConfig;
+  linkId: string;
+  homePhrase: string;
+}
+
+/** The link Child this CLI runs on, or null on a standalone, a hub or a hub client. */
+export function readLinkChildContext(read: typeof readClientConnectionState = readClientConnectionState): LinkChildContext | null {
+  let state: ReturnType<typeof readClientConnectionState>;
+  try { state = read(); } catch { return null; }
+  if (state.kind !== "connected" || state.value.transport !== "link" || !state.value.link) return null;
+  return { connection: state.value, linkId: state.value.link.linkId, homePhrase: linkHomePhrase(state.value) };
+}
+
+export function linkChildRefusal(context: LinkChildContext, operation?: string): string {
+  return linkChildManagementRefusal(context.homePhrase, context.linkId, operation);
+}
+
+/**
+ * The stderr label for a local read on a link Child (`ocx provider list`, `ocx config get`):
+ * the values are real, but they are this machine's and the Home's apply.
+ */
+export function linkChildLocalNotice(what: string): string | null {
+  const link = readLinkChildContext();
+  if (!link) return null;
+  return `Note: this machine is a Remote Link Child managed by ${link.homePhrase} (link ${link.linkId}). `
+    + `${what} below are this machine's local configuration. Its provider, model and routing settings are inactive while it is linked; the Home's apply. Run 'ocx status' for the Home's state.`;
+}
+
+export async function printLinkChildLocalNotice(what: string): Promise<void> {
+  const notice = linkChildLocalNotice(what);
+  if (notice) console.error(notice);
+}
+
+/** `ocx config set|unset|import` on a link Child: the write is local and its routing parts inactive. */
+export async function printLinkChildLocalWriteNotice(): Promise<void> {
+  const link = readLinkChildContext();
+  if (!link) return;
+  console.error(`Note: this machine is a Remote Link Child managed by ${link.homePhrase} (link ${link.linkId}). `
+    + "This writes this machine's local configuration; its provider, model and routing settings stay inactive while it is linked, and the Home's apply.");
+}
+
+/** The refusal for a local provider change on a link Child, or null elsewhere. */
+export function linkChildProviderChangeRefusal(operation: string): string | null {
+  const link = readLinkChildContext();
+  return link ? linkChildRefusal(link, operation) : null;
+}
+
+/** Can this management request be answered by reading the Home? */
+export function linkChildReadable(method: string, path: string): boolean {
+  const url = new URL(path.startsWith("/") ? path : `/${path}`, "http://cli.invalid");
+  return linkManagementReadAllowed(method, url.pathname, url.searchParams);
+}
+
+/** One allowlisted read from the Home. Throws with an operator sentence when it cannot be sent. */
+export async function readLinkHomeJson(
+  context: LinkChildContext,
+  path: string,
+  deps: LinkHomeDeps = {},
+): Promise<{ status: number; body: unknown }> {
+  const token = readServiceApiTokenState();
+  if (token.kind !== "present" || token.fingerprint !== context.connection.tokenFingerprint) {
+    throw new Error(`The enrolled link key for ${context.homePhrase} is missing or changed; re-link this machine from the Home.`);
+  }
+  let response: Response;
+  try {
+    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`, {}, deps);
+  } catch (error) {
+    const detail = error instanceof Error && error.name === "LinkRelayAuthenticationError" ? error.message : "the link tunnel did not answer";
+    throw new Error(`Could not read ${context.homePhrase} over Remote Link (${context.linkId}): ${detail}.`);
+  }
+  const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_MAX_BYTES, signal: AbortSignal.timeout(30_000) });
+  if (result.oversized) throw new Error(`${context.homePhrase} returned a response larger than the CLI accepts.`);
+  const text = new TextDecoder().decode(result.bytes);
+  let body: unknown = null;
+  if (text) {
+    try { body = JSON.parse(text); } catch { body = text; }
+  }
+  // A Home that predates the relay answers its listener's generic unknown-endpoint 404.
+  const error = body && typeof body === "object" ? (body as Record<string, unknown>).error : undefined;
+  const unknownEndpoint = error === "not_found"
+    || (!!error && typeof error === "object" && (error as Record<string, unknown>).code === "not_found");
+  if (response.status === 404 && unknownEndpoint) {
+    return { status: 503, body: { error: `${context.homePhrase} does not serve Remote Link management reads; upgrade the Home.` } };
+  }
+  return { status: response.status, body };
+}

package/src/cli/link-enrollment.ts

@@ -0,0 +1,96 @@
+import { createInterface } from "node:readline/promises";
+import { assertSshAlias } from "../link/ssh-argv";
+import { CliUsageError, RuntimeApiError, runtimeBaseUrl, rejectArgs, takeJsonFlag, takeOption, printData } from "./runtime-api";
+import type { LinkCliDeps } from "./link";
+
+const FINGERPRINT = /^SHA256:[A-Za-z0-9+/]{16,88}={0,2}$/;
+const ENROLLMENT_DEADLINE_MS = 360_000;
+const PHASES: Record<string, string> = {
+  remote_port_failed: "remote port selection", remote_port_timeout: "remote port selection",
+  child_preflight_failed: "Child preflight", child_preflight_timeout: "Child preflight",
+  child_restart_unsupported: "Child restart preflight", child_curl_missing: "Child curl preflight",
+  home_setup_failed: "Home setup", home_setup_timeout: "Home setup",
+  remote_connect_failed: "Child enrollment", remote_connect_timeout: "Child enrollment",
+  child_restart_failed: "Child restart", child_restart_timeout: "Child restart",
+  child_relay_failed: "Child relay verification", child_relay_timeout: "Child relay verification",
+  child_runtime_not_client: "Child runtime role verification",
+  remote_platform_unsupported: "remote platform verification", remote_ocx_missing: "remote OpenCodex discovery",
+};
+const RECOVERY = "Run ocx disconnect and ocx restart on the Child before retrying.";
+type LinkRequest = <T>(path: string, init: RequestInit, deps: LinkCliDeps) => Promise<T>;
+
+function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function offered(value: unknown): { alias: string; fingerprint: string; keyType: string; ocxVersion: string } {
+  if (!record(value) || Object.keys(value).sort().join(",") !== "alias,fingerprint,keyType,ocxVersion"
+    || typeof value.alias !== "string" || typeof value.fingerprint !== "string" || !FINGERPRINT.test(value.fingerprint)
+    || typeof value.keyType !== "string" || !/^[A-Za-z0-9@._+-]{1,64}$/.test(value.keyType)) throw new Error("Invalid host probe response");
+  if (typeof value.ocxVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/.test(value.ocxVersion)) throw new Error("Invalid host version response");
+  return { alias: value.alias, fingerprint: value.fingerprint, keyType: value.keyType, ocxVersion: value.ocxVersion };
+}
+
+export async function runLinkEnrollment(command: "probe" | "add", args: string[], deps: LinkCliDeps, request: LinkRequest, usage: string): Promise<void> {
+  const wantsJson = takeJsonFlag(args);
+  const expected = takeOption(args, "--expect-fingerprint");
+  const alias = args.shift();
+  if (!alias) throw new CliUsageError(command + " requires an SSH alias", usage);
+  try { assertSshAlias(alias); } catch { throw new CliUsageError("Invalid SSH alias", usage); }
+  rejectArgs(args, usage);
+  if (command === "probe" && expected !== undefined) throw new CliUsageError("--expect-fingerprint is only for link add", usage);
+  if (expected !== undefined && !FINGERPRINT.test(expected)) throw new CliUsageError("Expected a SHA256 SSH fingerprint", usage);
+  if (command === "add" && !expected && !(deps.stdinImpl ?? process.stdin).isTTY) {
+    throw new CliUsageError("Non-interactive link add requires --expect-fingerprint", usage);
+  }
+  const timeout = deps.enrollmentTimeoutMs ?? ENROLLMENT_DEADLINE_MS;
+  if (!Number.isFinite(timeout) || timeout < 1 || timeout > ENROLLMENT_DEADLINE_MS) throw new Error("Invalid link enrollment deadline");
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expiry = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => { controller.abort(); reject(new Error("Link enrollment timed out; its outcome is uncertain. Run ocx link status on the Home and ocx connect status on the Child before retrying.")); }, timeout);
+  });
+  let boundDeps = deps;
+  const post = async <T>(path: string, body: unknown): Promise<T> => {
+    controller.signal.throwIfAborted();
+    const result = await request<T>(path, { method: "POST", redirect: "error", signal: controller.signal, headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, boundDeps);
+    controller.signal.throwIfAborted();
+    return result;
+  };
+  let rl: ReturnType<typeof createInterface> | undefined;
+  const work = async () => {
+    boundDeps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+    controller.signal.throwIfAborted();
+    const probe = offered(await post<unknown>("/api/link/probe", { alias, includeVersion: true }));
+    if (probe.alias !== alias) throw new Error("Host probe alias did not match");
+    if (command === "probe") { printData(probe, wantsJson, [probe.alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion]); return; }
+    if (expected && expected !== probe.fingerprint) throw new CliUsageError("The offered host fingerprint does not match --expect-fingerprint");
+    if (!expected) {
+      let approved: boolean;
+      if (deps.confirmFingerprint) approved = await deps.confirmFingerprint(probe);
+      else {
+        rl = createInterface({ input: deps.stdinImpl ?? process.stdin, output: process.stderr });
+        approved = (await rl.question("Confirm " + alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion + " (type yes): ", { signal: controller.signal })).trim() === "yes";
+      }
+      controller.signal.throwIfAborted();
+      if (!approved) throw new CliUsageError("Host fingerprint was not confirmed");
+    }
+    const confirm = await post<unknown>("/api/link/confirm-host", { alias, fingerprint: probe.fingerprint });
+    if (!record(confirm) || Object.keys(confirm).sort().join(",") !== "alias,fingerprint,ocxVersion" || confirm.alias !== alias || confirm.fingerprint !== probe.fingerprint
+      || typeof confirm.ocxVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/.test(confirm.ocxVersion)) throw new Error("Invalid host confirmation response");
+    const result = await post<unknown>("/api/link/apply", { alias, fingerprint: probe.fingerprint });
+    if (!record(result) || Object.keys(result).join(",") !== "linkId" || typeof result.linkId !== "string" || !/^lnk_[0-9a-f]{16}$/.test(result.linkId)) throw new Error("Invalid link apply response");
+    printData({ linkId: result.linkId, alias, state: "connected", childRole: "client" }, wantsJson, ["Connected " + alias + " as a Child (" + result.linkId + ")."]);
+  };
+  try { await Promise.race([work(), expiry]); }
+  catch (error) {
+    if (error instanceof RuntimeApiError && record(error.body)) {
+      const code = record(error.body.error) ? error.body.error.code : undefined;
+      const phase = typeof code === "string" && Object.hasOwn(PHASES, code) ? PHASES[code] : undefined;
+      const message = phase ? "Remote Link failed during " + phase : error.message;
+      if (phase || error.body.residual === true) throw new Error(message + (error.body.residual === true ? ". " + RECOVERY : ""));
+    }
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+    controller.abort();
+    rl?.close();
+  }
+}

package/src/cli/link.ts

@@ -1,3 +1,8 @@
+import { clientLinkStatusIdentity } from "../client/link-status";
+import { clientLinkTunnelStatus } from "../client/link-tunnel";
+import { loadConfig } from "../config";
+import { projectLinkStatus, type ClientLinkIdentity, type LinkStatusConfig, type LinkStatusDto } from "../link/status-projection";
+import { runLinkEnrollment } from "./link-enrollment";
 import { assertSshAlias } from "../link/ssh-argv";
 import { linkStorePath } from "../link/paths";
 import { isLinkPort } from "../link/ports";
@@ -19,10 +24,13 @@ import {
 } from "./runtime-api";
 
 export const LINK_USAGE = `Usage:
+  ocx link probe <alias> [--json]
+  ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]
   ocx link port [--json]
   ocx link issue --alias <alias> --tunnel-port <port> [--json]
   ocx link status [--json]
   ocx link revoke --link-id <id> [--force --yes] [--json]
+  ocx link reconnect --link-id <id> [--json]
 
 Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.`;
 
@@ -57,7 +65,13 @@ export interface LinkIssuePayload {
 }
 
 export interface LinkCliDeps extends RuntimeApiDeps {
+  /** Test seam can shorten, never extend, the whole enrollment deadline. */
+  enrollmentTimeoutMs?: number;
   choosePort?: () => Promise<number>;
+  readConfig?: () => LinkStatusConfig;
+  readClientLinkIdentity?: (linkId: string) => ClientLinkIdentity | null;
+  readChildStatus?: () => LinkStatusDto["child"];
+  confirmFingerprint?: (host: { alias: string; fingerprint: string; keyType: string }) => Promise<boolean>;
   readStore?: () => LinkStore;
   readAdminToken?: () => string | null;
 }
@@ -172,25 +186,12 @@ function validateRevoke(value: unknown, expectedLinkId: string): void {
   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,
-  };
+function localStatus(store: LinkStore, deps: LinkCliDeps): LinkStatusPayload {
+  const config = (deps.readConfig ?? loadConfig)();
+  const identity = config.client?.transport === "link" && config.client.link
+    ? (deps.readClientLinkIdentity ?? clientLinkStatusIdentity)(config.client.link.linkId) : null;
+  return projectLinkStatus(store, [], { state: store.links.length > 0 && store.listenerPort !== null ? "listening" : "off", port: store.links.length > 0 ? store.listenerPort : null },
+    config, { version: 1, entries: {} }, (deps.readChildStatus ?? clientLinkTunnelStatus)(), identity);
 }
 
 async function linkRequest<T>(path: string, init: RequestInit, deps: LinkCliDeps): Promise<T> {
@@ -211,10 +212,10 @@ async function linkRequest<T>(path: string, init: RequestInit, deps: LinkCliDeps
   }
 }
 
-function errorCodeBody(body: unknown): { error: { code: string } } | null {
+function errorCodeBody(body: unknown): { error: { code: string }; residual?: true } | 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;
+  return typeof code === "string" && /^[a-z_]{1,64}$/.test(code) ? { error: { code }, ...(body.residual === true ? { residual: true as const } : {}) } : null;
 }
 
 async function runPort(args: string[], deps: LinkCliDeps): Promise<void> {
@@ -252,7 +253,7 @@ async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
   } catch (error) {
     if (!deps.baseUrl && error instanceof RuntimeApiError && error.status === 503) {
       const store = (deps.readStore ?? (() => readLinkStore(linkStorePath())))();
-      console.log(JSON.stringify(localStatus(store)));
+      console.log(JSON.stringify(localStatus(store, deps)));
       return;
     }
     throw error;
@@ -303,14 +304,28 @@ async function runRevoke(args: string[], deps: LinkCliDeps): Promise<void> {
   console.log(JSON.stringify({ linkId }));
 }
 
+async function runReconnect(args: string[], deps: LinkCliDeps): Promise<void> {
+  takeJsonFlag(args);
+  const linkId = takeOption(args, "--link-id");
+  if (!linkId || !LINK_ID.test(linkId)) throw new CliUsageError("reconnect requires a valid --link-id", LINK_USAGE);
+  rejectArgs(args, LINK_USAGE);
+  const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}/reconnect`, { method: "POST" }, deps);
+  if (!isRecord(response)) throw new Error("invalid link API response: reconnect object");
+  assertExactKeys(response, ["linkId"], "reconnect");
+  if (response.linkId !== linkId) throw new Error("invalid link API response: reconnect link id");
+  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);
+    if (command === "probe" || command === "add") await runLinkEnrollment(command, args, deps, linkRequest, LINK_USAGE);
+    else 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);
+    else if (command === "reconnect") await runReconnect(args, deps);
+    else throw new CliUsageError("link requires one of: probe, add, port, issue, status, revoke, reconnect", LINK_USAGE);
   });
 }

package/src/cli/observe-stream.ts

@@ -89,7 +89,12 @@ export async function withObserveStream(
       // Snapshot recovery comes from our observed target, never arbitrary transport text.
       if (context.kind === "snapshot") {
         if (!found) throw new ObservationError("Proxy is not running. Start it with: ocx start");
-        if (found.role === "client") throw new ObservationError("This listener runs in the client role and has no management API. Run this command on its serving hub, or open the hub dashboard.");
+        if (found.role === "client") {
+          const { readLinkChildContext, linkChildRefusal } = await import("./link-child");
+          const link = readLinkChildContext();
+          throw new ObservationError(link ? linkChildRefusal(link)
+            : "This listener runs in the client role and has no management API. Run this command on its serving hub, or open the hub dashboard.");
+        }
       }
       return found;
     } }), signal);

package/src/cli/observe.ts

@@ -113,8 +113,12 @@ async function logs(argv: string[], deps: ObserveStreamDeps): Promise<number> {
     return followLogs({ query: new URLSearchParams(query(params)), limit, jsonl: wantsJsonl, events: wantsEvents, formatRow: formatLog }, deps);
   }
   const data = await runtimeRequest(`/api/logs${query(params)}`, {}, deps);
+  const rows = logRows(data);
+  if (!wantsJson && !wantsJsonl && rows.length === 0 && [provider, model, status, conversationId, account].some(Boolean)) {
+    console.log("No log entry matched the filters.");
+  }
   if (wantsJson) printData(data, true);
-  else for (const row of logRows(data)) {
+  else for (const row of rows) {
     if (wantsJsonl) console.log(JSON.stringify(row));
     else console.log(formatLog(row));
   }
@@ -206,8 +210,12 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     if (token.kind !== "present" || token.fingerprint !== connection.value.tokenFingerprint) {
       throw new Error("Client usage unavailable: the enrolled data key is missing or changed; repair the client connection");
     }
+    // A Remote Link Child sends this read through the connection-bound link relay (#6957).
+    const link = connection.value.transport === "link" && connection.value.link;
+    const peerFetch = deps.fetchImpl
+      ?? (link ? (await import("../client/link-home")).linkBoundFetch(connection.value, token.token) : undefined);
     result = await fetchHubUsage(connection.value.serverUrl, token.token, new URLSearchParams(suffix), {
-      fetchImpl: deps.fetchImpl, timeoutMs: 60_000,
+      fetchImpl: peerFetch, timeoutMs: 60_000, ...(link ? { peer: "Home" as const } : {}),
     });
     const current = readClientConnectionState();
     const currentToken = readServiceApiTokenState();

package/src/cli/provider.ts

@@ -584,8 +584,19 @@ export async function handleProviderCommand(args: string[], deps: ProviderComman
     return;
   }
 
+  // #6957: a link Child's local providers are inactive; changing them is refused like any other
+  // provider change, which belongs to the Home.
+  if (sub === "add" || sub === "remove" || sub === "set-default") {
+    const refusal = (await import("./link-child")).linkChildProviderChangeRefusal(`ocx provider ${sub}`);
+    if (refusal) {
+      console.error(refusal);
+      process.exitCode = 1;
+      return;
+    }
+  }
   switch (sub) {
     case "list":
+      await (await import("./link-child")).printLinkChildLocalNotice("The providers");
       handleList(subArgs);
       break;
     case "add":
@@ -595,6 +606,7 @@ export async function handleProviderCommand(args: string[], deps: ProviderComman
       handleRemove(subArgs);
       break;
     case "show":
+      await (await import("./link-child")).printLinkChildLocalNotice("The provider settings");
       handleShow(subArgs);
       break;
     case "set-default":

package/src/cli/registry.ts

@@ -144,14 +144,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "link",
-    usage: "ocx link <port|issue|status|revoke>",
+    usage: "ocx link <port|issue|status|revoke|reconnect>",
     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> [--force --yes] [--json]",
-      "Issue, status, and revoke use the running proxy's loopback management API and admin token.",
+      "Reconnect: ocx link reconnect --link-id <id> [--json]",
+      "Issue, status, revoke, and reconnect use the running proxy's loopback management API and admin token.",
     ],
   },
   {
@@ -245,8 +246,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "hub",
-    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]",
-    summary: "Hub-side commands. `invite` prints a ready-to-run `ocx connect` line for one more machine.",
+    usage: "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]\n  ocx hub disable [--revoke-clients --client-key <id> ...] [--json]",
+    summary: "Invite another machine, or disable hub mode in one validated config write.",
     details: [
       "Topology: a hub serves ONE port. Remote machines dial `hostname:port` with their own per-client",
       "key; the hub's own local processes dial `127.0.0.1:<same port>` with no credential, through the",
@@ -377,6 +378,18 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx model <subcommand>",
     summary: "Alias of ocx models.",
   },
+  {
+    name: "advisor",
+    usage: "ocx advisor <status|on|off|consent|set> ...",
+    summary: "Inspect and configure the advisor sidecar (expert consultation for routed workers).",
+    details: [
+      "ocx advisor and ocx advisor status read the resolved settings; use --json for machine-readable output.",
+      "ocx advisor on requires current context-sharing consent. Pass --ack-context-sharing to record consent v1 and enable. ocx advisor off disables the sidecar without granting consent.",
+      "ocx advisor consent records consent v1 after printing the disclosure. ocx advisor consent --revoke removes it and stops task-context transfer.",
+      "ocx advisor set updates --model, --effort, --policy and --timeout-ms; the model may be any routable model string (bare native, provider/model, or account-qualified). set does not grant consent.",
+      "policy manual consults only when the worker calls the synthetic advisor tool; policy preflight also attempts one automatic consultation per task with a stable conversation identity, once the task shows orientation evidence. Without a stable identity, each eligible request may trigger another consultation. Both require current consent before any task context is sent.",
+    ],
+  },
   {
     name: "companion",
     usage: "ocx companion <show|set|reset|usage|timeline> ...",
@@ -468,13 +481,13 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "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.",
+      "Every rollout switch defaults off except antigravityDirect. `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|commandcode|prime|aside|raycast|omo|cline|kilo|droid> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid) wired to the running proxy.",
+    usage: "ocx export --client <qoder|opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|commandcode|prime|aside|raycast|omo|cline|kilo|droid> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid, Qoder) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",

package/src/cli/restart-scope.ts

@@ -173,6 +173,9 @@ export async function handleDesktopAppRestart(
         + "Quit and relaunch the desktop app manually to refresh the model picker.",
       );
       return result;
+    case "relaunch_context_failed":
+      log.error("Codex desktop launch options could not be preserved safely, so the app was not stopped. Review its current launch options before retrying.");
+      return result;
     case "no_targets":
       log.log("Codex desktop app is not running; nothing to restart.");
       return result;
@@ -189,4 +192,3 @@ export async function handleDesktopAppRestart(
       return result;
   }
 }
-

package/src/cli/runtime-api.ts

@@ -12,6 +12,7 @@
 import { findLiveProxy, probeHostname, type LivenessIo, type LiveProxy } from "../server/proxy-liveness";
 import { runningProxyUpdateHeaders } from "../oauth/login-cli";
 import { redactSecretArgs } from "./secret-args";
+import type { LinkHomeDeps } from "../client/link-home";
 export { redactSecretArgs };
 
 export type CliStdin = NodeJS.ReadableStream & { isTTY?: boolean; readableEnded?: boolean };
@@ -28,6 +29,8 @@ export interface RuntimeApiDeps {
   stdinSignal?: AbortSignal;
   /** Optional proxy liveness probe injection for commands that check or fall back around live runtime state. */
   findLiveProxy?: (io?: LivenessIo) => Promise<LiveProxy | null>;
+  /** Remote Link Child: how allowlisted reads reach the Home (#6957). */
+  linkHome?: LinkHomeDeps;
 }
 
 export class CliUsageError extends Error {
@@ -45,7 +48,7 @@ export class RuntimeApiError extends Error {
     readonly status: number,
     readonly body: unknown,
     /** Local discovery refusals occur before the management request is sent. */
-    readonly code?: "proxy_not_running" | "client_role_management_unavailable",
+    readonly code?: "proxy_not_running" | "client_role_management_unavailable" | "link_child_management_unavailable",
   ) {
     super(message);
     this.name = "RuntimeApiError";
@@ -83,6 +86,10 @@ export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string>
   // this costs no extra request. Only the client role is refused: an absent role is a
   // standalone or hub proxy (or a legacy body that predates the field), and both serve /api/*.
   if (live.role === "client") {
+    // A Remote Link Child has no relay transport to point at; it names its Home instead (#6957).
+    const { readLinkChildContext, linkChildRefusal } = await import("./link-child");
+    const link = readLinkChildContext();
+    if (link) throw new RuntimeApiError(linkChildRefusal(link), 503, null, "link_child_management_unavailable");
     throw new RuntimeApiError(clientRoleManagementRefusal(live.port), 503, null, "client_role_management_unavailable");
   }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
@@ -180,7 +187,25 @@ export async function runtimeRequest<T = unknown>(
   init: RequestInit = {},
   deps: RuntimeApiDeps = {},
 ): Promise<T> {
-  const baseUrl = await runtimeBaseUrl(deps);
+  let baseUrl: string;
+  try {
+    baseUrl = await runtimeBaseUrl(deps);
+  } catch (error) {
+    if (!(error instanceof RuntimeApiError) || error.code !== "link_child_management_unavailable") throw error;
+    // #6957: on a Remote Link Child an allowlisted read is answered by the Home over the link;
+    // every other request is refused with the operation named, before anything is sent.
+    const method = (init.method ?? "GET").toUpperCase();
+    const { readLinkChildContext, linkChildReadable, linkChildRefusal, readLinkHomeJson } = await import("./link-child");
+    const link = readLinkChildContext();
+    if (!link) throw error;
+    const pathname = new URL(path.startsWith("/") ? path : `/${path}`, "http://cli.invalid").pathname;
+    if (!linkChildReadable(method, path)) {
+      throw new RuntimeApiError(linkChildRefusal(link, `${method} ${pathname}`), 503, null, "link_child_management_unavailable");
+    }
+    const { status, body } = await readLinkHomeJson(link, path, deps.linkHome);
+    if (status < 200 || status >= 300) throw new RuntimeApiError(responseMessage(body, status), status, body);
+    return body as T;
+  }
   const headers = runningProxyUpdateHeaders();
   for (const [key, value] of new Headers(init.headers).entries()) headers.set(key, value);
   const fetchImpl = deps.fetchImpl ?? fetch;