@bitkyc08/opencodex 2.90.0 → 2.91.0

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

@@ -203,6 +203,56 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["Without --list at least one setting is required. Stored settings and Codex application outcomes remain distinct.","Stream-routed-output belongs only to web. Timeout changes preserve siblings; native apply and saved state are distinct."],
   },
+  {
+    command: ["fallback"],
+    usage: "ocx fallback [status] [--json]",
+    summary: "Show which model and provider fallbacks are allowed, per-device local fallback, and the last fallback taken or refused.",
+    routes: [{"method": "GET", "path": "/api/fallback"}],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the ocx.fallback/1 state."}],
+    mutates: false,
+    json: "payload",
+    details: ["Reads the live proxy. On a Remote Link Child it reads the Home's state over the link (aliases omitted). The last event is in memory and resets on restart."],
+  },
+  {
+    command: ["fallback", "off"],
+    usage: "ocx fallback off [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Refuse model or provider fallback globally or for one provider, route or device.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to the provider a request started on."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector such as combo/<id> or policy/<id>."}, {"name": "--device", "value": "string", "summary": "Scope to a Remote Link id or alias, or a Hub data key id; device off always refuses."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["A refused hop answers fallback_refused with the triggering failure's status. Rotation among accounts or keys of one provider pool is not a fallback and stays on."],
+  },
+  {
+    command: ["fallback", "on"],
+    usage: "ocx fallback on [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Allow model or provider fallback at one scope, overriding a broader off.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to a provider."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector."}, {"name": "--device", "value": "string", "summary": "Scope to a device."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["Route beats provider beats global. A device setting can only refuse: on for a device records the value but never reopens a hop another scope refuses."],
+  },
+  {
+    command: ["fallback", "clear"],
+    usage: "ocx fallback clear [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]",
+    summary: "Remove a fallback override so the scope inherits again.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--kind", "value": "string", "summary": "model, provider or all (default)."}, {"name": "--provider", "value": "string", "summary": "Scope to a provider."}, {"name": "--route", "value": "string", "summary": "Scope to an exact selector."}, {"name": "--device", "value": "string", "summary": "Scope to a device."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["Clearing every override restores today's behavior: every fallback allowed."],
+  },
+  {
+    command: ["fallback", "local"],
+    usage: "ocx fallback local <on|off> --device <id|alias> [--json]",
+    summary: "Record whether a device may use its own providers while the Home is unreachable.",
+    routes: [{"method": "PUT", "path": "/api/fallback"}],
+    flags: [{"name": "--device", "value": "string", "summary": "Remote Link id or alias, or Hub data key id."}, {"name": "--json", "value": "boolean", "summary": "Emit the resulting state."}],
+    mutates: true,
+    json: "payload",
+    details: ["Run on the Home. A permission GOAT reads; OpenCodex itself keeps answering home_unreachable on the device and never serves it from local providers."],
+  },
   {
     command: ["effort"],
     usage: "ocx effort [status|low|medium|high|xhigh|max|ultra|->] [--json]",

package/src/cli/capabilities-base.ts

@@ -86,6 +86,16 @@ export const CAPABILITIES: readonly Capability[] = [
     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: ["link","cleanup"],
+    summary: "Find Windows Remote Link Children and explain how to move them to Hub mode.",
+    routes: [],
+    flags: [{"name":"--link-id","value":"string","summary":"Check only this link."},{"name":"--json","value":"boolean","summary":"Emit {links, changed:false} as JSON."}],
+    mutates: false,
+    json: "payload",
+    usage: "ocx link cleanup [--link-id <id>] [--json]",
+    details: ["Runs on the Home from its local link store. Asks each Home-initiated Child for uname -s over the link's pinned SSH trust; a Windows answer (Git Bash, MSYS, Cygwin, cmd or PowerShell) is reported with recovery steps.","Never revokes, disconnects or edits a link. A Windows Child needs ocx disconnect on itself, then ocx link revoke --force --yes on the Home, then ocx hub invite and ocx connect."],
+  },
   {
     command: ["remote-workspace","pair"],
     summary: "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
@@ -156,7 +166,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{ name: "--json", value: "boolean", summary: "Emit the status envelope as JSON." }],
     mutates: false,
     json: "envelope",
-    details: ["Reads /healthz plus local config; drives no management API route."],
+    details: ["Reads /healthz plus local config; drives no management API route.", "--json includes install: {method: bun|npm|pnpm|mise|source|standalone|unknown, evidence: {basis, mise?, error?}} from the updater's install detector."],
   },
   {
     command: ["resolve"],
@@ -225,7 +235,10 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--json","value":"boolean","summary":"Emit the provider list as JSON."},{"name":"--jsonl","value":"boolean","summary":"Emit one configured provider per JSON line."}],
     mutates: false,
     json: "envelope",
-    details: ["Local config and registry read, not GET /api/providers. --json and --jsonl are mutually exclusive."],
+    details: [
+      "Local config and registry read, not GET /api/providers. --json and --jsonl are mutually exclusive.",
+      "Each configured row carries active: false while this device is linked to a Home (a Remote Link Child or a Hub-mode client), whose providers serve instead; true when the row serves. Credential values are never printed.",
+    ],
     usage: "ocx provider list [--json|--jsonl]",
   },
   {

package/src/cli/capabilities-observe-system.ts

@@ -621,11 +621,11 @@ export const OBSERVE_SYSTEM_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["service", "status"], summary: "Inspect local service-manager status.",
-    usage: "ocx service status",
+    usage: "ocx service status [--json]",
     routes: [],
-    flags: [],
-    mutates: false, json: "none",
-    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API or JSON mode.", "Backend options apply only to install; other verbs use the installed backend."],
+    flags: [{"name": "--json", "value": "boolean", "summary": "Emit the passive service status document as JSON."}],
+    mutates: false, json: "payload",
+    details: ["Local OS service manager: macOS launchd, Linux systemd, Windows Task Scheduler or WinSW. No management API.", "--json is passive: schemaVersion 1 with installed, running, enabled, viable, stale, conflict, backend (launchd|systemd|schtasks|winsw|none), label, serving {probed, ok, port}, summary, logPath, ownershipLease and desktopLogin. It starts, stops, installs and repairs nothing.", "Backend options apply only to install; other verbs use the installed backend."],
   },
   {
     command: ["service", "uninstall"], summary: "Uninstall the local service.",

package/src/cli/codex-shim-autorestore.ts

@@ -26,6 +26,11 @@ export function skipsCodexShimAutoRestore(command: string | undefined, args: str
   // `resolve` is read-only inspection for embedding shells: a lookup made to populate
   // a consent surface must not trigger a shim repair side effect first.
   if (command === "resolve") return true;
+  // `service status --json` is a passive inventory read for peers such as GOAT: a shim repair
+  // before dispatch would change the installation it was asked only to describe.
+  // Flags may precede the verb (`ocx service --json status`), exactly as parseServiceArgs reads it.
+  if (command === "service" && args.includes("--json")
+    && args.slice(1).find(arg => !arg.startsWith("--")) === "status") return true;
   // The desktop's approval-bound stop must validate its snapshot before any unrelated
   // CLI repair changes the installation it was approved against.
   if (command === "stop" && args.some(arg => arg.startsWith("--expect-"))) return true;

package/src/cli/dispatch.ts

@@ -437,6 +437,32 @@ const commandRunners: Record<string, CommandRunner> = {
           }
         }
         await handleConnectedSyncCatalogWrite(result, restartScope);
+        if (result.applyRecordFailed) {
+          console.error("The Home's Codex settings were applied, but the apply record could not be written; the client runtime was not restarted. Run 'ocx sync' again.");
+          process.exitCode = 1;
+        }
+        // OCX-6: a link Child's runtime must have started after the apply it serves under.
+        if (link && result.appliedRecord) {
+          const { applyRestartMessage, restartRuntimeAfterApply } = await import("./link-apply-restart");
+          const { sameClientConnectionOwner } = await import("../client/state");
+          const applied = clientState.value;
+          const outcome = await restartRuntimeAfterApply(result.appliedRecord, {
+            restart: startWhenStopped => deps.handleProxyRestart(startWhenStopped),
+            recoveryStart: recovering => deps.handleRestartStartWhenStopped(recovering),
+            connectionUnchanged: () => {
+              const current = readClientConnectionState();
+              return current.kind === "connected" && sameClientConnectionOwner(current.value, applied)
+                && current.value.link?.linkId === applied.link?.linkId;
+            },
+          });
+          const message = applyRestartMessage(outcome);
+          if (outcome.kind === "failed" || outcome.kind === "connection-changed") {
+            console.error(message);
+            process.exitCode = 1;
+          } else {
+            console.log(message);
+          }
+        }
         // `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
         // drives app-server restarts, and one of those recording a failure must not be
@@ -876,6 +902,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleEffortCommand } = await import("./effort");
     return await handleEffortCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
+  fallback: async deps => {
+    const { handleFallbackCommand } = await import("./fallback");
+    return await handleFallbackCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
+  },
   agent: async deps => {
     const { handleAgentCommand } = await import("./agent");
     return await handleAgentCommand(deps.args.slice(1));

package/src/cli/fallback.ts

@@ -0,0 +1,127 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  terminalSafeText,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+export const FALLBACK_USAGE = `Usage:
+  ocx fallback status [--json]
+  ocx fallback off   [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]
+  ocx fallback on    [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]
+  ocx fallback clear [--kind model|provider|all] [--provider <name> | --route <selector> | --device <id|alias>] [--json]
+  ocx fallback local <on|off> --device <id|alias> [--json]`;
+
+type Switches = { model?: boolean; provider?: boolean };
+interface DeviceRow { id?: string; alias?: string; localFallback?: boolean; model?: boolean | null; provider?: boolean | null }
+interface EventRow { at?: string; site?: string; route?: string; kind?: string; from?: string; to?: string; trigger?: string; outcome?: string; scope?: string }
+interface FallbackState {
+  global?: { model?: boolean; provider?: boolean };
+  providers?: Record<string, Switches>;
+  routes?: Record<string, Switches>;
+  devices?: DeviceRow[];
+  last?: EventRow | null;
+}
+
+const onOff = (value: boolean | null | undefined): string => value === false ? "off" : value === true ? "on" : "inherit";
+
+function switchesLine(label: string, value: Switches): string {
+  const parts: string[] = [];
+  if (value.model !== undefined) parts.push("model " + onOff(value.model));
+  if (value.provider !== undefined) parts.push("provider " + onOff(value.provider));
+  return terminalSafeText(label) + ": " + parts.join(", ");
+}
+
+export function fallbackStatusLines(state: FallbackState): string[] {
+  const lines = [
+    "model fallback: " + (state.global?.model === false ? "off" : "on") + " (global)",
+    "provider fallback: " + (state.global?.provider === false ? "off" : "on") + " (global)",
+  ];
+  for (const [name, value] of Object.entries(state.providers ?? {})) lines.push(switchesLine("provider " + name, value));
+  for (const [name, value] of Object.entries(state.routes ?? {})) lines.push(switchesLine("route " + name, value));
+  for (const device of state.devices ?? []) {
+    const label = "device " + (device.id ?? "?") + (device.alias ? " (" + device.alias + ")" : "");
+    lines.push(terminalSafeText(label) + ": local fallback " + (device.localFallback ? "allowed" : "off")
+      + ", model " + onOff(device.model) + ", provider " + onOff(device.provider));
+  }
+  const last = state.last;
+  lines.push(last
+    ? terminalSafeText("last: " + last.at + " " + last.outcome + " " + last.kind + " fallback on " + last.route + ": "
+      + last.from + " -> " + last.to + " (" + last.trigger + ", " + last.scope + ")")
+    : "last: no fallback since this proxy started");
+  return lines;
+}
+
+function takeScope(args: string[]): { scope: "global" | "provider" | "route" | "device"; key?: string } {
+  const provider = takeOption(args, "--provider");
+  const route = takeOption(args, "--route");
+  const device = takeOption(args, "--device");
+  const given = [provider, route, device].filter(value => value !== undefined);
+  if (given.length > 1) throw new CliUsageError("use one of --provider, --route or --device", FALLBACK_USAGE);
+  if (provider !== undefined) return { scope: "provider", key: provider };
+  if (route !== undefined) return { scope: "route", key: route };
+  if (device !== undefined) return { scope: "device", key: device };
+  return { scope: "global" };
+}
+
+function takeKinds(args: string[]): Array<"model" | "provider"> {
+  const kind = takeOption(args, "--kind") ?? "all";
+  if (kind === "all") return ["model", "provider"];
+  if (kind === "model" || kind === "provider") return [kind];
+  throw new CliUsageError("--kind must be model, provider or all", FALLBACK_USAGE);
+}
+
+async function put(body: Record<string, unknown>, deps: RuntimeApiDeps): Promise<FallbackState> {
+  return await runtimeRequest<FallbackState>("/api/fallback", {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }, deps);
+}
+
+async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, FALLBACK_USAGE);
+  const state = await runtimeRequest<FallbackState>("/api/fallback", {}, deps);
+  printData(state, wantsJson, fallbackStatusLines(state));
+}
+
+async function setSwitch(argv: string[], value: boolean | null, deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const kinds = takeKinds(args);
+  const scope = takeScope(args);
+  rejectArgs(args, FALLBACK_USAGE);
+  const state = await put({ writes: kinds.map(setting => ({ ...scope, setting, value })) }, deps);
+  printData(state, wantsJson, fallbackStatusLines(state));
+}
+
+async function local(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const mode = args.shift();
+  if (mode !== "on" && mode !== "off") throw new CliUsageError("fallback local needs on or off", FALLBACK_USAGE);
+  const device = takeOption(args, "--device");
+  if (!device) throw new CliUsageError("fallback local needs --device <id|alias>", FALLBACK_USAGE);
+  rejectArgs(args, FALLBACK_USAGE);
+  const state = await put({ scope: "device", key: device, setting: "localFallback", value: mode === "on" }, deps);
+  printData(state, wantsJson, fallbackStatusLines(state));
+}
+
+export async function handleFallbackCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub, ...rest] = argv;
+    if (sub === undefined || sub === "status") await status(rest, deps);
+    else if (sub === "off") await setSwitch(rest, false, deps);
+    else if (sub === "on") await setSwitch(rest, true, deps);
+    else if (sub === "clear") await setSwitch(rest, null, deps);
+    else if (sub === "local") await local(rest, deps);
+    else throw new CliUsageError("unknown fallback command: " + sub, FALLBACK_USAGE);
+  });
+}

package/src/cli/help.ts

@@ -81,6 +81,7 @@ Usage:
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx message <sub>           Codex queued messages, explicit SSH peers and foreground ownership
   ocx effort [sub]            Inspect and configure reasoning effort caps and defaults
+  ocx fallback <sub>          Turn model or provider fallback off per scope; per-device local fallback
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx inspect <sub>           Effective config, catalog, analytics, pacing, client-config
   ocx route <sub>             Routing features (combo, policy)

package/src/cli/index.ts

@@ -167,7 +167,7 @@ import { startClientRuntimeUnderOwnershipLease } from "./client-start-fence";
 import { recoverStartStateUnderOwnershipLease } from "./start-owner-fence";
 import { handledSignalExitCode } from "../lib/handled-signal-exit";
 import { createLocalAttestationSecret } from "../lib/local-management-attestation";
-import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS, RESTART_REOBSERVE_RESERVE_MS } from "../lib/system-restart-contract";
 import { startServiceLogging } from "../service/logging";
 
 /**
@@ -941,7 +941,6 @@ async function handleTrayProxyStart(existingIsSuccess = true): Promise<boolean>
 const PROXY_RESTART_OBSERVE_MS = MEMORY_DRAIN_RESTART_MS + REPLACEMENT_READY_TIMEOUT_MS + 15_000;
 
 /** Reserve confirmation time within the shared restart deadline. */
-const RESTART_REOBSERVE_RESERVE_MS = 10_000;
 async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {

package/src/cli/link-apply-restart.ts

@@ -0,0 +1,72 @@
+/**
+ * After `ocx sync` applies the Home's Codex settings on a Remote Link Child, restart the Child's
+ * runtime so it started after the apply (OCX-6, P5).
+ *
+ * Idempotent: the record keeps its apply time while the settings digest is unchanged, so a runtime
+ * that already started after it is left alone, and a sync after a failed restart retries it. The
+ * restart is `ocx restart`'s own (`handleProxyRestart`); this module only decides whether to call
+ * it and never starts a runtime that was not running, except to recover one an accepted restart
+ * left absent.
+ */
+import type { HomeCodexSettingsRecord } from "../client/link-home";
+import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
+import type { ProxyRestartStartOutcome } from "./tray-proxy";
+
+export type ApplyRestartOutcome =
+  | { kind: "current" }
+  | { kind: "not-running" }
+  | { kind: "connection-changed" }
+  | { kind: "restarted" }
+  | { kind: "failed" };
+
+export interface ApplyRestartDeps {
+  findLive?: () => Promise<LiveProxy | null>;
+  /** Epoch ms the live client runtime reports as its start, or null when it reports none. */
+  readStartedAt?: (live: LiveProxy) => Promise<number | null>;
+  restart: (startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>) => Promise<boolean>;
+  recoveryStart: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>;
+  /** Still the connection this sync applied for (rechecked right before the restart). */
+  connectionUnchanged: () => boolean;
+}
+
+export async function readClientRuntimeStartedAt(live: LiveProxy, fetchImpl: typeof fetch = fetch): Promise<number | null> {
+  try {
+    const response = await fetchImpl(`http://${probeHostname(live.hostname)}:${live.port}/healthz`, {
+      headers: { accept: "application/json" },
+      redirect: "manual",
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!response.ok) return null;
+    const body = await response.json() as { pid?: unknown; startedAt?: unknown } | null;
+    if (body?.pid !== live.pid || typeof body.startedAt !== "string") return null;
+    const startedAt = Date.parse(body.startedAt);
+    return Number.isFinite(startedAt) ? startedAt : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function restartRuntimeAfterApply(record: HomeCodexSettingsRecord, deps: ApplyRestartDeps): Promise<ApplyRestartOutcome> {
+  const live = await (deps.findLive ?? (() => findLiveProxy()))();
+  if (!live || live.role !== "client") return { kind: "not-running" };
+  const appliedAt = Date.parse(record.appliedAt);
+  // A runtime that reports no start time predates OCX-6 and cannot prove it is current.
+  const startedAt = await (deps.readStartedAt ?? (target => readClientRuntimeStartedAt(target)))(live);
+  if (startedAt !== null && Number.isFinite(appliedAt) && startedAt >= appliedAt) return { kind: "current" };
+  if (!deps.connectionUnchanged()) return { kind: "connection-changed" };
+  const ok = await deps.restart(async recovering => recovering
+    ? deps.recoveryStart(true)
+    : { status: "skipped" });
+  return ok ? { kind: "restarted" } : { kind: "failed" };
+}
+
+/** One line for each outcome, printed by `ocx sync`. */
+export function applyRestartMessage(outcome: ApplyRestartOutcome): string {
+  switch (outcome.kind) {
+    case "current": return "Client runtime already started after this apply; no restart needed.";
+    case "not-running": return "No client runtime is running; the applied settings take effect when it starts.";
+    case "connection-changed": return "The connection changed during sync; the client runtime was not restarted. Run 'ocx sync' again.";
+    case "restarted": return "Client runtime restarted after applying the Home's settings.";
+    case "failed": return "The client runtime restart did not complete; the previous runtime keeps serving. If a background service or the desktop app owns it, restart it there; otherwise retry with 'ocx restart' or 'ocx sync'.";
+  }
+}

package/src/cli/link-child.ts

@@ -74,6 +74,7 @@ export async function readLinkHomeJson(
   context: LinkChildContext,
   path: string,
   deps: LinkHomeDeps = {},
+  init: { signal?: AbortSignal } = {},
 ): Promise<{ status: number; body: unknown }> {
   const token = readServiceApiTokenState();
   if (token.kind !== "present" || token.fingerprint !== context.connection.tokenFingerprint) {
@@ -81,12 +82,15 @@ export async function readLinkHomeJson(
   }
   let response: Response;
   try {
-    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`, {}, deps);
+    response = await fetchLinkHomeManagement(context.connection, token.token, path.startsWith("/") ? path : `/${path}`,
+      init.signal ? { signal: init.signal } : {}, 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) });
+  // A caller's deadline (the status report's 2 s) bounds the body read as well as the request.
+  const readSignal = init.signal ? AbortSignal.any([init.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+  const result = await readBoundedResponseBytes(response, { maxBytes: RESPONSE_MAX_BYTES, signal: readSignal });
   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;

package/src/cli/link-cleanup.ts

@@ -0,0 +1,95 @@
+/**
+ * `ocx link cleanup`: find Home-initiated Remote Link Children that run Windows and explain how to
+ * move each one to Hub mode. It never revokes or changes anything.
+ *
+ * Windows Children are refused at enrollment, but a link enrolled before that refusal existed keeps
+ * its record, key and reverse tunnel. Its record carries no platform, so this command asks the
+ * Child over the same pinned SSH trust the tunnel uses (`uname -s` through `sh`) and classifies the
+ * answer with `detectRemotePlatform` (a localized cmd or PowerShell refusal gets the fixed %OS% probe).
+ *
+ * The recovery order matters. An ordinary `ocx link revoke` runs `ocx disconnect` on the Child
+ * through the POSIX ocx prelude, which exits 125 on Windows, so for these Children the revoke must
+ * be forced after the Child disconnected itself.
+ */
+import { linkKnownHostsPath, linkStorePath } from "../link/paths";
+import { detectRemotePlatform, REMOTE_UNAME_ARGV, type RemotePlatform } from "../link/remote-platform";
+import { buildExecArgv } from "../link/ssh-argv";
+import { createSshRunner, sshFailureHint, sshRunnerErrorHint, type SshRunner } from "../link/ssh-runner";
+import { readLinkStore, type LinkStore } from "../link/store";
+import { CliUsageError, printData, rejectArgs, takeJsonFlag, takeOption } from "./runtime-api";
+
+const LINK_ID = /^lnk_[0-9a-f]{16}$/;
+const CHECK_TIMEOUT_MS = 30_000;
+
+export interface LinkCleanupDeps {
+  readStore?: () => LinkStore;
+  sshRunner?: SshRunner;
+  knownHostsFile?: string;
+}
+
+export interface LinkCleanupEntry {
+  linkId: string;
+  alias: string;
+  direction: LinkStore["links"][number]["direction"];
+  platform: RemotePlatform | "not_checked";
+  reason: string | null;
+  recovery: string[];
+}
+
+export function windowsChildRecovery(linkId: string, alias: string): string[] {
+  return [
+    `On ${alias}, run 'ocx disconnect' and then 'ocx restart' so it stops using this link.`,
+    `On this Home, run 'ocx link revoke --link-id ${linkId} --force --yes'. A plain revoke cannot disconnect a Windows Child remotely.`,
+    `Then connect ${alias} in Hub mode: run 'ocx hub invite' on a Hub and the printed 'ocx connect' command on ${alias}.`,
+  ];
+}
+
+async function checkPlatform(runner: SshRunner, alias: string, knownHostsFile: string): Promise<{ platform: RemotePlatform; reason: string | null }> {
+  try {
+    const result = await runner.run(buildExecArgv({ alias, argv: REMOTE_UNAME_ARGV, knownHostsFile }), { timeoutMs: CHECK_TIMEOUT_MS });
+    const platform = await detectRemotePlatform(runner, alias, knownHostsFile, result);
+    return { platform, reason: platform === "unknown" ? (sshFailureHint(result.stderr) ?? `ssh exited ${result.code}`) : null };
+  } catch (error) {
+    return { platform: "unknown", reason: sshRunnerErrorHint(error) ?? "ssh could not run" };
+  }
+}
+
+function humanLines(entries: LinkCleanupEntry[]): string[] {
+  if (entries.length === 0) return ["No links are recorded on this Home.", "Nothing was revoked or changed."];
+  const lines: string[] = [];
+  for (const entry of entries) {
+    const label = `${entry.linkId} (${entry.alias})`;
+    if (entry.platform === "windows") {
+      lines.push(`${label}: Windows Child. Remote Link does not support Windows Children; this link predates that refusal.`);
+      for (const [index, step] of entry.recovery.entries()) lines.push(`  ${index + 1}. ${step}`);
+    } else if (entry.platform === "posix") lines.push(`${label}: macOS or Linux Child; nothing to clean up.`);
+    else if (entry.platform === "not_checked") lines.push(`${label}: Child-initiated; this Home has no SSH route to check it.`);
+    else lines.push(`${label}: platform could not be checked (${entry.reason ?? "unknown"}); retry when it is reachable.`);
+  }
+  lines.push("Nothing was revoked or changed.");
+  return lines;
+}
+
+export async function runLinkCleanup(args: string[], deps: LinkCleanupDeps, usage: string): Promise<void> {
+  const wantsJson = takeJsonFlag(args);
+  const linkId = takeOption(args, "--link-id");
+  if (linkId !== undefined && !LINK_ID.test(linkId)) throw new CliUsageError("cleanup --link-id must be a valid link id", usage);
+  rejectArgs(args, usage);
+  const store = (deps.readStore ?? (() => readLinkStore(linkStorePath())))();
+  const records = linkId === undefined ? store.links : store.links.filter(link => link.id === linkId);
+  if (linkId !== undefined && records.length === 0) throw new CliUsageError(`No link ${linkId} is recorded on this Home.`, usage);
+  const runner = deps.sshRunner ?? createSshRunner();
+  const knownHostsFile = deps.knownHostsFile ?? linkKnownHostsPath();
+  const entries: LinkCleanupEntry[] = [];
+  // One at a time: each check is a bounded SSH command, and order keeps the report stable.
+  for (const record of records) {
+    const checked = record.direction === "hub-initiated"
+      ? await checkPlatform(runner, record.alias, knownHostsFile)
+      : { platform: "not_checked" as const, reason: null };
+    entries.push({
+      linkId: record.id, alias: record.alias, direction: record.direction, ...checked,
+      recovery: checked.platform === "windows" ? windowsChildRecovery(record.id, record.alias) : [],
+    });
+  }
+  printData({ links: entries, changed: false }, wantsJson, humanLines(entries));
+}

package/src/cli/link-enrollment.ts

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { assertSshAlias } from "../link/ssh-argv";
+import { windowsChildRefusal } from "../link/remote-platform";
 import { CliUsageError, RuntimeApiError, runtimeBaseUrl, rejectArgs, takeJsonFlag, takeOption, printData } from "./runtime-api";
 import type { LinkCliDeps } from "./link";
 
@@ -83,6 +84,9 @@ export async function runLinkEnrollment(command: "probe" | "add", args: string[]
   catch (error) {
     if (error instanceof RuntimeApiError && record(error.body)) {
       const code = record(error.body.error) ? error.body.error.code : undefined;
+      // Refused at probe or confirm, before any key or tunnel: point at Hub mode, not at a phase.
+      // A residual response comes after key issuance; it keeps its Child recovery below.
+      if (code === "remote_platform_unsupported" && error.body.residual !== true) throw new Error(windowsChildRefusal(alias));
       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 : ""));