fix(link): preserve orphan token files for confirmed recovery

devlog/_plan/261107_orphaned_child_link/010_design.md

@@ -37,3 +37,16 @@ therefore does not establish that the present token belongs to the sidecar, and
 followed by compare-and-swap alone only proves that the token did not change during cleanup. A
 recovery implementation needs an independent owner witness and a safe path for legacy orphans;
 it must not interpret sidecar presence as proof of token ownership.
+
+## Explicit legacy recovery
+
+The operator can instead authorize preservation of the unowned files explicitly with
+`ocx disconnect --orphaned-token --yes`. This is a recovery action, not a connection
+reconstruction: it moves the service token and any rotation backup to a private directory and
+prints its location and restoration guidance. Under the existing start ownership lease and client
+lifecycle lock, check that no client runtime is live, treating unknown as a refusal; under the
+config mutation lock recheck disconnected state, pending-connect marker, disconnect receipt, and
+token file identities immediately before moving. Hub role, admission-secret use and installed or
+unverified service definitions refuse recovery. On Windows, private hard links retain file identity
+while source handles close before rename. Refuse unsafe paths and preserve all backup bytes if any
+part fails. The normal disconnect, sync and enrollment paths retain their ownership checks.

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

@@ -77,6 +77,8 @@ On a Child, `GET /healthz` only says that OpenCodex is running. `GET /readyz` (a
 
 The reason `client_state_changed` means the running Child's saved connection is missing or now names another owner or link. Its machine and link status endpoints also return `503` with this reason. Stop or restart the Child and check its connection before re-linking; this readiness result does not itself disconnect the relay.
 
+If `ocx connect status --json` reports `disconnected` but a leftover service token prevents a new link, inspect the situation on the Child. After confirming that preserving the existing token files is intended, run `ocx disconnect --orphaned-token --yes`. It refuses a connected or pending client and any live client runtime or unverified runtime state. It also refuses a Hub, a non-loopback bind, a configured or matching admission secret, and an installed or unverified service: these can use the token for admission. On a Hub, manage the credential through the Hub service; otherwise inspect the bind, API keys, token environment and `ocx service status`, and remove or migrate a service only if intended before retrying. It moves the token and any rotation backup into a private directory under the OpenCodex config directory, prints the location, and does not infer that either token belonged to the link. On Windows, recovery requires hard-link support to preserve file identity while closing handles; if it reports an incomplete backup, inspect the reported directory and original files before retrying. Stop OpenCodex to restore: move the saved files back only when the original names are absent. The command does not revoke a Home key or restore missing client configuration.
+
 To confirm which Home is serving a Child, compare the `x-opencodex-served-by` header on the Child's `GET /v1/models` with the `instanceId` in the Home's `GET /healthz`. The Child passes the Home's header through unchanged, so the two match while the link works. The value is an opaque id, never a hostname; see [Home identity and the served-by header](/reference/management-api/#home-identity-and-the-served-by-header).
 
 ## What a Child shows and manages
@@ -89,6 +91,8 @@ A Child runs on the Home's providers, accounts and settings, so the Home is wher
   When OpenCodex Desktop or a background service supervises the Child runtime, sync succeeds after applying settings and reports that the runtime restart is deferred. The settings take effect when that supervisor restarts the runtime: use **Quit** in the OpenCodex tray menu, then reopen OpenCodex, or run `ocx service restart` for a service.
 - **CLI.** Commands that only read, such as `ocx account list`, `ocx provider quota` and `ocx usage`, read the Home. They show what the Home has already observed: a read from a Child never makes the Home probe a provider, refresh a token or start a process, so quota and account details are as fresh as the Home's own activity keeps them. Reads that only exist to run provider discovery or a forced refresh, such as `ocx models live`, `ocx models preset show` and `ocx account list --quota`, are refused like changes. Commands that change configuration are refused with one message that names the Home and the link and says no request was sent. `ocx status` describes the Home and the link. `ocx provider list` and `ocx config get` still show this computer's own configuration, labelled as local and inactive while the computer is linked. `ocx config set`, `ocx config unset` and `ocx config import` still write locally, each with the same note, and `ocx provider add`, `remove` and `set-default` are refused because those providers are not used while linked.
 
+An import that would replace or remove an active client connection is refused. Disconnect that client first, or import a file that preserves its connection record exactly.
+
 These reads need an OpenCodex version with the Remote Link management relay on both the Home and the Child. An older Home answers with a message asking you to upgrade it.
 
 ## Remove a Child

scripts/generate-ocx-skill-surface.ts

@@ -22,7 +22,7 @@ const DOMAINS = [
   { name: "agents-routing", roots: ["agent", "combo", "route", "fallback", "v2", "effort", "memory", "message", "advisor"] },
   { name: "integrations", roots: ["claude", "integration", "commandcode", "grok", "codex-shim"] },
   { name: "observe-system", roots: ["companion", "usage", "logs", "storage", "inspect", "system", "observe", "debug", "export", "import", "cost", "update", "config", "tray"] },
-  { name: "access-remote", roots: ["link", "remote-workspace", "hub", "connect", "api", "access"] },
+  { name: "access-remote", roots: ["link", "remote-workspace", "hub", "connect", "disconnect", "api", "access"] },
   { name: "lab", roots: ["lab"] },
 ];
 

skills/ocx/references/01_management_surface.md

@@ -31,7 +31,7 @@ These answer in the CLI head and never reach the proxy, so they work with nothin
 | [agents-routing](01_surface_agents-routing.md) | 68 |
 | [integrations](01_surface_integrations.md) | 41 |
 | [observe-system](01_surface_observe-system.md) | 99 |
-| [access-remote](01_surface_access-remote.md) | 33 |
+| [access-remote](01_surface_access-remote.md) | 34 |
 | [lab](01_surface_lab.md) | 21 |
 
 ## Read-only capabilities
@@ -1367,6 +1367,10 @@ Original invocation order. These headings preserve links to the previous single-
 
 [Read-oriented task](01_surface_observe-system.md#ocx-companion-timeline)
 
+### `ocx disconnect`
+
+[State-changing task](01_surface_access-remote.md#ocx-disconnect)
+
 ### `ocx hub disable`
 
 [State-changing task](01_surface_access-remote.md#ocx-hub-disable)
@@ -1521,6 +1525,6 @@ Original invocation order. These headings preserve links to the previous single-
 
 ## Counts
 
-- declared capabilities: 368
-- of those, state-changing: 226
+- declared capabilities: 369
+- of those, state-changing: 227
 - head-resolved invocations: 2

skills/ocx/references/01_surface_access-remote.md

@@ -8,7 +8,7 @@
 Use these declarations to choose a task, then check its flags and authority before execution.
 Non-mutating probes may still contact providers, consume quota or refresh caches.
 
-Declared capabilities: 33.
+Declared capabilities: 34.
 
 ### `ocx link probe`
 
@@ -326,6 +326,26 @@ State-changing: yes. JSON mode: `payload`.
 - A bare invocation reads and never writes.
 - A setting flag changes the operator's config; run it only when the operator asks for that change.
 
+### `ocx disconnect`
+
+Usage: `ocx disconnect [--keep-catalog] [--json] | ocx disconnect --orphaned-token --yes [--json]`
+
+Disconnect a client or preserve orphaned token files for recovery.
+
+State-changing: yes. JSON mode: `payload`.
+
+Drives no management route.
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--keep-catalog` | boolean | Keep the connected client's catalog during ordinary disconnect. |
+| `--orphaned-token` | boolean | Preserve unowned service-token files in a private backup when disconnected. |
+| `--yes` | boolean | Explicitly confirm orphan-token recovery; requires --orphaned-token. |
+| `--json` | boolean | Emit the local result and backup location as JSON. |
+
+- Orphan recovery requires a disconnected durable state, no pending connect or disconnect, no Hub or admission-secret use, no installed or unverified service, and verified absence of a client runtime. It preserves rather than deletes token files and does not establish their ownership.
+- If refused, inspect the bind, API keys, token environment and service status; manage a Hub secret through its service. Stop OpenCodex and move saved files back only when their original names are absent. Never print their contents.
+
 ### `ocx hub disable`
 
 Usage: `ocx hub disable [--revoke-clients --client-key <id> ...] [--json]`

skills/ocx/references/05_remote_hub.md

@@ -370,6 +370,16 @@ It ends a browser session; it does not disconnect a client or revoke a key.
 
 ### When `disconnect` refuses, that is the safety property
 
+When the operator has explicitly authorized recovery of a disconnected installation with a
+leftover token, `ocx disconnect --orphaned-token --yes` preserves the service-token files in a
+private backup. It refuses pending or connected client state, a Hub, admission-token use,
+installed or unverified service definitions, and live or unverified client runtimes. Inspect the
+bind, API keys, token environment and `ocx service status`; manage a Hub credential through the
+Hub service. It does not prove the tokens belonged to a link or restore lost connection settings.
+Report the printed backup location; to restore, stop OpenCodex and move the saved files back only
+if their original names are absent. Never read or print their contents. Do not add `--yes` without
+the operator's explicit authorization.
+
 Do not work around these. Each one means unwinding would damage state that
 `disconnect` cannot prove is safe to touch.
 

src/cli/capabilities-access-remote.ts

@@ -2,6 +2,19 @@ import type { Capability } from "./capability-types";
 
 /** Verified existing handlers only; local operations never claim management routes. */
 export const ACCESS_REMOTE_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["disconnect"], summary: "Disconnect a client or preserve orphaned token files for recovery.",
+    usage: "ocx disconnect [--keep-catalog] [--json] | ocx disconnect --orphaned-token --yes [--json]",
+    routes: [],
+    flags: [
+      { name: "--keep-catalog", value: "boolean", summary: "Keep the connected client's catalog during ordinary disconnect." },
+      { name: "--orphaned-token", value: "boolean", summary: "Preserve unowned service-token files in a private backup when disconnected." },
+      { name: "--yes", value: "boolean", summary: "Explicitly confirm orphan-token recovery; requires --orphaned-token." },
+      { name: "--json", value: "boolean", summary: "Emit the local result and backup location as JSON." },
+    ],
+    mutates: true, json: "payload",
+    details: ["Orphan recovery requires a disconnected durable state, no pending connect or disconnect, no Hub or admission-secret use, no installed or unverified service, and verified absence of a client runtime. It preserves rather than deletes token files and does not establish their ownership.", "If refused, inspect the bind, API keys, token environment and service status; manage a Hub secret through its service. Stop OpenCodex and move saved files back only when their original names are absent. Never print their contents."],
+  },
   {
     command: ["hub", "disable"], summary: "Return a hub to standalone in one validated config write.",
     usage: "ocx hub disable [--revoke-clients --client-key <id> ...] [--json]",

src/cli/codex-shim-autorestore.ts

@@ -24,6 +24,8 @@ export function skipsCodexShimAutoRestore(command: string | undefined, args: str
   if (command === "update" && isOrchestratedUpdateArgv(args)) return true;
   if (command === "sync") return true;
   if (command === "status" || command === "doctor") return true;
+  // Explicit orphan-token recovery must not mutate Codex before its guards run.
+  if (command === "disconnect" && args.includes("--orphaned-token")) return true;
   // The launcher owns shim handoff after classifying routing, including native fast paths.
   if (command === "codex") return true;
   // Exec admission only observes the selected target; it must never repair a shim first.

src/cli/config-command.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { clearCodexAccountPin } from "../codex/account-priority";
-import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
+import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate, withConfigMutationLockSync } from "../config";
+import { readClientConnectionState } from "../client/state";
 import { getConfigDir, withConfigDirHardeningSettled } from "../config/paths";
 import { readCliConfigForMutation } from "./config-mutation";
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
@@ -331,7 +332,15 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       rejectArgs(args, USAGE);
       await withConfigDirHardeningSettled(getConfigDir(), () => {
         readCliConfigForMutation();
-        saveConfig(validate(loadInput(path)));
+        const imported = validate(loadInput(path));
+        withConfigMutationLockSync(() => {
+          const client = readClientConnectionState();
+          if (client.kind === "connected" && (imported.runtimeRole !== "client"
+            || JSON.stringify(imported.client) !== JSON.stringify(client.value))) {
+            throw new Error("config import refused: disconnect the active client before replacing its connection");
+          }
+          saveConfig(imported);
+        });
       });
       printData({ ok: true, source: path }, wantsJson, [`Imported config from ${path}. Restart or run ocx sync if needed.`]);
       return;

src/cli/connect.ts

@@ -20,6 +20,7 @@ import { teardownClientLink } from "../client/link-teardown";
 import { reapOrphanTunnel } from "../client/link-tunnel";
 import { readServiceApiTokenState } from "../lib/service-secrets";
 import type { ClientLifecycleLockDeps } from "../client/lifecycle-lock";
+import { recoverOrphanedTokens, type OrphanTokenRecoveryDeps } from "../client/orphan-token-recovery";
 import { linkKnownHostsPath } from "../link/paths";
 import { createSshRunner, type SshRunner } from "../link/ssh-runner";
 import type { OrphanTunnelResult } from "../client/link-tunnel";
@@ -83,7 +84,8 @@ export const CONNECT_USAGE = `Usage:
   ocx connect revoke --admin-token-stdin [--json]`;
 
 export const DISCONNECT_USAGE = `Usage:
-  ocx disconnect [--keep-catalog] [--json]`;
+  ocx disconnect [--keep-catalog] [--json]
+  ocx disconnect --orphaned-token --yes [--json]`;
 
 export type ClientConnectionStatus = {
   state: "disconnected" | "connected" | "invalid" | "mismatched";
@@ -529,13 +531,26 @@ export async function handleConnectCommand(argv: string[], deps: ClientCommandDe
 
 export async function handleDisconnectCommand(
   argv: string[],
-  deps: Pick<ClientCommandDeps, "lifecycleLockDeps" | "linkTeardownDeps"> = {},
+  deps: Pick<ClientCommandDeps, "lifecycleLockDeps" | "linkTeardownDeps"> & { orphanRecoveryDeps?: OrphanTokenRecoveryDeps } = {},
 ): Promise<number> {
   return runCliAction(async () => {
     const args = [...argv];
     const keepCatalog = takeFlag(args, "--keep-catalog");
     const wantsJson = takeFlag(args, "--json");
+    const orphanedToken = takeFlag(args, "--orphaned-token");
+    const yes = takeFlag(args, "--yes");
     rejectArgs(args, DISCONNECT_USAGE, { redactValues: true });
+    if (orphanedToken) {
+      if (!yes || keepCatalog) throw new CliUsageError("--orphaned-token requires --yes and cannot be combined with --keep-catalog", DISCONNECT_USAGE);
+      const backup = await recoverOrphanedTokens({ ...deps.orphanRecoveryDeps, lifecycleLockDeps: deps.lifecycleLockDeps });
+      const restore = "Stop OpenCodex and move the saved files back into its config directory only if the destination names are absent.";
+      printData({ ...backup, restore }, wantsJson, [
+        `Preserved token files in ${backup.backupDir}.`,
+        `To restore: ${restore}`,
+      ]);
+      return;
+    }
+    if (yes) throw new CliUsageError("--yes requires --orphaned-token", DISCONNECT_USAGE);
     const teardown = await teardownClientLink({
       readSidecar: readClientLinkState,
       connectedLinkId: () => {

src/client/connect.ts

@@ -556,6 +556,9 @@ function assertConnectingState(expectedTokenFingerprint?: string): void {
   const token = readServiceApiTokenState();
   if (expectedTokenFingerprint === undefined ? token.kind !== "absent"
     : token.kind !== "present" || token.fingerprint !== expectedTokenFingerprint) {
+    if (expectedTokenFingerprint === undefined && token.kind === "present") {
+      throw new Error("client_token_changed: if this is not a Hub and no admission secret or installed service uses the token, inspect it and use ocx disconnect --orphaned-token --yes before retrying");
+    }
     throw new Error("client_token_changed");
   }
 }
@@ -1121,7 +1124,7 @@ export async function disconnectClient(
         writeDesktopDisconnectReceipt(held, previous, receipt);
       }
     } else if (state.kind !== "disconnected" || !receipt || !disconnectAtLeast(receipt, "clearing_connection")) {
-      throw new Error("disconnect refused: no recoverable connected state");
+      throw new Error("disconnect refused: no recoverable connected state; if this is not a Hub and no admission secret or installed service uses the token, inspect it and use ocx disconnect --orphaned-token --yes");
     }
     if (!receipt || receipt.keepCatalog !== keepCatalog) throw new Error("client_disconnect_options_changed");
     return { receipt, connection };