Skip to content

fix(link): remedies check the machine before any disconnect, and a bound detach finishes its own interrupted attach - #8691

Merged
lidge-jun merged 19 commits into
devfrom
fix/link-remedy-followups
Nov 13, 2026
Merged

lidge-jun merged 19 commits into
devfrom
fix/link-remedy-followups

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Summary

The Remote Link remedy texts that #8654 and #8662 added could send an operator, or an agent reading them, to disconnect a machine that now belongs to another link, or to run a command that fails as printed. This PR rewrites each remaining remedy so that nothing acts on a machine on the strength of a status check alone. A status check cannot prove that another link is stale: an ocx-child's status reads only state.json, so an attach still in progress can show no link or an earlier one, and state that cannot be read shows none. Each remedy now offers a link-bound command (ocx disconnect --expect-link <id>, ocx-child detach --expect-link <id>, ocx link recover --link-id <id>), a Home-side command for this link (--force), or, on a full install only, a plain ocx disconnect right after a check that shows this link's id or no connection. Every other state, including a check that cannot answer, leaves the machine as it is. It also makes one Child behaviour change so that a link's own interrupted attach no longer ends as a residual that only a plain detach could clear.

Behaviour change (native/ocx-child):

  • ocx-child detach --expect-link <id> now finishes this link's own attach when it was interrupted before writing state.json. That state is an owner record naming the link in phase attaching, with no rollback or a rollback that names no link or this one. Restoring that rollback brings back no other link. A rollback naming another link is still refused as child_residual, unchanged. Before, every bound revoke of such a link answered residual (exit 6). Two Rust tests interrupt an attach at the owner record and at the config/rollback write; both failed before the change and pass after it. The residual reasons no longer suggest a plain detach.

Remedy texts (CLI, server messages, guides en/es, lifecycle reference en/es, capability text and the generated skill references, structure):

  • O1c-8 (fix(link): the CLI explains journal refusals and unfinished revokes from a truth table; the operation journal keeps replays for at least 2 hours #8654 follow-ups): the operation_journal_unreadable text prints ocx link revoke --force --link-id <id> --yes, which runs as printed. An unknown revoke that reads committed on its repeat is told to repeat once more to clear what it left. The lock-waiter wording reuses alias-lock.ts. "Reopens the entry" now applies only while the record is listed. Test titles use the text's own words.
  • alias_linked: the other link is left as it is. No status check on the machine can show it is stale: an ocx-child's status reads only state.json, so an attach still in progress can show no link or an earlier one, and state that cannot be read shows none. The tombstone waits until that link is removed. Revoking that link ends it and disconnects the machine if the machine runs it, so the text says to do that only to end that link. A person's --forget is a separate option, and the CLI fills in --link-id when recover was called with one.
  • expect_link_unsupported: update a full install and revoke again, or revoke this link with --force. Revoking the other link instead is no way out unless you mean to end it: no status check can show it is stale, its revoke under the same pinned host key meets the same guard, and through a shared route it disconnects the machine.
  • child_disconnect_pending: status cannot tell whose disconnect it is, so a plain ocx disconnect is advised only when the machine shows no connection; every other answer, or none, leads to --force.
  • child_link_mismatch: new branches for a machine that shows this link's id (let its connect or rotation finish, then revoke again) and for an unreadable or unreachable machine.
  • Forced-revoke texts: on a full Child, ocx disconnect --expect-link <id> replaces check-then-disconnect, which closes the window between the two commands. An OpenCodex older than that flag refuses it as a usage error before acting on the link, and only then does the text fall back to the check. A link without a recorded childKind gets the bound commands for both installs and is told that it leaves no tombstone. If the build refuses the flag, a full install falls back to check-then-disconnect, and a lightweight Child is left as it is.
  • child_recover_unsupported: do not run the old build's plain detach, because its status cannot show an interrupted attach of another link, which a plain detach would restore and then remove. Leave the machine; a person forgets the tombstone, with the real link id, once the machine is confirmed clean or gone. ocx link recover now prints its own text for this code; before, the CLI showed only the code. The purge path's message no longer carries advice the route replaces. The Windows planted paths are described as Command Prompt paths, and recover's promise describes what it checks.
  • ocx link cleanup: the Windows step no longer prints --yes without --force (which ocx link revoke refuses), and it uses the link-bound disconnect.

Dashboard (own commits): the force-remove dialog and the notices after a forced removal use the link-bound commands, and the unknown-type notice no longer offers an unbound ocx-child detach in any locale. When the Child answered and refused (child_link_mismatch, child_residual, child_disconnect_pending, expect_link_unsupported), the dialog's title says it refused, not that it could not be reached, and it names the reason from that closed set. Any other hint keeps the unreachable title. The new and reworded keys exist in all 11 locales with the same commands, paths and placeholders.

Refusal dialog for a full Child, before and after:

Force-remove dialog after a link-bound refusal, before
Force-remove dialog after a link-bound refusal, after

Notice after a forced removal of a full Child, before and after:

Forced-removal notice for a full Child, before
Forced-removal notice for a full Child, after

Notice after a forced removal of a Child of unknown type, before and after:

Forced-removal notice for a Child of unknown type, before
Forced-removal notice for a Child of unknown type, after

Known limits and follow-ups (not in this PR):

Verification

Run on the final head in this worktree:

  • cargo fmt --check, cargo clippy --locked --all-targets -- -D warnings and cargo test --locked in native/ocx-child on Rust 1.100.0: all pass (54 unit tests, 26 owner_link, and the other binaries).
  • Focused Bun suites with a temporary HOME/OPENCODEX_HOME and an empty git guard checkout: cli-link-operation, cli-link-force, cli-link-recover, cli-link-cleanup, cli-link-enrollment, cli-link, link-recover, link-revoke-operation, link-management-routes, docs-spanish-localization and skill-ocx: all pass.
  • cd gui && bun test tests/remote-link.test.tsx tests/locale-parity.test.ts: 81 pass, 0 fail. bun run lint:i18n and bun run build in gui exit 0.
  • bun run typecheck, bun run structure:check, bun run skill:surface:check, bun run privacy:scan: pass.
  • Each item changed its test first, including the five review fixes; the GUI title and reason tests and the two Rust interrupted-attach tests failed against the old code.
  • Screenshots come from a scratch harness, deleted afterwards, that renders the Remote Link page with stubbed API answers, captured with headless Chrome. "Before" used dev's GUI sources.

NOT RUN: full bun run test (focused suites only, given concurrent worktrees; CI runs the rest); Windows and real SSH execution. tests/ci-workflows/structure-ssot.test.ts fails three cases in this worktree only, on node_modules paths named in structure/codex-cli-update.md and structure/ops/service-and-sidecars.md (files this PR does not touch) and the shared git-config guard; structure:check passes.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

… follows every state a repeat can leave

Follow-ups to #8654's review:
- operation_journal_unreadable printed "ocx link revoke --force without --operation-id also runs", a usage error as printed. It now names ocx link revoke --link-id <id> --force --yes, without --operation-id, built from the validated link id like the retirement guidance.
- An unknown revoke whose record is already gone and whose receipt this id still owns: the repeat's resume settles the entry committed, and clearing the receipt can still answer 503. The unknown-outcome text and the structure paragraph now say: if it reads committed, the removal finished: repeat it once more to clear what it left.
- The structure's alias-lock sentence said a waiter that gets the lock can still finish before the CLI calls the outcome uncertain; it now uses alias-lock.ts's own wording (the wait is bounded, the finish is not promised).
- "A resume reopens the entry" holds only while the record is still listed (link.ts comment and structure).
- The tombstone-limit test's title and comment use the text's own words (the link, its key or the Child).

The two behaviour tests failed first on the old texts.
…heck cannot tell, and gives the forget way out on its own with the link id

#8662 delta review, P3 1, 3 and 4:
- A machine that cannot be reached, whose state cannot be read, or that shows a connect or key rotation in progress now counts as running that link: leave it, and the tombstone waits until that link is removed.
- The server message and the en and es CLI reference now carry the check step the CLI text and the guide had: check which link the machine runs (ocx connect status --json, or the planted ocx-child's), and revoke the other link only if it shows neither that link nor a connect or key rotation in progress.
- The forget way out was inside the branch that keeps the machine running that link; it is its own sentence now (once the machine is confirmed clean or gone), and the CLI fills the link id it was called with instead of printing <id> (the placeholder stays for --operation-id).

The CLI and server tests failed first on the old texts.
… stale, and keeps the pinned-key case apart

#8662 delta review, P3 2. The parenthesis mixed the same-pinned-key case into the staleness test and never said how to check it. The step now reads: revoke the other link first only if it is stale too, that is, ocx connect status --json on the machine (the planted ocx-child's on a lightweight Child) does not show its id; if the check cannot be run, leave it, since through a shared route its revoke would disconnect it. Under the same pinned host key its revoke is refused the same way, so use --force instead. CLI hint, server message, en and es guide. The CLI hint test failed first.
…y when the machine shows no connection

#8662 follow-up P3-a. The remedy said to check "whose it is" with ocx connect status, which cannot answer that, and to finish the disconnect when it shows this link's id or no connection. It now says the status cannot tell whose disconnect it is, finishes it with ocx disconnect only when the machine shows no connection, and sends every other answer (any link, a hub or another Home, an unreadable state, an unreachable machine) to --force. CLI hint, server message, en and es guide, structure row. The CLI hint tests failed first.
…this link's id, and one for a check that cannot answer

#8662 follow-up P3-b. A Child refuses a bound disconnect of its own link while a connect or key rotation of it is in progress (pending_operation), so the status can show this link's id. The remedy now says so: let it finish on the Child, then revoke again (a new or the same operation id by outcome). An unreadable state is repaired on the Child; if that is not possible, or the machine cannot be reached, revoke this link with --force once any enrollment of this link has finished. CLI hint, server message, en and es guide. The CLI hint tests failed first.
…pect-link, which closes the race between a check and a plain disconnect

#8662 follow-up P3-c. The force texts said to check ocx connect status and then run a plain ocx disconnect right after, accepting that an enrollment landing between the two would be removed. ocx disconnect --expect-link <id> (from #8662) acts only while the machine is connected to this link, so it is the step now; an OpenCodex older than the flag refuses it as a usage error before it acts on the link, and only then does the check-then-disconnect order apply, with "its state cannot be read" added to the leave-it branch. The forced revoke's output, the revoke usage line, the guide's Remove here only block and code block (en and es), the CLI reference (en and es), the capability text and the generated skill reference, and the recipe. The force-output tests failed first.
…mes the steps for either install

#8662 follow-up P3-d. A link saved before the Home recorded childKind keeps no tombstone (link-routes.ts writes one only for a known ephemeral Child), yet the forced revoke's output gave the full-install step only, and the guide and CLI reference had no step at all. The CLI now tells three cases apart (ephemeral, full, unknown, where unknown also covers a link the store does not list or a store it cannot read): for unknown it names ocx link recover when ocx link recover --list shows the link, and otherwise ocx disconnect --expect-link <id> on a full install or the planted ocx-child's detach --expect-link <id> on a lightweight Child (with its paths), the fallback for a build older than the flag, and the leave-it branch. The guide (en and es) and the CLI reference (en and es) say the same. Released ocx-child builds all parse detach's arguments strictly (since v2.100.0), so the bound form never detaches a link it does not name. The force-output tests failed first.
…upted before its state write

#8662 follow-up P3-f. An attach of link L interrupted after it wrote the owner record (phase attaching) but before state.json was refused as residual by detach --expect-link L, with a reason telling the operator to run a plain detach, while the Home's texts say never to run one; nothing could clean it. check_expected_link now finishes it as a plain detach would when no other link is involved: the record names L in phase attaching and any rollback snapshot names no prior link or L (a rollback naming another link is still refused as residual earlier in the check). The remaining refusal reasons no longer recommend a plain detach. A test barrier (attach-before-state-write) marks the point after the CODEX_HOME change and before the state write. Two tests in owner_link.rs (an attach stopped right after the record, and one stopped after it changed CODEX_HOME and left its rollback) failed first with residual (exit 6) and now restore the original config and release the record; another link's bound detach still answers conflict. structure/remote-link.md says so.

cargo fmt --check, cargo clippy --locked --all-targets -D warnings and cargo test --locked (Rust 1.100.0): pass.
…nted, and the purge path's dead remedy text goes

#8662 follow-up, the rest of P3-e. After recover answered child_recover_unsupported (the planted ocx-child predates detach --expect-link) the operator was told only not to detach and, for a gone machine, to forget. The answer now gives the check first: that ocx-child's connect status --json; only if it shows this link's id, its plain detach right after the check removes this link's attachment; another link, nothing, an unreadable state or an unreachable machine: leave it. Recover cannot confirm either case with that build, so the forget command follows with this link's id filled in. The purge path's own remedy for expect_link_unsupported (remote-plant.ts) never reached a user, since the route answers the hint's fixed message; it now names only what happened, with a comment saying where the remedy lives. The recover test failed first on the old message.
…th, and recover's promise says what it really checks

#8662 follow-up, the rest of P3-h.
- %LOCALAPPDATA%\opencodex\bin\ocx-child.exe expands only in Command Prompt (PowerShell spells it $env:LOCALAPPDATA). The child_link_mismatch check (CLI hint, server message, en and es guide) now says "in Command Prompt on Windows".
- "It cleans the machine only while it still belongs to this link" was not what recover checks: it acts when the machine's records name this link or nothing at all (then it only removes the planted binary) and refuses a machine another link owns. The forced revoke's output, the guide (en and es) and the capability text with its generated skill reference now say so.
The CLI tests failed first on the old texts.
… link-bound disconnect

#8662 follow-up (F3 from #8685's review). The report printed ocx link revoke --link-id <id> --yes, which the CLI refuses (--yes requires --force), and tests/cli/cli-link-cleanup.test.ts pinned that line. The step is the ordinary revoke, which disconnects through the recorded SSH trust and, since #8662, only while the machine is connected to this link: ocx link revoke --link-id <id>. The step on the machine now runs ocx disconnect --expect-link <id> and then ocx restart; an OpenCodex older than the flag refuses it before it acts on the link, and only then the check-then-disconnect order applies, with the leave-it branch for another link, a hub, another Home or an unreadable state. The cleanup test failed first.
…ands, and a Child's refusal gets its own title and reason

#8662 follow-ups for the dashboard (P3-g, the dialog title and hint, and the same steps as the CLI for P3-c and P3-h):
- A Child of unknown type: the notice named a plain ocx-child detach first. Every released ocx-child parses detach's arguments strictly (since v2.100.0), so the link-bound forms come first: ocx disconnect --expect-link <id> on a full install, or the planted ocx-child's detach --expect-link <id>; each acts only while the machine still belongs to this link. The check and the plain commands follow only for a build older than the flag.
- A full Child: the dialog and the notice name ocx disconnect --expect-link <id>, which closes the race between a check and a plain disconnect; the check-then-disconnect lines stay for an OpenCodex older than the flag, now with an unreadable state in the leave-it branch.
- A lightweight Child: "it cleans the machine only while it still belongs to this link" now says what recover checks: it acts only when the machine's records name this link or nothing at all, and refuses a machine another link owns.
- After #8662 a link-bound refusal (remote_disconnect_failed with hint child_link_mismatch, child_residual, child_disconnect_pending or expect_link_unsupported) opens the Remove here only dialog. It was titled "This machine could not reach {alias}", which is false when the Child answered, and it never showed why. The dialog now says "{alias} refused to disconnect from this link" with the reason from that closed set; any other hint keeps the unreachable title.
Seven changed and seven new keys in all 11 locales; the byte-for-byte pin covers the new ones. The dialog, notice and locale tests failed first on the old texts.
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 13, 2026
@coderabbitai

coderabbitai Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 13:23
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 13:23
@lidge-jun
lidge-jun merged commit ee0098a into dev Nov 13, 2026
30 of 33 checks passed
@lidge-jun
lidge-jun deleted the fix/link-remedy-followups branch November 13, 2026 13:23
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T13:26:07.787290Z 1706962 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1706962ea6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +2009 to +2012
let own_interrupted_attach = owner.is_some_and(|r| r.phase == OwnershipPhase::Attaching)
&& rollback
.as_ref()
.is_none_or(|prior| prior.as_deref().is_none_or(|id| id == link_id));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Allow retries after an interrupted attach cleanup changes phase

When cleaning a first attach interrupted before its state write, this newly accepted path stops being retryable if the detach crashes or encounters a restoration error. detach_with_exe persists OwnershipPhase::Detaching before calling AttachRollbackSnapshot::recover; if recovery does not finish, the rollback remains and state.json is still absent. The next bound detach then fails both checks: interrupted_detach requires no rollback, while own_interrupted_attach requires phase Attaching. Consequently, even after fixing a transient filesystem error, repeating ocx link recover returns residual instead of completing cleanup. Accept the same verified, link-safe rollback in the detaching phase, or preserve enough phase information to resume this cleanup.

Useful? React with 👍 / 👎.

lidge-jun added a commit that referenced this pull request Nov 13, 2026
…, and finish a bound detach killed while restoring its own attach (#8694)

* fix(ocx-child): a bound detach finishes its own detach that stopped while it restored an interrupted attach

* fix(link): child_link_mismatch says a connect or rotation may be in progress, and ends in --force when the answer repeats

* fix(link): alias_linked says to run recover again and names the other link's id for its revoke

* fix(link): child_recover_unsupported names a way to a clean machine, and an --operation-id recover names where the link id comes from

* fix(link): wording nits from the #8691 review: the absent-link reason, the cleanup restart, the race reason, the Windows Command Prompt paths, and the /1 reason

* fix(link): a failed enrollment's residual answer names the attempt's link id and binds the Child's step to it

* fix(cli): a failed enrollment prints the Child step bound to the attempt's link id, never a plain disconnect or detach

* fix(gui): a failed enrollment's Child step is bound to the attempt's link id in every locale, and is left without one

* docs(link): the guides and structure describe the failed enrollment's Child step bound to the attempt's link id

* fix(link): the first answer to an uncertain journalled plant names the reserved link id and the bound purge

* fix(link): a lightweight Child's enrollment step names the managed ocx-child path for its platform and a copy placed by hand

* docs(link): the structure note and recover reference say a bound detach also finishes a detach that stopped while restoring its rollback

* fix(cli): an --operation-id recover's refusals name the operation id: recover it again, or resolve it

* test(gui): the residual without a link id shows neither the server message nor its recovery line
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant