@bitkyc08/opencodex 2.82.0 → 2.84.0

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");

package/src/cli/claude.ts

@@ -12,7 +12,7 @@ import { spawn } from "node:child_process";
 import { loadConfig } from "../config";
 import { injectClaudeAgentDefs } from "../claude/agents-inject";
 import { CLAUDE_ALIAS_PREFIX_CURRENT, CLAUDE_ALIAS_PREFIX_CURRENT_V2, CLAUDE_ALIAS_PREFIX_V1, CLAUDE_ALIAS_PREFIX_V2 } from "../claude/alias";
-import { claudeToolSearchEnv, effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
+import { claudeTierDisplayName, claudeToolSearchEnv, effectiveModelEnv, isClaudeTierLabelSlot, resolveAutoContext } from "../claude/context-windows";
 import { claudeConfigDir, fetchGatewayModels, writeGatewayModelCache } from "../claude/gateway-cache";
 import { commandInvocation } from "../lib/win-exec";
 import { isProxyAdmissionSecret } from "../server/auth-cors";
@@ -211,10 +211,12 @@ export function buildClaudeEnv(
   // real cost to a documented entry point, and the escape hatch is the launcher: run
   // through `ocx` (the published bin) and genuine shell exports are preserved by proof.
   deleteUntrustedAnthropicSlots(env, deps);
-  const setDefault = (name: string, value: string | undefined) => {
-    if (value === undefined || value.length === 0) return;
-    if (env[name] !== undefined && env[name] !== "") return; // user wins
+  /** Returns whether the value was written; a value the user already has wins. */
+  const setDefault = (name: string, value: string | undefined): boolean => {
+    if (value === undefined || value.length === 0) return false;
+    if (env[name] !== undefined && env[name] !== "") return false; // user wins
     env[name] = value;
+    return true;
   };
   if (config.claudeCode?.subagentModelForce !== undefined) {
     const forced = resolveSubagentForceModel(config, contextWindows, deps.forceAvailableSelectors !== undefined ? { selectors: deps.forceAvailableSelectors } : { entries: deps.forceAvailable ?? [] });
@@ -415,7 +417,9 @@ export function buildClaudeEnv(
   // with automatic [1m] context-variant marking when the slot's target model has an
   // authoritative >=1M window (Claude Code then accounts 1M, compaction preserved).
   for (const [name, value] of Object.entries(effectiveModelEnv(config.claudeCode, contextWindows, auto))) {
-    setDefault(name, value);
+    // A tier slot this launch wrote gets its picker label too (#6926). A slot the user exported
+    // stays unlabelled, and a `<slot>_NAME` the user exported wins.
+    if (setDefault(name, value) && isClaudeTierLabelSlot(name)) setDefault(`${name}_NAME`, claudeTierDisplayName(value));
   }
   return env;
 }
@@ -682,7 +686,12 @@ export function buildNativeClaudeEnv(
   const providerNames = Object.keys(config.providers);
   for (const name of MODEL_ENV_SLOT_NAMES) {
     const value = env[name];
-    if (value && isProxyOnlyModelId(value, providerNames)) delete env[name];
+    if (!value || !isProxyOnlyModelId(value, providerNames)) continue;
+    delete env[name];
+    // The label opencodex paired with this slot names a proxy route the native session cannot use.
+    const labelName = `${name}_NAME`;
+    const label = claudeTierDisplayName(value);
+    if (isClaudeTierLabelSlot(name) && label !== undefined && env[labelName] === label) delete env[labelName];
   }
   if (deps.allowRootSkipPermissions === true && !env.IS_SANDBOX) env.IS_SANDBOX = "1";
   return env;

package/src/cli/config-command.ts

@@ -60,11 +60,14 @@ export function remoteHubConfigNote(
   // alone describes a machine that cannot read its hub, and `ocx status` is still the command
   // that has the facts — so the note points there in every case, connected or not.
   const connected = connection.state === "connected" && connection.token === "owned";
+  const link = config.client.transport === "link";
   const note = connection.state !== "connected"
     ? `this machine is configured as a client but its connection is ${connection.state}${connection.reason ? ` (${connection.reason})` : ""}; run ocx connect status`
     : connection.token !== "owned"
-      ? `this machine is configured as a client but its hub data-plane token is ${connection.token}; run ocx connect status`
-      : "provider credentials and model availability live on the hub; run ocx status";
+      ? `this machine is configured as a client but its ${link ? "Remote Link key" : "hub data-plane token"} is ${connection.token}; run ocx connect status`
+      : link
+        ? "this machine is a Remote Link Child: provider credentials, model availability and the Codex settings OpenCodex writes come from its Home; the settings in this file are local and inactive while linked; run ocx status"
+        : "provider credentials and model availability live on the hub; run ocx status";
   return { connected, origin: config.client.serverUrl, note };
 }
 
@@ -235,6 +238,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       const path = args.shift();
       if (!path) throw new CliUsageError("config path is required", USAGE);
       rejectArgs(args, USAGE);
+      await (await import("./link-child")).printLinkChildLocalNotice("The values");
       const diagnostics = readConfigDiagnostics();
       if (diagnostics.source === "fallback" || diagnostics.error) {
         console.error(`Warning: Config at ${getConfigPath()} is invalid or unreadable; defaults are being shown for invalid settings. Run: ocx config validate. Inspect: ocx config show --source.`);
@@ -246,6 +250,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       return;
     }
     if (action === "set" || action === "unset") {
+      await (await import("./link-child")).printLinkChildLocalWriteNotice();
       const path = args.shift();
       const raw = action === "set" ? args.shift() : undefined;
       if (!path || (action === "set" && raw === undefined)) throw new CliUsageError(action === "unset" ? "config path is required" : "config path and value are required", USAGE);
@@ -316,6 +321,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       return;
     }
     if (action === "import") {
+      await (await import("./link-child")).printLinkChildLocalWriteNotice();
       const path = args.shift();
       const yes = takeFlag(args, "--yes");
       if (!path) throw new CliUsageError("import path is required", USAGE);

package/src/cli/debug.ts

@@ -10,6 +10,14 @@ async function requireLiveProxy() {
     console.error("Proxy is not running. Start it with: ocx start");
     process.exit(1);
   }
+  if (live.role === "client") {
+    // Debug capture is the serving proxy's; a connected client has no management API (#6957).
+    const { readLinkChildContext, linkChildRefusal } = await import("./link-child");
+    const link = readLinkChildContext();
+    console.error(link ? linkChildRefusal(link, "ocx debug")
+      : "This listener runs in the client role and has no management API. Run this command on its serving hub. No request was sent.");
+    process.exit(1);
+  }
   return live;
 }
 

package/src/cli/dispatch.ts

@@ -31,7 +31,7 @@ import { restoreNativeCodexAsync, type CodexNativeRestoreResult } from "../codex
 import { stripGrokConfig } from "../grok/inject";
 import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
-import { isJsonOption, takeFlag, terminalSafeError } from "./runtime-api";
+import { isJsonOption, takeFlag, terminalSafeError, terminalSafeText } from "./runtime-api";
 import { printStopSummary, type StopOutcome } from "./stop-report";
 import { parseStopApproval, type StopApproval } from "./stop-approval";
 import type { ResolveArgs } from "./resolve";
@@ -407,9 +407,22 @@ const commandRunners: Record<string, CommandRunner> = {
       try {
         const { syncConnectedClient } = await import("../client/connect");
         const result = await syncConnectedClient({ restartCodex });
+        const link = clientState.value.transport === "link";
         console.log(result.stale
-          ? "Hub unavailable; retained and applied the last-known-good remote catalog (stale)."
-          : "Remote hub catalog synchronized.");
+          ? `${link ? "Home" : "Hub"} unavailable; retained and applied the last-known-good remote catalog (stale).`
+          : link ? "Remote Link Home catalog synchronized." : "Remote hub catalog synchronized.");
+        if (result.homeSettings) {
+          const { describeHomeCodexSettings } = await import("../link/codex-settings");
+          const settings = result.homeSettings;
+          if (settings.source === "local") {
+            console.log(`Codex settings: kept this machine's local values (${terminalSafeText(settings.reason)}).`);
+          } else {
+            console.log(settings.source === "home"
+              ? `Codex settings applied from Home ${terminalSafeText(settings.document.home.name)}:`
+              : `Codex settings applied from the last recorded Home read (${terminalSafeText(settings.reason)}):`);
+            for (const line of describeHomeCodexSettings(settings.document.settings)) console.log(`  ${terminalSafeText(line)}`);
+          }
+        }
         await handleConnectedSyncCatalogWrite(result, restartScope);
         // `process.exitCode` rather than a literal 0, for the same reason every other
         // runner does it (tests/cli/cli-transport-honesty.test.ts): the catalog-write helper

package/src/cli/export-command.ts

@@ -29,6 +29,7 @@
 import { writeFileSync } from "node:fs";
 import { loadConfig } from "../config";
 import {
+  ClientPathError,
   EXPORT_CLIENTS,
   EXPORT_CLIENT_IDS,
   buildClientConfigText,
@@ -193,6 +194,18 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     const clientConfig = built.document;
     const text = built.text;
 
+    // Resolve the human-facing destination BEFORE writing anything. A client whose
+    // config location cannot be determined (a relative override, or ZCode bootstrap
+    // settings naming an unknown data root) still exports the document: the export
+    // writes nothing into the client and the destination is advisory text.
+    let destination: string;
+    try {
+      destination = spec.destination(process.env);
+    } catch (error) {
+      if (!(error instanceof ClientPathError)) throw error;
+      destination = `unknown (${error.message})`;
+    }
+
     // Every serializer already ends with exactly one newline.
     if (out !== undefined) writeExport(out, text, force);
     // stderr, so `--json` stdout stays a standalone JSON document.
@@ -208,7 +221,7 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
       ...text.trimEnd().split("\n"),
       "",
       ...(out !== undefined ? [`Wrote ${out}`] : []),
-      `Destination: ${spec.destination(process.env)}`,
+      `Destination: ${destination}`,
       "Merge this generated configuration into that file; do not replace it.",
       `Before launching: ${spec.exportHint}`,
       `${modelCount} model${modelCount === 1 ? "" : "s"}; ${modelsWithoutLimits} omit context limits (the client applies its own defaults).`,

package/src/cli/hub-disable.ts

@@ -0,0 +1,99 @@
+import { mutatePersistedConfig, validateConfigCandidate } from "../config";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { probeServiceInstallation } from "../service/cli";
+import { redactSecretString } from "../lib/redact";
+import { CliUsageError, printData, runCliAction } from "./runtime-api";
+import type { OcxConfig } from "../types";
+
+export const HUB_DISABLE_USAGE = "ocx hub disable [--revoke-clients --client-key <id> ...] [--json]";
+const HUB_KEYS = ["hub", "unauthenticatedLoopbackListener", "runtimeRole", "hostname"] as const;
+const PUBLISHING_NOTE = "External publishing is unchanged. Check tailscale serve status and any other frontend for mappings to the old hub ports.";
+
+export interface HubDisableOptions { json: boolean; revokeClients: boolean; clientKeys: string[] }
+export interface HubDisableDeps {
+  mutateConfig?: typeof mutatePersistedConfig;
+  restartHint?: () => string;
+}
+interface HubDisableResult {
+  removed: string[];
+  keys: { id: string; name: string; createdAt: string; revoked: boolean }[];
+  revoked: string[];
+}
+
+export function parseHubDisableArgs(args: string[]): HubDisableOptions {
+  const options: HubDisableOptions = { json: false, revokeClients: false, clientKeys: [] };
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--json" && !options.json) options.json = true;
+    else if (arg === "--revoke-clients" && !options.revokeClients) options.revokeClients = true;
+    else if (arg === "--client-key") {
+      const id = args[++index];
+      if (!id || id.startsWith("-") || options.clientKeys.includes(id)) throw new CliUsageError("Each --client-key requires a unique exact key ID.", HUB_DISABLE_USAGE);
+      options.clientKeys.push(id);
+    } else throw new CliUsageError("Unknown or repeated hub disable argument.", HUB_DISABLE_USAGE);
+  }
+  if (options.clientKeys.length && !options.revokeClients) throw new CliUsageError("--client-key requires --revoke-clients.", HUB_DISABLE_USAGE);
+  return options;
+}
+
+/** Selection is explicit: legacy keys have editable names but no trustworthy issuance marker. */
+export function disableHubConfig(config: OcxConfig, options: HubDisableOptions): HubDisableResult {
+  if (config.runtimeRole !== "hub") throw new CliUsageError("This machine is not a hub; no settings or keys were changed.");
+  const keys = config.apiKeys ?? [];
+  const secrets = keys.flatMap(key => [key.key, key.pendingRotation?.key]).filter((secret): secret is string => Boolean(secret));
+  const safeMetadata = (value: string) => redactSecretString(secrets.reduce((text, secret) => text.split(secret).join("[REDACTED]"), value));
+  if (options.revokeClients && keys.length && !options.clientKeys.length) {
+    throw new CliUsageError("Keys have no verified client origin. List IDs with 'ocx access key list --json', then repeat --client-key <id> for each client key to revoke.", HUB_DISABLE_USAGE);
+  }
+  const selected = new Set(options.clientKeys);
+  if (options.clientKeys.some(id => !keys.some(key => key.id === id))) {
+    throw new CliUsageError("A selected client key ID is not in the current config; no settings or keys were changed.");
+  }
+  const candidate = structuredClone(config);
+  const removed = HUB_KEYS.filter(key => Object.hasOwn(candidate, key));
+  for (const key of HUB_KEYS) delete candidate[key];
+  if (options.revokeClients) candidate.apiKeys = keys.filter(key => !selected.has(key.id));
+  const validated = validateConfigCandidate(candidate);
+  if (!validated.ok) throw new CliUsageError(validated.error);
+  // Keep deletion intent so a later live save cannot resurrect the hub's old bindings.
+  for (const key of HUB_KEYS) deleteConfigTopLevelKey(config, key);
+  Object.assign(config, validated.config);
+  return {
+    removed,
+    keys: keys.map(key => ({ id: safeMetadata(key.id), name: safeMetadata(key.name), createdAt: safeMetadata(key.createdAt), revoked: selected.has(key.id) })),
+    revoked: options.revokeClients ? [...selected].map(safeMetadata) : [],
+  };
+}
+
+export function hubDisableRestartHint(): string {
+  try {
+    if (inspectDesktopSupervision().kind === "desktop") return "Restart to apply: ocx restart (OpenCodex Desktop supervises the replacement).";
+    const service = probeServiceInstallation();
+    if (service.state === "installed") return "Restart to apply: ocx service restart.";
+  } catch { /* An unavailable probe must not prevent an already validated config change. */ }
+  return "Restart to apply: use your current proxy supervisor; for a manually started proxy, ocx restart.";
+}
+
+export async function runHubDisable(args: string[], deps: HubDisableDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const options = parseHubDisableArgs(args);
+    const outcome = (deps.mutateConfig ?? mutatePersistedConfig)(config => ({
+      changed: true, value: disableHubConfig(config, options),
+    }));
+    if (outcome.status === "unavailable") throw new Error(`Hub disable could not read or commit the config (${outcome.reason}); retry after fixing the config.`);
+    let restart: string;
+    try { restart = (deps.restartHint ?? hubDisableRestartHint)(); }
+    catch { restart = "Restart to apply: use your current proxy supervisor."; }
+    const result = { ok: true, ...outcome.value, restart, note: PUBLISHING_NOTE, keyOrigin: "unverified", effectiveAfterRestart: true };
+    // Explicit field projection excludes secrets and pending rotations; names are arbitrary input.
+    const safe = { ...result, keys: result.keys.map(key => ({ ...key, name: redactSecretString(key.name) })) };
+    printData(safe, options.json, [
+      `Removed hub settings: ${safe.removed.join(", ")}.`,
+      ...safe.keys.map(key => `${key.revoked ? "Revoked" : "Retained"} saved key: ${key.id} (${key.name})`),
+      "Saved keys have no verified client origin; revocation uses only explicitly selected IDs.",
+      restart, PUBLISHING_NOTE,
+      "Restart is required to apply all saved settings; this command does not terminate existing sessions.",
+    ]);
+  });
+}

package/src/cli/hub.ts

@@ -7,9 +7,10 @@ import {
   type GuiPairRequestResult,
 } from "./gui-pair-client";
 import type { RuntimeApiDeps } from "./runtime-api";
+import { HUB_DISABLE_USAGE, runHubDisable, type HubDisableDeps } from "./hub-disable";
 
 export const HUB_USAGE =
-  "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]";
+  "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]\n  " + HUB_DISABLE_USAGE;
 
 const PAIRING_WARNING = "Pairing codes are secret, single-use, and expire quickly. Do not save them.";
 
@@ -23,7 +24,7 @@ const PAIRING_WARNING = "Pairing codes are secret, single-use, and expire quickl
  */
 const DEFAULT_CLIENT_BROWSER_ORIGIN = "http://localhost:10100";
 
-export interface HubCommandDeps extends RuntimeApiDeps {
+export interface HubCommandDeps extends RuntimeApiDeps, HubDisableDeps {
   loadConfig: () => OcxConfig;
   findLiveProxy?: () => Promise<LiveProxy | null>;
   requestPairingGrant?: (
@@ -361,6 +362,7 @@ async function runInvite(args: string[], deps: HubCommandDeps): Promise<number>
 }
 
 export async function runHubCommand(args: string[], deps: HubCommandDeps): Promise<number> {
+  if (args[0] === "disable") return runHubDisable(args.slice(1), deps);
   if (args[0] !== "invite") {
     console.error(`Usage: ${HUB_USAGE}`);
     return 1;

package/src/cli/index.ts

@@ -11,6 +11,7 @@ import { packageVersion } from "../lib/package-version";
 import { codexHomeIsAbsent } from "../codex/codex-home-owner";
 import { getCodexHome } from "../codex/paths";
 import { admitUpdateRestartChild } from "./update-restart-child";
+import { HEALTH_SENTINEL_STANDALONE_ARG, startServiceHealthSentinel } from "../service/health-sentinel-launch";
 import { UpdateRestartRequired } from "./update-restart-candidate";
 import { describeUpdateRestartFailure, restartFromCurrentInstallation } from "./update-restart";
 import { findGuiDist } from "../server/gui-static";
@@ -212,6 +213,7 @@ initializeNodeLauncherContext();
 // The compiled executable is also the capture-only MCP server's launcher.
 // Handle this private entrypoint before CLI preflight or command dispatch.
 if (process.argv[2] === "__keyring-load-check") { console.log(JSON.stringify((await import("../lib/keyring-native")).inspectKeyringBinding())); process.exit(0); }
+if (process.argv[2] === HEALTH_SENTINEL_STANDALONE_ARG) process.exit(await (await import("../service/health-sentinel-main")).runHealthSentinelProcess());
 
 // The compiled executable also launches the isolated MCP servers.
 // Handle these private entrypoints before CLI preflight or command dispatch.
@@ -623,6 +625,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   // Records are visible now; background work may observe this runtime without a gap.
   scheduleCatalogPrewarm();
   installCrashGuards();
+  let healthSentinel: ReturnType<typeof startServiceHealthSentinel> = null; // opt-in #6671, started once ready
   // No pre-emptive snapshot here. `injectCodexConfig` journals the exact bytes it
   // is about to transform; snapshotting earlier only captured a baseline that could
   // already be stale by the time injection ran (#477).
@@ -646,6 +649,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     try { routingHealer?.stop(); } catch { /* best-effort */ }
     try { guardian.stop(); } catch { /* best-effort */ }
     try { historyGuardian?.stop(); } catch { /* best-effort */ }
+    try { healthSentinel?.stop(); } catch { /* best-effort */ }
     // Dashboard drain-and-restart (#563) must not tear down injection: the replacement
     // process expects Codex/Grok/env fences to still be in place. A sibling owns none of them.
     const teardown = decideStartExitTeardown({ sibling: siblingStart, recycling: isRecyclingForExit(), ocxService: process.env.OCX_SERVICE });
@@ -746,6 +750,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   );
   if (!startupSync.ran) console.log(startupLeftCodexNativeLine(localClientSkipReason(config), server.port ?? port));
   await refreshOwnedRaycastCatalog(config, port);
+  if (!cleaned && !shuttingDown) healthSentinel = startServiceHealthSentinel(config); // after startup reconciliation; never mid-boot or mid-drain
   // #1046: one warning per startup, after BOTH writes. The server's cache
   // invalidation happens first and the catalog sync second, so the mtime is only
   // final here — and neither write site warns on its own, or a boot that hits
@@ -1717,7 +1722,7 @@ async function handleStatus() {
   // are tagged `(local)`. A reader who sees neither draws the wrong conclusion from a correct
   // report — an agent read `xai ✗ not logged in` off a client and decided the hub could not
   // serve grok.
-  const remoteHubBanner = remoteHubBannerLine(status.json.remoteHub);
+  const remoteHubBanner = remoteHubBannerLine(status.json.remoteHub, status.json.connection.transport);
   if (remoteHubBanner) console.log(remoteHubBanner);
   // `(local)` only while connected: on a standalone install every line is local, and tagging
   // them all would be noise that trains the reader to skip the tag.
@@ -1798,7 +1803,9 @@ async function handleStatus() {
   if (status.json.hub) {
     for (const line of hubStatusLines(status.json.hub)) console.log(`   ${line}`);
   }
-  console.log(`   Remote hub: ${status.json.connection.state}${status.json.connection.serverUrl ? ` (${status.json.connection.serverUrl})` : ""}`);
+  console.log(status.json.remoteHub.link
+    ? `   Remote Link Home: ${status.json.connection.state} (${status.json.remoteHub.link.homePhrase}, ${status.json.remoteHub.link.linkId})`
+    : `   ${status.json.connection.transport === "link" ? "Remote Link Home" : "Remote hub"}: ${status.json.connection.state}${status.json.connection.serverUrl ? ` (${status.json.connection.serverUrl})` : ""}`);
   if (status.json.connection.state === "invalid" || status.json.connection.state === "mismatched") {
     console.log(`   ⚠️  ${status.json.connection.reason}`);
   }
@@ -1854,10 +1861,12 @@ async function handleStatus() {
   // that decide what a request can route to. The local block still prints — an operator debugging
   // a half-migrated machine needs to see it — but under a heading that says it is not in use, and
   // below the hub's, so the hub's is what a reader (or an agent) encounters first (#4236).
-  for (const line of remoteHubStatusLines(status.json.remoteHub)) console.log(`   ${line}`);
+  for (const line of remoteHubStatusLines(status.json.remoteHub, status.json.connection.transport)) console.log(`   ${line}`);
   if (status.json.remoteHub.connected) {
     console.log(status.json.remoteHub.stateSource === "unavailable"
-      ? "   Local-only credential state (this is NOT the hub's; the hub's state could not be read):"
+      ? status.json.connection.transport === "link"
+        ? "   Local-only credential state (Home state is unavailable over Remote Link):"
+        : "   Local-only credential state (this is NOT the hub's; the hub's state could not be read):"
       : "   Local-only (not used for routing while connected):");
   }
   console.log(`   OAuth logins${local}:`);

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