fix(link): Children owned by the desktop app or a service can leave and re-link from the Home

bin/ocx.mjs

@@ -576,6 +576,8 @@ async function runPackageManagerSelfUpdate(manager, child) {
     }
     const env = mutationChildEnvironment();
     delete env.OCX_SERVICE;
+    // Not launched by a supervisor: none of its markers (src/lib/supervisor-markers.ts) may ride along.
+    for (const name of ["OCX_DESKTOP_SUPERVISED", "OCX_SERVICE_MANAGED", "OCX_WINDOWS_WRAPPER_PROTOCOL"]) delete env[name];
     // The restarted proxy is an ordinary owner; only a sibling's own replacement carries this.
     delete env.OCX_SIBLING_OF_PORT;
     delete env.OCX_SIBLING_HANDOFF_NONCE;

docs-site/src/content/docs/guides/remote-link.md

@@ -109,6 +109,8 @@ ocx disconnect   # or ~/.cache/opencodex/bin/ocx-child detach on a lightweight C
 
 To disconnect a Child-initiated link, run `ocx disconnect` on the Child. It disconnects the client tunnel and revokes the link on Home over SSH. If Home revocation fails, it prints: `Home revoke failed; run ocx link revoke --link-id <linkId> on the home.`
 
+On a full OpenCodex Child, `ocx disconnect` also restarts a client runtime that is still running, so the Child is serving standalone OpenCodex when the command returns. If that restart does not complete, the command exits non-zero and prints advice for the state it observed: `ocx restart` on the Child when the same runtime still serves the old connection; `ocx service restart` when a service that cannot be shown to relaunch the runtime refused the restart; and inspection with `ocx status` and `ocx connect status` when a new connection is in use, the client state cannot be read, or a different or unknown runtime answers. A client runtime whose connection was removed accepts `ocx restart` when its owner can relaunch it: the OpenCodex desktop app, or a background service that is enabled and running, starts the standalone replacement, so the same command works over SSH with nobody at the Child's screen. A service that cannot be shown to relaunch it (for example a unit started by hand while disabled) keeps the runtime and the command says to run `ocx service restart`. A runtime that carries only `OCX_SERVICE=1` (a service installed before 2.49, or a proxy started by `ocx claude`, `ocx codex` or `ocx opencode`) is not changed by this: `ocx disconnect` does not restart it, and `ocx restart` refuses while its service is viable, as before. The same holds for a client runtime started by an OpenCodex version before this change: `ocx disconnect` restarts a runtime only after it has been restarted once on the new version (an update's own restart, the desktop app restarting it, `ocx service restart`, or `ocx restart`).
+
 ## Troubleshooting
 
 When a step fails, the dashboard shows the reason and, when SSH reported one, a short sanitized hint from its last non-empty error line under the message. Remote-shell errors can appear there even when the remote shell emits non-UTF-8 text; OpenCodex removes terminal controls, link keys and URL queries and limits the hint's length.
@@ -276,6 +278,8 @@ A Windows x64 Child needs OpenSSH Server, Windows PowerShell and either standalo
 
 Run `ocx link cleanup` on Home to inspect recorded Child platforms without changing them. Current Home releases disconnect Windows Children through PowerShell. If a remote disconnect fails, resolve the reported shell or installation error and retry; **Remove here only** remains an explicit recovery action that can leave the Child needing a local disconnect.
 
-Restart waits for running turns and may take several minutes. Success requires the restarted Child to serve the client role and relay a fresh complete catalog to this Home. SSH setup has a bounded allowance derived from measured latency; relay verification starts after restart with its own 15-second window. Errors name the failing phase. If an error reports residual Child configuration, run `ocx disconnect` and `ocx restart` on that Child before retrying. Home cleanup alone does not restore Child configuration. A CLI timeout reports an uncertain outcome; inspect Home `ocx link status` and Child `ocx connect status` first.
+Restart waits for running turns and may take several minutes. Success requires the restarted Child to serve the client role and relay a fresh complete catalog to this Home. SSH setup has a bounded allowance derived from measured latency; relay verification starts after restart with its own 15-second window. Errors name the failing phase and end with the error code. If an error reports residual Child configuration, run `ocx disconnect` and `ocx restart` on that Child before retrying. Home cleanup alone does not restore Child configuration. A CLI timeout reports an uncertain outcome; inspect Home `ocx link status` and Child `ocx connect status` first.
+
+A `Child restart preflight` failure (`child_restart_unsupported`) names what the Child is and the Child command that fixes it. Typical causes are a Child still linked to a Home (run `ocx disconnect`, then `ocx restart`), a Child still serving a client runtime (`ocx restart`), a Hub (`ocx hub disable`), a runtime without restart support (update OpenCodex), and a runtime answering on a port other than its configured one (`ocx restart`).
 
 On a Home-initiated Child, `ocx link status` reports role `child`, link identity and tunnel port from its saved connection even though its Home-side link store is empty. Locally unobserved tunnel state is `idle`. `ocx status` calls the peer a Remote Link Home. When Home runs in Hub mode, status reads its supported projection through the local Child relay. A standalone Home reports that it does not publish Hub state. Child-initiated tunnel identity comes from its valid sidecar; unreadable evidence does not claim a direction.

scripts/test-layout/layout.json

@@ -1820,7 +1820,7 @@
     "terminal-continuation-owner-rotation.test.ts": "adapters",
     "terminal-guard-server.test.ts": "server",
     "terminal-guard.test.ts": "server",
-    "test-home-guard.test.ts": "ci-workflows", "test-home-guard-unpreloaded.test.ts": "ci-workflows",
+    "test-home-guard.test.ts": "ci-workflows", "codex-home-sandbox.test.ts": "ci-workflows", "test-home-guard-unpreloaded.test.ts": "ci-workflows",
     "test-run-lock-generation.test.ts": "ci-workflows", "test-runner.test.ts": "ci-workflows", "test-runner-bun.test.ts": "ci-workflows", "test-runner-spawnsync-finalizer.test.ts": "ci-workflows", "test-sandbox-cleanup.test.ts": "ci-workflows", "test-temp-quarantine.test.ts": "ci-workflows",
     "thought-signature-credential-scope.test.ts": "responses",
     "token-estimate.test.ts": "lib",
@@ -1987,7 +1987,7 @@
     "zz-ci-storage-policy-isolation.test.ts": "ci-workflows",
     "zz-pr-coderabbit-readiness-revalidation.test.ts": "ci-workflows",
     "injection-link-websocket.test.ts": "codex-integration",
-    "cli-link.test.ts": "cli", "cli-link-enrollment.test.ts": "cli", "link-apply-restart.test.ts": "cli", "link-child-parity.test.ts": "server", "restart-replacement-not-ready.test.ts": "server",
+    "cli-link.test.ts": "cli", "cli-link-enrollment.test.ts": "cli", "link-apply-restart.test.ts": "cli", "disconnect-runtime.test.ts": "cli", "link-child-parity.test.ts": "server", "restart-replacement-not-ready.test.ts": "server",
     "link-management-routes.test.ts": "server", "link-enrollment.test.ts": "server",
     "web-search-run-turn-loop.test.ts": "web-search",
     "responses-run-turn-web-search.test.ts": "responses",

src/adapters/cursor/native-exec-desktop.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { withoutSupervisorMarkers } from "../../lib/supervisor-markers";
 import { shellInvocation } from "../../lib/win-exec";
 import { create } from "@bufbuild/protobuf";
 import {
@@ -120,7 +121,7 @@ function runExternalJson(command: string, payload: unknown, config: DesktopExecu
     const inv = shellInvocation(command);
     const child = spawn(inv.file, inv.args, {
       cwd: config.cwd,
-      env: config.env ? { ...process.env, ...config.env } : process.env,
+      env: withoutSupervisorMarkers(config.env ? { ...process.env, ...config.env } : process.env),
       stdio: ["pipe", "pipe", "pipe"],
       ...inv.options,
     });

src/adapters/cursor/native-exec-shell.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { withoutSupervisorMarkers } from "../../lib/supervisor-markers";
 import { resolve } from "node:path";
 import { foregroundShellUnavailableMessage, runForegroundShell, type CursorForegroundShellOwner } from "./native-foreground-shell";
 import { create } from "@bufbuild/protobuf";
@@ -430,7 +431,7 @@ export function backgroundShellSpawnExec(execMsg: ExecServerMessage, sessionId:
   if (!admissionLease) return backgroundShellSpawnError(execMsg, args.command, cwd, "background shell limit reached");
   let child: ChildProcessWithoutNullStreams;
   try {
-    child = backgroundShellRuntime.spawn(args.command, { cwd, shell: true });
+    child = backgroundShellRuntime.spawn(args.command, { cwd, shell: true, env: withoutSupervisorMarkers(process.env) });
   } catch (err) {
     admissionLease.release();
     return backgroundShellSpawnError(execMsg, args.command, cwd, errorText(err));

src/claude/desktop-remote-store.ts

@@ -52,6 +52,9 @@ function recordedGenerations(io: StoreIO, owner: DesktopRemoteOwner): string[] {
 
 export function inspectRemoteDesktopStore(owner: DesktopRemoteOwner): {
   kind: "absent" | "active" | "pending" | "restored" | "legacy_current_connection" | "conflict" | "unsafe";
+  /** Set for the one refusal a person can clear: the store folder exists with nothing in it OpenCodex reads. */
+  reason?: "root_without_state";
+  path?: string;
 } {
   try {
     parseOwner(owner);
@@ -71,7 +74,7 @@ export function inspectRemoteDesktopStore(owner: DesktopRemoteOwner): {
       if (projectionHash(file?.value ?? null) !== bundle.state.lastProjectionHash) return { kind: "conflict" };
       return { kind: bundle.state.phase === "restored" ? "restored" : "active" };
     }
-    if (existsSync(bundle.paths.root) && !receipt(io)) throw new DesktopStoreError("unsafe");
+    if (existsSync(bundle.paths.root) && !receipt(io)) return { kind: "unsafe", reason: "root_without_state", path: bundle.paths.root };
     const legacy = locateLegacy(io, owner, serviceGenerations());
     if (legacy) currentConnection(owner);
     return { kind: legacy ? "legacy_current_connection" : "absent" };

src/cli/claude.ts

@@ -37,6 +37,17 @@ import { desktopProfileWireAlias, legacyDesktopProfileWireAlias } from "../claud
 import { inspectDesktopFirstParty } from "../claude/desktop-first-party";
 import { isClaudeInterceptProxyUrl, type ClaudeInterceptSettingsState } from "../claude/intercept/settings";
 import { withoutSiblingMarker } from "../codex/sibling-start";
+import { withoutSupervisorMarkers } from "../lib/supervisor-markers";
+
+/**
+ * The environment of the detached `ocx start` that `ocx claude` launches (the spawn adds the runtime
+ * provenance stamp): an ordinary owner. It
+ * carries OCX_SERVICE=1 but no service manager's marker, which is how a restart tells it apart from
+ * a manager-launched process (src/client/runtime-restart.ts classifyClientRestartSupervisor).
+ */
+export function claudeProxyStartEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return withoutSupervisorMarkers(withoutSiblingMarker({ ...base, OCX_SERVICE: "1" }));
+}
 
 export interface ClaudeLaunchEnv {
   [key: string]: string | undefined;
@@ -532,7 +543,7 @@ export async function ensureProxyForClaude(deps: ClaudeProxyEnsureDeps = {}): Pr
     stdio: "ignore",
     windowsHide: true,
     // An ordinary owner: a stray sibling marker would otherwise mark it before any probe.
-    env: withProcessRuntimeProvenance(withoutSiblingMarker({ ...process.env, OCX_SERVICE: "1" })),
+    env: withProcessRuntimeProvenance(claudeProxyStartEnv()),
   });
   child.unref();
   const deadline = Date.now() + 8_000;

src/cli/codex-launcher.ts

@@ -38,6 +38,7 @@ import { attestCodexRuntime, codexCredentialDestinationIsTrusted, resolveCodexLa
 import { codexCommandCanBypass, CODEX_UNVERIFIED_SHIM } from "./codex-launch-command";
 import { codexTokenArgsAreSafe, codexTokenEnvironmentIsSafe } from "./codex-launch-policy";
 import { codexTokenWithheldDiagnostic, type CodexTokenRefusal, type CodexTokenRefusalReporter } from "./codex-launch-diagnostics";
+import { withoutSupervisorMarkers } from "../lib/supervisor-markers";
 
 export interface CodexLaunchEnv {
   [key: string]: string | undefined;
@@ -115,7 +116,8 @@ export function codexProxyStartEnv(base: CodexLaunchEnv = process.env): CodexLau
   const withTokenFile = stripped.OPENCODEX_API_AUTH_TOKEN?.trim()
     ? stripped
     : { ...stripped, OCX_API_TOKEN_FILE: serviceApiTokenFilePath() };
-  return { ...withTokenFile, OCX_SERVICE: "1" } as CodexLaunchEnv;
+  // A shell a supervised runtime handed to a tool carries its supervisor's markers; this proxy is not its.
+  return withoutSupervisorMarkers({ ...withTokenFile, OCX_SERVICE: "1" }) as CodexLaunchEnv;
 }
 
 export type CodexProxyEnsureDeps = {

src/cli/connect.ts

@@ -599,7 +599,13 @@ export async function handleDisconnectCommand(
       knownHostsFile: deps.linkTeardownDeps?.knownHostsFile ?? linkKnownHostsPath(),
       timeoutMs: deps.linkTeardownDeps?.timeoutMs,
     });
-    const result = await disconnectClient({ keepCatalog }, deps);
+    const result = await disconnectClient({ keepCatalog }, deps).catch((error: unknown) => {
+      // The bare code left a Home-driven leave with nothing to act on; the remedy already exists.
+      if (error instanceof Error && error.message === "client_catalog_ownership_changed") {
+        throw new Error("client_catalog_ownership_changed: the Codex model catalog (opencodex-catalog.json in the Codex home) matches neither the catalog this connection wrote nor the one recorded before it connected, so something changed it after connecting and disconnect will not overwrite it. To disconnect and leave that file as it is, run: ocx disconnect --keep-catalog");
+      }
+      throw error;
+    });
     const payload = {
       ...result,
       homeRevoke: teardown.homeRevoke,

src/cli/desktop-runtime-guidance.ts

@@ -19,7 +19,7 @@ export function duplicateRuntimeMessage(
   if (pid != null && latch.observe(evidence)) {
     const supervisor = evidence.kind === "desktop" ? `, ${evidence.app}` : "";
     return `OpenCodex Desktop supervises the running proxy (pid ${pid}${supervisor}, port ${port}). `
-      + "Use the running proxy, or quit OpenCodex before starting it from this CLI.";
+      + "Use the running proxy (restart it with 'ocx restart', re-point Codex with 'ocx sync'), or quit OpenCodex before starting it from this CLI.";
   }
   return `⚠️  Proxy already running (PID ${pid ?? "unknown"}, port ${port}). Use 'ocx stop' first.`;
 }