@bitkyc08/opencodex 2.83.0 → 2.84.0

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/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-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]",
   },
   {

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