@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/claude/outbound.ts

@@ -11,7 +11,7 @@
  *  - errors: {type:"error", error:{type,message}}; may arrive mid-stream after HTTP 200.
  */
 import { createHash } from "node:crypto";
-import { httpStatusFromTerminalError } from "../lib/errors";
+import { httpStatusFromTerminalError, UNDECLARED_TOOL_CALL_ERROR_CODE } from "../lib/errors";
 import { isTransientUpstreamStatus } from "../lib/upstream-retry";
 import {
   isTranslatorBudgetExceededError,
@@ -81,12 +81,16 @@ export function anthropicErrorType(status: number): string {
  * (devlog/_plan/261009_claude_1m_default/010).
  */
 const CLAUDE_PROMPT_TOO_LONG_RE = /prompt is too long|input is too long for requested model/i;
-const STATED_CONTEXT_COUNTS_RE = /maximum context length is (\d+) tokens[\s\S]*?(?:resulted in|you requested) (\d+) tokens/i;
+const MAX_OVERFLOW_MESSAGE_CHARS = 64 * 1024;
+const STATED_CONTEXT_LIMIT_RE = /maximum context length is (\d+) tokens/i;
+const STATED_REQUEST_COUNT_RE = /(?:resulted in|you requested) (\d+) tokens/i;
 
 export function claudePromptTooLongMessage(message: string): string {
+  message = message.slice(0, MAX_OVERFLOW_MESSAGE_CHARS);
   if (CLAUDE_PROMPT_TOO_LONG_RE.test(message)) return message;
-  const counts = STATED_CONTEXT_COUNTS_RE.exec(message);
-  if (counts) return `prompt is too long: ${counts[2]} tokens > ${counts[1]} maximum`;
+  const limit = STATED_CONTEXT_LIMIT_RE.exec(message);
+  const requested = limit && STATED_REQUEST_COUNT_RE.exec(message.slice(limit.index + limit[0].length));
+  if (limit && requested) return `prompt is too long: ${requested[1]} tokens > ${limit[1]} maximum`;
   return `prompt is too long: ${message}`;
 }
 
@@ -804,11 +808,14 @@ export function responsesSseToAnthropicSse(
             // Unclassified status-absent response.failed (relaySseWithFailedTail synthetic
             // tail) still lands on a transient 5xx here — the mid-stream reset shape maps to
             // overloaded_error by design.
+            // The undeclared-tool refusal is deterministic and proxy-owned, not an upstream
+            // condition: keep its api_error type and code instead of a retryable overload.
+            const deterministic = code === UNDECLARED_TOOL_CALL_ERROR_CODE;
             fail(
               status,
               message,
-              true,
-              code === "context_length_exceeded" ? code : undefined,
+              !deterministic,
+              deterministic || code === "context_length_exceeded" ? code : undefined,
             );
             break;
           }

package/src/cli/account-api.ts

@@ -137,6 +137,7 @@ export async function apiJson(
   body?: unknown,
   options: { signal?: AbortSignal; redirect?: RequestRedirect } = {},
 ): Promise<ApiResult> {
+  if (baseUrl === LINK_HOME_BASE) return linkHomeApiJson(deps, method, path);
   const fetchImpl = deps.fetchImpl ?? fetch;
   try {
     const res = await fetchImpl(`${baseUrl}${path}`, {
@@ -163,9 +164,73 @@ export async function resolveBaseUrl(deps: AccountDeps): Promise<string | null>
   if (deps.baseUrl) return deps.baseUrl;
   const live = await findLiveProxy();
   if (!live) return null;
+  if (live.role === "client") {
+    const { readLinkChildContext } = await import("./link-child");
+    if (readLinkChildContext()) return LINK_HOME_BASE;
+  }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
+/**
+ * Remote Link Child (#6957): account reads come from the Home over the link, and every account
+ * change is refused with the Child refusal. The marker is never a URL and never reaches fetch.
+ */
+export const LINK_HOME_BASE = "ocx-link-home:";
+
+async function linkHomeApiJson(deps: AccountDeps, method: string, path: string): Promise<ApiResult> {
+  const { readLinkChildContext, linkChildReadable, linkChildRefusal, readLinkHomeJson } = await import("./link-child");
+  const link = readLinkChildContext();
+  if (!link) return { status: 503, json: { error: "The Remote Link connection changed while the command ran; retry." } };
+  const pathname = new URL(path, "http://cli.invalid").pathname;
+  if (!linkChildReadable(method, path)) {
+    return { status: 403, json: { error: linkChildRefusal(link, `${method} ${pathname}`) } };
+  }
+  try {
+    const { status, body } = await readLinkHomeJson(link, path, deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {});
+    return { status, json: (body && typeof body === "object" ? body : { error: String(body ?? "") }) as Record<string, unknown> };
+  } catch (error) {
+    return { status: 503, json: { error: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+/**
+ * The config account commands classify providers against. On a Remote Link Child the local
+ * providers are inactive, so the Home's `/api/providers` projection (presence flags only) takes
+ * their place. Anywhere else the local config is returned. When the Home cannot be read the
+ * result is an error: classifying against the inactive local providers would answer for the
+ * wrong machine.
+ */
+export async function accountClassificationConfig(
+  deps: AccountDeps,
+  local: OcxConfig,
+): Promise<{ config: OcxConfig } | { error: string }> {
+  if (deps.baseUrl) return { config: local };
+  const { readLinkChildContext, readLinkHomeJson } = await import("./link-child");
+  const link = readLinkChildContext();
+  if (!link) return { config: local };
+  const unavailable = (detail: string) => ({ error: `Could not read the provider list from ${link.homePhrase} over Remote Link (${link.linkId}): ${detail}.` });
+  try {
+    const { status, body } = await readLinkHomeJson(link, "/api/providers", deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {});
+    if (status !== 200) {
+      // Keep the Home's own sentence (for example the upgrade instruction an older Home yields).
+      const message = body && typeof body === "object" && typeof (body as { error?: unknown }).error === "string"
+        ? (body as { error: string }).error : null;
+      return unavailable(message ?? `the Home answered HTTP ${status}`);
+    }
+    if (!Array.isArray(body)) return unavailable("the Home returned an unreadable provider list");
+    const providers: Record<string, unknown> = {};
+    for (const row of body) {
+      if (!row || typeof row !== "object" || typeof (row as { name?: unknown }).name !== "string") continue;
+      const { name, hasApiKey, ...rest } = row as Record<string, unknown> & { name: string };
+      // A placeholder marks presence for classification; no credential value crosses the link.
+      providers[name] = { ...rest, ...(hasApiKey === true ? { apiKey: "home-credential" } : {}) };
+    }
+    return { config: { ...local, providers: providers as OcxConfig["providers"] } };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 export function proxyUnreachable(transportError?: string): number {
   console.error("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
   // Naming the transport cause distinguishes "nothing is listening" from a refused

package/src/cli/account-auth.ts

@@ -441,6 +441,18 @@ async function resetCredits(argv: string[], deps: RuntimeApiDeps): Promise<void>
   printData(result, wantsJson);
 }
 
+/** Codes that leave a coupon operation unconfirmed: the caller must keep its operationId. */
+const UNCONFIRMED_COUPON_CODES: ReadonlySet<string> = new Set([
+  "attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed",
+  "redeem_failed", "attempt_mark_failed", "operation_token_mismatch",
+]);
+/** Pre-dispatch ledger refusals: unconfirmed when anchored to an operation, never a settled code. */
+const LEDGER_REFUSAL_CODES: ReadonlySet<string> = new Set(["ledger_unavailable", "capacity"]);
+/** The only codes the ledger records as a definitive outcome; any other settled code is unconfirmed. */
+const DEFINITIVE_SETTLED_CODES: ReadonlySet<string> = new Set([
+  "redeemed", "auth_failed", "fetch_resets_failed", "no_coupons_available", "coupon_unavailable", "token_unresolved",
+]);
+
 async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   // The account id is optional here (the server falls back to the selected xAI
@@ -467,6 +479,7 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
   rejectArgs(args, USAGE);
   const accountId = rawId ? (rawId === "main" ? "__main__" : rawId) : undefined;
   const effectiveOperationId = consume ? operationId ?? crypto.randomUUID() : undefined;
+  const unconfirmed = () => new RuntimeApiError(`Coupon redemption outcome is unconfirmed. Preserve --operation-id ${effectiveOperationId}; reuse it to inspect this attempt and do not create a replacement operation.`, 503, null);
   let result: unknown;
   try {
     result = consume
@@ -476,15 +489,26 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
       : await runtimeRequest(`/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`, {}, deps);
   } catch (error) {
     const apiError = error instanceof RuntimeApiError ? error : undefined;
-    const body = apiError?.body as { error?: { code?: string } } | null | undefined;
+    const body = apiError?.body as { operationId?: unknown; error?: { code?: string } } | null | undefined;
     const code = body && typeof body === "object" ? body.error?.code : undefined;
+    const carriesOperation = !!body && typeof body === "object" && typeof body.operationId === "string";
     if (consume && (!apiError || (!apiError.code && (
-      (!code && apiError.status >= 500) || ["attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed", "redeem_failed"].includes(code ?? "")
+      (!code && apiError.status >= 500) || UNCONFIRMED_COUPON_CODES.has(code ?? "")
+      || (LEDGER_REFUSAL_CODES.has(code ?? "") && carriesOperation)
     )))) {
       throw new RuntimeApiError(`Coupon redemption outcome is unconfirmed. Preserve --operation-id ${effectiveOperationId}; reuse it to inspect this attempt and do not create a replacement operation.`, apiError?.status ?? 503, apiError?.body ?? null);
     }
     throw error;
   }
+  if (consume) {
+    // A 200 can replay a recorded refusal; only "redeemed" is a successful spend.
+    const settled = result && typeof result === "object" ? (result as { code?: unknown }).code : undefined;
+    if (typeof settled !== "string" || !DEFINITIVE_SETTLED_CODES.has(settled)) throw unconfirmed();
+    if (settled !== "redeemed") {
+      printData(result, wantsJson);
+      throw new RuntimeApiError(`Coupon was not redeemed (${settled}).`, 409, result);
+    }
+  }
   printData(result, wantsJson);
 }
 

package/src/cli/account.ts

@@ -21,7 +21,7 @@ import {
   cmdRoutes,
   cmdStrategy,
 } from "./account-extended";
-import { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
+import { accountClassificationConfig, apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
   from "./account-api";
 
 export { classifyAccount } from "./account-api";
@@ -199,7 +199,12 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
 
@@ -289,7 +294,12 @@ async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const c = classifyAccount(config, name);
   if ("error" in c) {
     console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
@@ -332,7 +342,20 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  // #6957: an account change on a link Child is refused before any Home read.
+  if (!deps.baseUrl) {
+    const refusal = (await import("./link-child")).linkChildProviderChangeRefusal("ocx account use");
+    if (refusal) {
+      console.error(`Error: ${refusal}`);
+      return 1;
+    }
+  }
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const c = classifyAccount(config, name);
   if ("error" in c) {
     console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
@@ -392,7 +415,20 @@ async function cmdClear(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  // #6957: an account change on a link Child is refused before any Home read.
+  if (!deps.baseUrl) {
+    const refusal = (await import("./link-child")).linkChildProviderChangeRefusal("ocx account clear");
+    if (refusal) {
+      console.error(`Error: ${refusal}`);
+      return 1;
+    }
+  }
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const c = classifyAccount(config, name);
   if ("error" in c) {
     console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);

package/src/cli/advisor.ts

@@ -0,0 +1,151 @@
+import { ADVISOR_CONTEXT_SHARING_CONSENT_VERSION, ADVISOR_CONTEXT_SHARING_DISCLOSURE } from "../advisor/disclosure";
+import { CliUsageError, printData, rejectArgs, runCliAction, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx advisor status [--json]
+  ocx advisor on [--ack-context-sharing] [--json]
+  ocx advisor off [--json]
+  ocx advisor consent [--revoke] [--json]
+  ocx advisor set [--model <model>] [--effort <effort>] [--policy <manual|preflight>] [--timeout-ms <ms>] [--json]`;
+
+const VALUED_FLAGS = new Set(["--model", "--effort", "--policy", "--timeout-ms"]);
+
+interface SetOptions {
+  model?: string;
+  effort?: string;
+  policy?: string;
+  timeoutMs?: string;
+}
+
+function parseSetArgs(args: string[]): SetOptions {
+  const options: SetOptions = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (!VALUED_FLAGS.has(arg)) throw new CliUsageError(`unknown advisor set option ${arg}`, USAGE);
+    const value = args[++index];
+    if (value === undefined || value.startsWith("--")) throw new CliUsageError(`${arg} requires a value`, USAGE);
+    // An explicitly supplied empty value is meaningful for --model alone: the settings route
+    // treats "" as the supported "clear the model" state. Every other valued flag still needs one.
+    if (value === "" && arg !== "--model") throw new CliUsageError(`${arg} requires a value`, USAGE);
+    if (arg === "--model") options.model = value;
+    else if (arg === "--effort") options.effort = value;
+    else if (arg === "--policy") options.policy = value;
+    else options.timeoutMs = value;
+  }
+  if (Object.keys(options).length === 0) {
+    throw new CliUsageError("advisor set requires at least one of --model, --effort, --policy, --timeout-ms", USAGE);
+  }
+  return options;
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  printData(await runtimeRequest("/api/advisor/settings", {}, deps), wantsJson);
+}
+
+function printDisclosure(): void {
+  console.error(ADVISOR_CONTEXT_SHARING_DISCLOSURE);
+}
+
+async function readConsent(deps: RuntimeApiDeps): Promise<unknown> {
+  const current = await runtimeRequest("/api/advisor/settings", {}, deps) as {
+    settings?: { contextSharingConsent?: unknown };
+  };
+  return current.settings?.contextSharingConsent;
+}
+
+async function setEnabled(enabled: boolean, argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const acknowledge = takeFlag(args, "--ack-context-sharing");
+  rejectArgs(args, USAGE);
+  if (!enabled) {
+    if (acknowledge) {
+      throw new CliUsageError(
+        "--ack-context-sharing has no effect with `ocx advisor off`; it never records consent.",
+        USAGE,
+      );
+    }
+    printData(await runtimeRequest("/api/advisor/settings", {
+      method: "PUT",
+      body: JSON.stringify({ enabled: false }),
+    }, deps), wantsJson, ["Advisor disabled."]);
+    return;
+  }
+  const consent = await readConsent(deps);
+  if (acknowledge) {
+    printDisclosure();
+    printData(await runtimeRequest("/api/advisor/settings", {
+      method: "PUT",
+      body: JSON.stringify({
+        enabled: true,
+        contextSharingConsent: ADVISOR_CONTEXT_SHARING_CONSENT_VERSION,
+      }),
+    }, deps), wantsJson, ["Advisor enabled with context-sharing consent v1."]);
+    return;
+  }
+  if (consent !== ADVISOR_CONTEXT_SHARING_CONSENT_VERSION) {
+    printDisclosure();
+    throw new CliUsageError(
+      "Advisor context-sharing consent is required before consultations can send task content. "
+      + "Re-run `ocx advisor on --ack-context-sharing` after reading the disclosure, or run `ocx advisor consent`.",
+      USAGE,
+    );
+  }
+  printData(await runtimeRequest("/api/advisor/settings", {
+    method: "PUT",
+    body: JSON.stringify({ enabled: true }),
+  }, deps), wantsJson, ["Advisor enabled."]);
+}
+
+async function consent(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const revoke = takeFlag(args, "--revoke");
+  rejectArgs(args, USAGE);
+  if (!revoke) printDisclosure();
+  printData(await runtimeRequest("/api/advisor/settings", {
+    method: "PUT",
+    body: JSON.stringify({
+      contextSharingConsent: revoke ? null : ADVISOR_CONTEXT_SHARING_CONSENT_VERSION,
+    }),
+  }, deps), wantsJson, [revoke
+    ? "Advisor context-sharing consent removed. Consultations will not send task content."
+    : "Advisor context-sharing consent v1 recorded.",
+  ]);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const options = parseSetArgs(args);
+  const patch: Record<string, unknown> = {};
+  if (options.model !== undefined) patch.model = options.model;
+  if (options.effort !== undefined) patch.effort = options.effort;
+  if (options.policy !== undefined) patch.policy = options.policy;
+  if (options.timeoutMs !== undefined) {
+    const parsed = Number(options.timeoutMs);
+    if (!Number.isFinite(parsed)) throw new CliUsageError("--timeout-ms must be a number", USAGE);
+    patch.timeoutMs = parsed;
+  }
+  printData(await runtimeRequest("/api/advisor/settings", {
+    method: "PUT",
+    body: JSON.stringify(patch),
+  }, deps), wantsJson, ["Advisor settings saved."]);
+}
+
+export async function handleAdvisorCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "status", ...rest] = argv;
+    if (sub === "status") await status(rest, deps);
+    else if (sub === "on") await setEnabled(true, rest, deps);
+    else if (sub === "off") await setEnabled(false, rest, deps);
+    else if (sub === "consent") await consent(rest, deps);
+    else if (sub === "set") await set(rest, deps);
+    else throw new CliUsageError(`unknown advisor command ${sub}`, USAGE);
+  });
+}
+
+export const ADVISOR_USAGE = USAGE;

package/src/cli/auxiliary-listener-preflight.ts

@@ -0,0 +1,37 @@
+import type { OcxConfig } from "../types";
+import { AuxiliaryListenerBindError } from "../server/ports";
+import { createServer } from "node:net";
+
+/**
+ * Reject impossible auxiliary binds before startup creates private state. On Windows
+ * that publication requires several synchronous ACL subprocesses. This is only an
+ * early rejection: startServer still owns the actual bind and transactional rollback
+ * if another process takes the port between this probe and startup.
+ */
+export async function assertAuxiliaryListenerPortsAvailable(config: OcxConfig): Promise<void> {
+  const loopback = config.unauthenticatedLoopbackListener;
+  const management = config.runtimeRole === "hub" ? config.hub?.managementIngress : undefined;
+  const targets = [
+    { listener: "unauthenticatedLoopbackListener", port: loopback?.enabled ? loopback.port : undefined },
+    { listener: "hub.managementIngress", port: management?.enabled ? management.port : undefined },
+  ] as const;
+  // Each probe releases its socket, so two listeners configured for one port would both
+  // pass and startup would still fail on the second bind. Reject the collision directly.
+  if (targets[0].port !== undefined && targets[0].port === targets[1].port) {
+    throw new AuxiliaryListenerBindError(
+      "hub.managementIngress", targets[1].port, "127.0.0.1",
+      new Error("port is also configured for unauthenticatedLoopbackListener"),
+    );
+  }
+  for (const { listener, port } of targets) {
+    // The port-less companion shares the public bind; it has no independent target.
+    if (port === undefined) continue;
+    await new Promise<void>((resolve, reject) => {
+      const probe = createServer(socket => socket.destroy());
+      const fail = (cause: unknown) => reject(new AuxiliaryListenerBindError(listener, port, "127.0.0.1", cause));
+      probe.once("error", fail);
+      probe.once("listening", () => probe.close(error => error ? fail(error) : resolve()));
+      try { probe.listen({ port, host: "127.0.0.1" }); } catch (error) { fail(error); }
+    });
+  }
+}

package/src/cli/capabilities-access-remote.ts

@@ -2,6 +2,14 @@ import type { Capability } from "./capability-types";
 
 /** Verified existing handlers only; local operations never claim management routes. */
 export const ACCESS_REMOTE_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["hub", "disable"], summary: "Return a hub to standalone in one validated config write.",
+    usage: "ocx hub disable [--revoke-clients --client-key <id> ...] [--json]",
+    routes: [],
+    flags: [{ name: "--revoke-clients", value: "boolean", summary: "Revoke only explicitly selected saved client key IDs." }, { name: "--client-key", value: "string", summary: "Exact saved key ID to revoke; repeatable, requires --revoke-clients." }, { name: "--json", value: "boolean", summary: "Emit the result and restart guidance as JSON." }],
+    mutates: true, json: "envelope",
+    details: ["Removes hub, unauthenticatedLoopbackListener, runtimeRole and hostname atomically after validation; non-hub roles refuse without changes.", "Existing keys have no verified client origin. Names never select keys; --revoke-clients requires exact --client-key IDs when keys exist. Unselected keys remain.", "Prints only safe key metadata, never plaintext keys or pending rotations. Restart advice is informational; the running proxy and external publishing are unchanged."],
+  },
   {
     command: ["access", "key"], summary: "Manage API access keys and inspect masked metadata.",
     usage: "ocx access key list [--json]",

package/src/cli/capabilities-agents-routing.ts

@@ -25,6 +25,24 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
       "queued means submitted, not processed. unknown must not be replayed; no automatic retry, daemon start or thread resume.",
       "Exit 0: queued; 1: not sent; 3: unknown; 64: invalid usage. No remote/Claude transport or skill installation."],
   },
+  {
+    command: ["advisor"],
+    summary: "Inspect and configure the advisor sidecar (expert consultation for routed workers).",
+    routes: [
+      { method: "GET", path: "/api/advisor/settings" },
+      { method: "PUT", path: "/api/advisor/settings" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit advisor settings as JSON." }],
+    mutates: true,
+    json: "payload",
+    details: [
+      "`status` (the default) reads the resolved settings; `on`/`off` toggle the sidecar; `consent` records or revokes context-sharing consent; `set` updates model, effort, policy, or timeout.",
+      "`on` does not grant consent. Without current consent it refuses and prints the disclosure. `on --ack-context-sharing` records consent v1 and enables. `consent --revoke` removes consent and stops task-context transfer.",
+      "The advisor model may be any routable model string: a bare native model, an explicit `provider/model`, or an account-qualified native model.",
+      "`policy: preflight` makes OpenCodex attempt one automatic consultation per task with a stable conversation identity once the task shows orientation evidence (an assistant tool call or a tool result after the latest user message). Without a stable identity, each eligible request may trigger another consultation. `policy: manual` consults only when the worker calls the synthetic `advisor` tool. Neither path sends task context without current context-sharing consent.",
+    ],
+  },
+
   {
     command: ["agent", "status"],
     usage: "ocx agent status [--json]",

package/src/cli/capabilities-base.ts

@@ -26,6 +26,8 @@ export const CAPABILITIES: readonly Capability[] = [
     bannerLines: ["ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)"],
     details: ["Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher."],
   },
+  {"command": ["link","probe"],"summary": "Probe an SSH host fingerprint and OpenCodex version without trusting it.","routes": [{"method": "POST","path": "/api/link/probe"}],"flags": [{"name": "--json","value": "boolean","summary": "Emit alias, fingerprint, key type and version as JSON."}],"mutates": true,"json": "payload","usage": "ocx link probe <alias> [--json]","details": ["Requires loopback admin authority on the Home. Stores only a temporary pending offer; does not persist host trust or issue a link key."]},
+  {"command": ["link","add"],"summary": "Connect an SSH Child to this Home after confirming its fingerprint.","routes": [{"method": "POST","path": "/api/link/probe"},{"method": "POST","path": "/api/link/confirm-host"},{"method": "POST","path": "/api/link/apply"}],"flags": [{"name": "--expect-fingerprint","value": "string","summary": "Exact SHA256 host fingerprint; required without an interactive TTY."},{"name": "--json","value": "boolean","summary": "Emit the verified link result as JSON."}],"mutates": true,"json": "payload","usage": "ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]","details": ["Requires loopback admin authority on the Home. Without a fingerprint, requires a TTY and explicit yes after showing the offered fingerprint. Never prints the link key.","Preflights bound Child restart support and curl, connects, restarts once and verifies a fresh authenticated catalog relay before success. Post-connect failures can leave Child config; run ocx disconnect and ocx restart there before retrying."]},
   {
     command: ["link","port"],
     summary: "Allocate a free loopback port for a remote home link.",
@@ -65,6 +67,16 @@ export const CAPABILITIES: readonly Capability[] = [
     details: ["Requires a valid link ID and loopback admin authority. Explicit force additionally requires --yes.","Ordinary revoke always emits {linkId} JSON; forced revoke has human output or a JSON cleanup receipt. Already-revoked link_not_found is idempotent success.","Ordinary revoke retains its no-body and idempotent behavior. Forced success reports remoteCleanup:skipped from invocation intent; already-missing link reports unverified. Neither proves the remote client disconnected.","If forced cleanup was needed, run ocx disconnect on the remote client. No new enrollment, SSH trust or credential action is implied."],
     usage: "ocx link revoke --link-id <id> [--force --yes] [--json]",
   },
+  {
+    command: ["link","reconnect"],
+    summary: "Restart a Home-initiated link's SSH tunnel now.",
+    routes: [{"method":"POST","path":"/api/link/{id}/reconnect"}],
+    flags: [{"name":"--link-id","value":"string","required":true,"summary":"Home-initiated link id whose tunnel to restart."},{"name":"--json","value":"boolean","summary":"Emit the restarted link id as JSON."}],
+    mutates: true,
+    json: "envelope",
+    usage: "ocx link reconnect --link-id <id> [--json]",
+    details: ["Requires a valid link ID and loopback admin authority. Stops the current ssh child, clears any backoff or failed state and starts a fresh attempt; read ocx link status for the outcome.","A Child-initiated link is refused with link_not_home_initiated: its own computer owns and retries that tunnel.","Always emits {linkId} JSON."],
+  },
   {
     command: ["remote-workspace","pair"],
     summary: "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
@@ -717,7 +729,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--effort","value":"string","summary":"set: also write the role's reasoning effort."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
     mutates: true,
     json: "payload",
-    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
+    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model and effort."],
     usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--effort <level>] [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
   },
   {
@@ -774,7 +786,7 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["api","policy"],
     summary: "Read the protocol policy, or change the Messages surface, unrepresentable policy and rollout switches.",
     routes: [{"method":"GET","path":"/api/protocols"},{"method":"PATCH","path":"/api/protocols/settings"}],
-    flags: [{"name":"--messages","value":"string","summary":"Open or close the Messages API: on or off. Off also turns the Claude integration off."},{"name":"--unrepresentable","value":"string","summary":"legacy keeps today's behavior; reject refuses a request its path cannot carry."},{"name":"--rollout","value":"string","summary":"One switch as name=on or name=off; repeatable. Every switch defaults off."},{"name":"--json","value":"boolean","summary":"Emit the resulting GET /api/protocols body."}],
+    flags: [{"name":"--messages","value":"string","summary":"Open or close the Messages API: on or off. Off also turns the Claude integration off."},{"name":"--unrepresentable","value":"string","summary":"legacy keeps today's behavior; reject refuses a request its path cannot carry."},{"name":"--rollout","value":"string","summary":"One switch as name=on or name=off; repeatable. Every switch defaults off except antigravityDirect."},{"name":"--json","value":"boolean","summary":"Emit the resulting GET /api/protocols body."}],
     mutates: true,
     json: "payload",
     details: ["A bare invocation reads and never writes.","A setting flag changes the operator's config; run it only when the operator asks for that change."],

package/src/cli/catalog-command-result.ts

@@ -23,7 +23,8 @@ export async function runCatalogAction(
     if (error instanceof RuntimeApiError) {
       if (error.code) {
         console.error(`Error: ${error.code === "proxy_not_running" ? PROXY_NOT_RUNNING_MESSAGE
-          : "This listener has no management API. Run management commands on the connected Hub. No request was sent."}`);
+          : error.code === "link_child_management_unavailable" ? terminalSafeText(error.message)
+            : "This listener has no management API. Run management commands on the connected Hub. No request was sent."}`);
         return 1;
       }
       const code = own(error.body, "code") ?? own(own(error.body, "error"), "code");