fix(link): a refused Child disconnect rolls back, Codex-edited config.toml no longer blocks it, desktop refusals name their cause

devlog/_plan/261111_child_disconnect_followups/000_plan.md

@@ -0,0 +1,14 @@
+# Child disconnect follow-ups (O7, O8, O9, O10)
+
+Stacked on #8529 (`fix/child-restart-desktop-owned`). Field reports: six Remote Link Children moved to new SSH aliases on 2026-11-11, OpenCodex 2.100.2.
+
+| Unit | Doc | Kind | Outcome wanted |
+|---|---|---|---|
+| O8 | 010 | defect, test-first | a refused disconnect never leaves state that stops the runtime from starting; a retry finishes or rolls back from `prepared`, including a receipt already stuck on 2.100.2 |
+| O9 | 020 | defect, test-first | disconnect succeeds when Codex edited config.toml after injection and no OpenCodex line remains; never overwrites Codex or user lines; keeps the journal while an OpenCodex line remains |
+| O7 | 030 | message, test-first | each `desktop_lifecycle_unsafe` refusal names the path or condition and the fix, code at the end |
+| O10 | 040 | research + proposal only | what a safe "restart Codex clients" is and where it belongs |
+
+Order: O8 and O9 share `disconnectClient` and land together (O9 makes the O8 retry succeed); O7 next; O10 is a written proposal in the PR body.
+
+Verification floor: each new test fails on the base branch first; `bun run typecheck`, `bun run structure:check`, `bun run privacy:scan`, the layout guards, and the files that import the changed modules.

devlog/_plan/261111_child_disconnect_followups/010_o8_prepared_receipt_rollback.md

@@ -0,0 +1,18 @@
+# O8 — a refused disconnect rolls back its `prepared` receipt
+
+## Cause
+
+`disconnectClient` (src/client/connect.ts) writes `desktop-remote/disconnect.json` with phase `prepared`, then runs `restoreConnectedCodex` outside the lifecycle lock. A throw there leaves the receipt. Every non-`complete` receipt makes `observeClientRotationRecovery` (src/client/state.ts) answer `client_disconnect_pending`, and client startup refuses (src/cli/index.ts). A retry repeats the same Codex restore and fails the same way.
+
+## Decision
+
+`desktop_restored` is the commit point. Before it, the receipt records intent only: the Claude Desktop store, the catalog, the service token and the connection are untouched. So a failure before `desktop_restored` aborts: the receipt is removed (compare-and-delete against the receipt this run read), and the `desktop-remote` folder is removed too when the receipt was the only thing in it. At or after `desktop_restored` a retry must finish, as today.
+
+What a partial Codex journal restore leaves behind: the journal (recovery evidence), config.toml as it was, possibly the generated profile already reverted. The connection stays `connected`; the client runtime's next sync re-injects routing and regenerates the profile.
+
+The startup refusal names its fix: run `ocx disconnect` again (same `--keep-catalog` choice) to finish or roll back.
+
+## Tests (fail on base first)
+
+- refused disconnect: receipt gone, folder gone, connection connected, rotation gate `clean` (startup would pass), journal kept.
+- upgrade path: a `prepared` receipt written as 2.100.2 left it; `ocx disconnect` on the new build either completes (Codex side now restorable) or rolls back (still refused), never needs a folder moved.

devlog/_plan/261111_child_disconnect_followups/020_o9_codex_edited_config.md

@@ -0,0 +1,21 @@
+# O9 — disconnect after Codex edited config.toml
+
+## Cause
+
+`compareJournalState` (src/codex/journal.ts) accepts config.toml only when it equals the original snapshot or the first injected bytes (hash). Codex appends `[projects."…"] trust_level` blocks and notice flags; the restore is then partial forever.
+
+## Rule
+
+Inside one held Codex config write lock, after `restoreJournalState` reports incomplete:
+
+- proceed only if the journal is verified, the profile is restored, there is no lock or ownership refusal, and config.toml is what changed;
+- and the owned-field strip that `ocx restore` uses (`stripOpencodexConfigResult` with the journaled values) would change nothing — no marked or journaled base URL / realtime URL, no `opencodex` provider or table, no managed web_search or subagent defaults, no profile section.
+
+Then config.toml is left byte-for-byte and the journal is removed: its only remaining use, a whole-file replay of the pre-injection snapshot, would delete the lines Codex wrote, so it is never safe to apply again. If any OpenCodex line remains, the journal is kept and the refusal names the file and the remaining OpenCodex settings, quoting only an allowlist of keys OpenCodex writes and fixed table labels (never values, continuation lines, or quoted table names), with the fix: remove each named key with its whole value and each named table with every line under it, then run `ocx disconnect` again. `ocx restore` is not named: on a connected Child it also stores Codex integration as off, and nothing here proves a later link turns it back on.
+
+Not done here: stripping the remaining OpenCodex lines inside disconnect. `ocx restore`'s strip does that with history-provider handling, and folding it into disconnect is a follow-up decision.
+
+## Tests
+
+- positive: Codex-appended lines, no routing → disconnect completes, config.toml unchanged, journal gone.
+- negative: Codex-appended lines plus a remaining OpenCodex line (journaled `openai_base_url` without its marker) → refused, config.toml unchanged, journal kept, message names `openai_base_url`, config.toml and the fix.

devlog/_plan/261111_child_disconnect_followups/030_o7_named_desktop_refusals.md

@@ -0,0 +1,7 @@
+# O7 (rest) — name every desktop_lifecycle_unsafe cause
+
+`inspectRemoteDesktopStore` (src/claude/desktop-remote-store.ts) folds its failure sites into `conflict` / `unsafe`. Thread a reason and path out of each site class and map each to a message with the condition, the path and the fix, ending `(code desktop_lifecycle_unsafe)`.
+
+Classes (to be confirmed against source): store owned by another connection; OpenCodex profile removed or renamed in Claude Desktop; OpenCodex profile edited in Claude Desktop; an unreadable or unsafe store / library file; the folder with no state or receipt (#8529).
+
+Tests: one per class through `disconnectClient`, asserting path, fix and trailing code.

devlog/_plan/261111_child_disconnect_followups/040_o10_restart_codex_clients.md

@@ -0,0 +1,19 @@
+# O10 — restarting running Codex clients after sync (proposal, not built)
+
+## What happens today (source-checked)
+
+- `ocx sync` on a Child takes the connected path (`src/cli/sync-command.ts` → `syncConnectedClient`). After it, `handleConnectedSyncCatalogWrite` runs the restart scope only when that sync wrote the catalog or the models cache (`if (!result.catalogWritten && !result.cacheSynced) return`).
+- Without a restart flag, the same write path calls `afterCatalogWriteHandleAppServers({ restart: false })` (`src/codex/app-server-processes.ts`), which prints "WARNING: N Codex app-server process(es) still running … Re-run with `ocx sync --restart-codex`" for app-servers started before the catalog's mtime. `ocx status` reports `clients=pending-restart(pid …)` from the same stale-client observation (`src/codex/autostart-health.ts`).
+- Why the advice did not apply: the re-run writes nothing (the catalog is already current), so the restart scope never runs. The registry already says so for `ocx system codex-restart`: "`sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog, cache, or changed configuration write".
+- `ocx system codex-restart --yes` restarts on request, but it posts to `/api/system/codex-restart` on the running runtime's management API. A Child's client runtime serves only the machine listener (`src/client/machine-listener.ts`: `/healthz`, the bound `POST /api/system/restart`); nothing under `src/client/` serves `codex-restart`, so on a Child this command has no endpoint to reach (to confirm with a test before relying on it).
+- The Home's `ocx link restart-codex` and `ocx link sync --restart-*` send a second pinned `ocx sync --expect-link <id> --json --restart-codex` to the Child (`src/link/ssh-argv.ts` `remotePinnedSyncArgv`). That goes through the same write-gated path, so a second sync that writes nothing restarts nothing. That is likely the same gap and needs a test to confirm. The Home withholds the restart while a relayed model request for that Child is in flight (`src/link/sync-then-restart.ts`, `restart-skipped:link-active`).
+- Idleness: OpenCodex sees a turn only as a request through its own proxy (`getActiveTurnCount()` in `src/server/lifecycle.ts`, used by `src/codex/catalog-self-heal.ts`; the link's in-flight count on the Home). It cannot see a Codex app-server's own state: a turn waiting on an approval prompt, or a composer draft, has no request in flight.
+
+## Proposal
+
+1. **Restart what is actually stale, on request.** When `ocx sync --restart-codex` / `--restart-app-server-only` writes nothing, still restart the app-servers that `computeCodexAppServerCatalogStatus` classifies as stale (started at or before the current catalog's mtime). That makes the command the warning prints do what it says, and makes the Home's second pinned sync effective. Processes are the ones `listCodexAppServerProcesses` already selects (same user, Codex app-server / code-mode-host argv), narrowed to the stale set. A fresh process is never touched. The desktop app is quit only for the full `--restart-codex` scope, as today.
+2. **Idle gate.** Before restarting, the Child checks its own client runtime for active turns, which needs a small `activeTurns` field on the client `/healthz`. If a turn is active it withholds the restart and reports `restart-skipped:active`, matching the Home's `link-active`. Because app-server-internal state stays invisible, the explicit flag (and `--yes` for the desktop scope) remains the consent. "Idle" here means no proxied request in flight, not "safe to discard UI state".
+3. **Where it belongs.** Child-local: `ocx sync --restart-*` (the code path above), so a person on the Child, the Home's pinned sync, and `ocx link restart-codex` all share one implementation. `ocx system codex-restart` on a Child should either run the same local module or refuse with a message naming `ocx sync --restart-app-server-only`, instead of reaching for a management API the client runtime does not serve.
+4. **Hints.** `clients=pending-restart` in `ocx status` and the sync warning on a Child should name the command that works there.
+
+Not built in this PR: (1) changes Home fan-out restart behaviour and needs its own tests across the three entry points. (2) adds a field to the client health contract.

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

@@ -111,6 +111,10 @@ To disconnect a Child-initiated link, run `ocx disconnect` on the Child. It disc
 
 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`).
 
+If `ocx disconnect` is refused before it has changed anything outside Codex, for example because the Codex configuration cannot be restored, it rolls itself back: the Child stays connected, its runtime still starts, and the message says the disconnect was rolled back. A Child left with a half-finished disconnect by an older release refuses to start its client runtime with `client startup refused: an ocx disconnect on this machine stopped part way`; run `ocx disconnect` again (with `--keep-catalog` if the first run used it) to finish it or roll it back. If an earlier run had already begun restoring Claude Desktop, the receipt is kept and the retry finishes the disconnect. Only one `ocx disconnect` runs at a time on a machine; a second one refuses with `client_disconnect_busy`.
+
+Codex adds its own lines to `~/.codex/config.toml`, such as trusted projects and notice flags. When it has done so after OpenCodex wrote its routing and no OpenCodex line remains, `ocx disconnect` leaves the file as it is and removes the Codex journal, whose snapshot would otherwise overwrite those lines. The one exception is your own root `web_search` line, if OpenCodex set it aside while routing: disconnect puts that line back. If an OpenCodex setting remains, disconnect keeps the journal and names it; remove each named key with its whole value and each named table with every line under it, then run `ocx disconnect` again. A refusal about the Claude Desktop remote profile store (`desktop_lifecycle_unsafe`) names the file or folder involved and the step that clears it.
+
 ## 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.

scripts/test-layout/layout-clients.json

@@ -162,6 +162,8 @@
   "client-link-state.test.ts": "clients",
   "client-link-status.test.ts": "clients",
   "client-link-teardown.test.ts": "clients",
+  "client-disconnect-recovery.test.ts": "clients",
+  "client-disconnect-desktop-refusals.test.ts": "clients",
   "client-link-tunnel.test.ts": "clients",
   "link-ports.test.ts": "clients",
   "link-supervisor.test.ts": "clients",