Repository navigation
fix(link): recover waits while another link names the alias, and a forced revoke's tombstone no longer outlives a revoke that threw - #8661
Conversation
…he commit, a throw included A throw between the early tombstone write and the record-removal commit (stopLink rejecting, for example) ran none of the explicit drops and left the tombstone beside a live link. A committed flag is now set once the record is removed, and the finally drops this revoke's own tombstone when it is not set; the three explicit drops inside the try are folded into it. The comment no longer claims a later ordinary revoke would strand that tombstone (a committed ordinary revoke removes it). The journalled force revoke whose first intent fails now asserts the drop too.
…ence, and the NotAttached rule structure/remote-link.md: the tombstone's parenthetical follows its file again; recover's hint list no longer names binary_in_use (recover settles on that marker); the binary_in_use hint is for a --purge revoke only; a NotAttached report is trusted as the link's own restore whether or not the binary stays. link-recover.ts's docblock names the in-use case. A test row pins the check order: the in-use marker on a report for another link answers receipt_unbound.
…tombstone's alias Inside the alias lock, before any SSH, recover now answers 409 alias_linked while a Home-initiated link names the target's alias (case-insensitive). The machine may belong to that link: a re-enrollment, or one whose revoke ran its disconnect without committing, which a plain revoke does not journal. Recovering then would settle the old link and purge the binary under the new one; in the case where the new link is still attached, the Child already refused (child_conflict), so the safe path loses nothing. Documented in the Remote Link guide (en, es), structure/remote-link.md and the recover capability (skill surface).
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 2 minutes. View limit details
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. |
|
✅ Deterministic PR hygiene checks passed. |
…d region, and a hold never leaks holdLink ran before the revoke's try, so a throw there skipped the finally's tombstone drop and left the tombstone beside the live link. It now runs inside the try. The supervisor's holdLink releases its own hold when the cancellation it runs throws, so no hold is left that nobody can release. Test first: a throwing hold kept the tombstone.
…evoke the link Settling an operation records it as resolved but keeps the link, so the guard stays; the message and the guide (en, es) now say to settle, then revoke, then recover.
Makes the route-proof registry's forget throw while holdLink cancels the link's round; the hold is then released, so reconnect restarts the link (on the previous supervisor it stayed held and reconnect answered false).
Conflicts: link-recover-route.ts keeps dev's in-lock link_present and link_retirement_pending checks, then this branch's alias_linked guard; link-routes.ts keeps dev's listed-only tombstone, guarded stopLink and one-step key+record commit, with this branch's hold inside the try and the committed flag set after the commit succeeds; the test imports take dev's union.
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Maintainer integration record for the squash merge a089ac7.
|
Conflicts: link-routes.ts keeps #8661's committed = true after the commit step and drops dev's commit-time tombstone removal (this branch: no revoke removes a tombstone); structure/remote-link.md 'Recover's limits' keeps this branch's tombstone rule with dev's binary_in_use wording (revoke only; recover settles on the in-use marker); link-recover.test.ts harness takes both options (holdThrows, ordinary) and keeps both appended describe blocks.
… that tombstone Final review P3-1 of #8661: recordTombstone writes the file and then chmods; if the chmod or the lock COMMIT throws, the revoke answered tombstone_write_failed and kept the link with the tombstone beside it. The catch now marks it written and drops it by its attempt token. Structure: that drop, like every own-tombstone drop, is best effort under busy_timeout 0. Test failed before the fix.
…ked means Final review P3-2 of #8661: every recover refusal printed only "Link management request failed (409)", so alias_linked looked like child_residual, whose remedy (ocx-child detach on the machine) would there detach the other link. runLinkRecover now names the code with the CLI's own text for alias_linked, link_present, link_retirement_pending, tombstone_not_found and host_key_changed, and a hint only when it is a plain word; the server message is never printed and the exit code is unchanged. Tests failed before.
…routes Final review P3-3 of #8661: the alias_linked guard compared each link's primary alias only, so a Home-initiated link that reaches the same machine through a sibling route was missed. It now compares the alias and every route (effectiveLinkRoutes). Test failed before.
…ists it and link_present Final review P3-4 of #8661: the guide said recover waits (it answers 409 at once) and another link (a Home-initiated one, by alias or route); the Spanish text used resuelva, narrower than settling (an open revoke can only be repeated); the CLI reference (en, es) listed recover refusals without alias_linked and link_present. The structure note on throws before the commit landed with the P3-1 commit.
…mbstone Final review P3-5 of #8661 (coverage): after the commit the link is gone, so a later throw answers link_remove_failed and the tombstone stays as the only cleanup evidence.
…ctive Final review of #8654 (P2): a resumed forced revoke can meet the tombstone limit after an earlier attempt of the same operation already revoked the key and stopped the tunnel, then failed before the record went and dropped its own tombstone; the repeat re-records one and is refused. 'so the link and its key stay active' was then false. The text keeps only 'this attempt did not touch the link, its key or the Child', which holds on every path, also once #8661 drops the tombstone on every exit before the commit.
One conflict, docs-site/src/content/docs/es/guides/remote-link.md: this branch keeps the journal paragraph before the recover paragraph (the English order), and the recover paragraph is #8661's updated one, with its new alias_linked sentence. capabilities-base.ts carries #8657's -F none sentence once in each of the two --proxy-command flags (probe and add) beside this branch's edits; the skills reference is regenerated on the merged tree (51 declared capabilities).
Final review of #8654 asked to change the method: structure/remote-link.md now holds the table, per code a journalled revoke can answer, of where it arises, what may already have changed on a first and on a resumed attempt (#8416, #8661), and what the CLI prints. A text claims a state only when it holds in every row for its code; journalledRevokeError's comments point here.
…rom a truth table; the operation journal keeps replays for at least 2 hours (#8654) * fix(link): the CLI explains a full operation journal and a journalled revoke that did not complete Final review of #8638: linkRequest replaces every API error with "Link management request failed (N)", operation_journal_full was not among the add refusals, and runRevoke rethrew everything but link_not_found, so a full journal, or a repeated open revoke that recovery settled unknown (409 operation_interrupted), printed only that generic line. operation_journal_full now carries a closed bound field (unsettled or recent); it is additive, and an older CLI drops it and still refuses. ocx link add and ocx link revoke with --operation-id print their own guidance for it, with the code and the bound, keeping exit 5. A journalled revoke that did not complete prints "(operation <id>: <outcome>) (code <code>)" from the filtered body (the caller's validated id, a closed outcome, the filtered code) and names ocx link operations resolve when the outcome is unknown. No server text is printed. * docs(link): say what an open revoke means and that its flags cannot be read back Final review of #8638: the open-suspension text said "the Home stopped during it", but an open entry also means the revoke failed before writing its outcome; "add --purge if it was a purge" cannot be checked from the entry, which records only a digest of the flags, so a wrong guess answers operation_mismatch; and the ALIAS_LOCK_WAIT_MS comment promised a waiter time to finish before the CLI deadline, which an apply's worst case does not give. The route, the CLI, the capability text, the guide (English and Spanish) and structure/remote-link.md now say "did not record its outcome (the Home stopped or the revoke failed before writing it)" and tell the caller to repeat with the flags of the first attempt, naming operation_mismatch for a different --purge. The alias-lock comment says the bound limits the wait and promises no time to finish. * docs(link): state the operation journal's throughput limit by churn Final review of #8638: the comment on OPERATION_JOURNAL_MAX_RECENT_SETTLED argued by machine count. The limit it sets is a burst of 1024 and about 42 journalled operations per hour sustained (1024 / 24.05 h); ten disposable machines that live ten minutes each make about 120 per hour and reach it in about 8.5 hours. The comment, structure/remote-link.md and the ocx link operations capability text now say so. The constants are unchanged until the owner chooses a replay horizon or a higher cap. * docs(link): a suspension needs the revoke's cleanup intent and no live revoke Lane review (P3): the ocx link operations resolve text said any revoke that did not record its outcome keeps the link down, but suspension needs the remote_cleanup intent, and an open entry only when no revoke in this Home still runs it. The capability text and the generated skill reference now say so. * docs(link): the cleanup-intent condition covers an open revoke too Final review of #8654 (P3): the ocx link operations resolve text tied the remote_cleanup intent to the unknown case only, but suspendingRevoke requires it for an open entry as well, so an open forced revoke or an open revoke of a Child-initiated link never suspends. The capability text and the generated skill reference now read as structure/remote-link.md does. * fix(link): a journalled revoke refused before it ran says nothing was changed Final review of #8654 (P3): operation_mismatch, link_operation_open, link_operation_in_progress and operation_journal_unreadable on ocx link revoke --operation-id printed 'Link revoke did not complete (code X)'. They now get the CLI's own text that nothing was changed, with the code, as add's refusals do. The list is closed: any other code, including ones a newer Home adds, keeps the generic text and makes no such claim. Exit codes are unchanged. * fix(link): the journalled revoke helper re-checks the outcome and code itself Final review of #8654 (P3): journalledRevokeError accepted any string outcome and was safe only because linkRequest's filter had limited it. It now re-checks the outcome against OPERATION_OUTCOMES and the code against the filter's pattern, as journalFullGuidance re-checks bound; a test passes an unfiltered body straight to the helper. * docs(link): say when the CLI adds the operation note and the bound Final review of #8654 (P3): structure/remote-link.md said an unfinished journalled revoke always prints the operation note and a full journal always the bound. The operation part appears when the answer names this operation and a known outcome, the bound when the Home sends it; the doc now says so and lists the refusals that say nothing was changed. * docs(link): a cleanup intent means cleanup may have started; a full journal also says nothing changed Lane review (P3s): the remote_cleanup intent is written before the tunnel stops and before the Child is contacted, so the capability text now says the Child's cleanup may have started instead of that it reached the Child (generated skill reference regenerated). structure/remote-link.md lists operation_journal_full's guidance among the texts that say nothing was changed. * fix(link): a forced revoke refused at the tombstone limit says nothing was changed After #8612, ocx link revoke --force --operation-id of an ephemeral Child can be refused with tombstone_limit (409) or tombstone_write_failed (503). tombstone_limit is answered before the tombstone is written, before the first journal intent and before the tunnel stops, so it joins the CLI's closed list of refusals that say nothing was changed; tests/server/link-recover.test.ts now pins that the key is not revoked and the tunnel not stopped. tombstone_write_failed stays generic: the tombstone file may already be written when its permissions step fails. * feat(link): keep a settled journal entry replayable for 2 hours instead of a day Decision for disposable-machine churn: with a one-day replay horizon the 1024 recently-settled bound allowed about 42 journalled operations per hour, and ten machines that live ten minutes each (about 120 per hour) hit it after about 8.5 hours. OPERATION_REPLAY_MIN_MS is now 2 hours; the alias-lock wait and the minute of margin stay, so the prune floor is 2 h + 120 s + 60 s, and the 1024 bound stays: about 500 journalled operations per hour sustained, 4.2 times the example churn, with a worst-case file of about 1.5 MiB. The guarantee: a repeat with the same operation id within 2 hours of the answer always gets that answer; later it may be treated as a new operation, which meets a safe refusal (link_exists for an enrollment whose link is there, link_not_found for a revoke whose link is gone). Unsettled entries are never pruned and the 30-day retention is unchanged, so the window matters only after more than 256 settled entries. The constant's comments, the 409 text for the recent bound, the CLI's own guidance, the ocx link operations capability text (and its generated skill reference) and structure/remote-link.md say so. * docs(link): state the replay guarantee with its conditions, and pin a repeat after the window Lane review of the 2-hour horizon: 'a repeat within 2 hours always gets that answer' overstated it. A repeat that reaches the journal within 2 hours gets the recorded outcome (status, code and outcome, not the identical body); a refusal before the journal is read (the alias lock busy past its wait, an unreadable journal) changes nothing and is retried. After the window the id may be treated as a new operation, and that is not always a refusal: an enrollment whose link was removed meanwhile enrolls the machine again, now pinned by a regression test. The constant's comment, the capability text (and its generated reference) and structure/remote-link.md say so. * test(link): pin a repeat after the window through real pruning and a revoke; the replay needs the same parameters Lane review (P3s): the post-window test now revokes the link through the route, lets 256 later operations settle, advances the clock past the prune floor and asserts that a journal write pruned the original entry before the repeat enrolls again. The replay guarantee in the constant's comment, the capability text (and its generated reference) and structure/remote-link.md now says the repeat must use the same parameters; another set answers operation_mismatch. * fix(link): a tombstone_limit refusal says a repeat of its operation id replays it Final review of #8654 (P3): a forced revoke refused at the tombstone limit is recorded failed_clean, so repeating the same operation id returns the same refusal even after the person recovered tombstones. The CLI's guidance now says so and to retry with a new operation id. Its test now uses --force, the only way to meet that limit. * docs(link): the guide's replay sentence names its conditions Final review of #8654 (P3): the Remote Link guide (English and Spanish) said a repeat of the same command returns the recorded outcome without conditions. It now says: with the same flags, within 2 hours of its answer, as the structure doc and capability text do. * test(link): the replay test's comment names the replay window, not a day Final review of #8654 (P3): a comment in tests/server/link-enrollment-operation.test.ts still said the burst settles 'within the same day'. It now says inside the replay window. (The other half of this item, a tombstone_limit test sent for a --purge revoke, is fixed in 825132f, which moved it to --force.) * fix(link): link_operation_in_progress claims only that the link, key and Child were untouched Found while re-reading the merge of #8416: a resumed revoke (one that owns its retirement receipt) can re-own that receipt and then answer 409 link_operation_in_progress when a Child job holds the link. The link, its key and the Child are untouched, but 'Nothing was changed' is too strong for that path. The CLI text for this code now says the attempt did not touch the link, its key or the Child; the other refusals keep 'Nothing was changed'. structure/remote-link.md says so. * fix(link): tombstone_limit guidance holds for a resumed revoke too Lane review (P2): a resumed force revoke can re-own its retirement receipt before removeReserved meets the tombstone limit (#8416), and such an operation can stay open or unknown, so 'Nothing was changed', 'recorded as failed_clean' and 'retry with a new operation id' could all be wrong for it. The CLI now says the attempt did not touch the link, its key or the Child, and to check ocx link operations --operation-id <id> before reusing the id: a failed_clean entry replays this refusal (use a new id), any other state is repeated with the same id. structure/remote-link.md says so. * docs(link): the guide's replay sentence says the repeat must reach the journal Lane review (P3): the guide (English and Spanish) said a repeat within 2 hours returns the recorded outcome; a lock-busy or unreadable-journal refusal can stop it first. It now says a repeat that reaches the journal within 2 hours returns it, and to retry a transient refusal such as link_operation_in_progress, as the capability and structure text do. * fix(link): tombstone_limit guidance repeats the same operation id first Lane review (P2): failed_clean alone does not mean a fresh refusal. A failed_clean operation can still own a retirement receipt; if its resumed force revoke meets the tombstone limit, the entry stays failed_clean, and once capacity is freed the original id resumes and finishes while a new id is refused with link_retirement_owned. The CLI now says to repeat the same operation id first and to use a new id only if that repeat answers the same refusal again. tests/server/link-revoke-operation.test.ts pins the server side (refused at the limit, a new id refused with link_retirement_owned, the same id committed after a slot is freed); structure/remote-link.md says so. * fix(link): tombstone_limit guidance never declares a refusal recorded Lane review (P2): a second tombstone_limit does not prove the refusal was replayed; a resumed revoke meets the live limit again while capacity stays full, and its receipt still belongs to the original id. The CLI now says to free capacity and repeat the same operation id, to try a new id only if the refusal comes back although capacity is free, and to keep the original id if the new one answers link_retirement_owned (a safe refusal). The server test now repeats the resumed revoke with capacity still full (tombstone_limit again) before a new id is refused and the original id commits once a slot is freed. * fix(link): tombstone_limit no longer says the link and its key stay active Final review of #8654 (P2): a resumed forced revoke can meet the tombstone limit after an earlier attempt of the same operation already revoked the key and stopped the tunnel, then failed before the record went and dropped its own tombstone; the repeat re-records one and is refused. 'so the link and its key stay active' was then false. The text keeps only 'this attempt did not touch the link, its key or the Child', which holds on every path, also once #8661 drops the tombstone on every exit before the commit. * fix(link): tombstone_limit guidance names the owner of an unfinished removal instead of claiming it Final review of #8654 (P2): 'if that answers link_retirement_owned, the removal still belongs to this id' can be false. A fresh refusal recorded failed_clean owns no receipt, and another removal of the same link (a journalled operation or a plain revoke) may hold it; repeating this id then replays the same refusal and loops. The text now says an unfinished removal holds the link, and to repeat the operation id that owns it (ocx link operations lists the link's revokes) or finish it with ocx link revoke --force without --operation-id. * fix(link): closed guidance for an interrupted removal on a journalled revoke Final review of #8654 (P3): link_retirement_owned and link_retirement_mode_mismatch (#8416) printed only 'Link revoke did not complete (code X)'; the owning operation and the way out were in the server's message, which the CLI never prints, although the tombstone_limit guidance points the person at link_retirement_owned. They now get closed texts that name where to look (ocx link operations, a plain revoke without --operation-id, the same options, --force) and claim nothing about what an earlier attempt changed. structure/remote-link.md lists them. * docs(link): the replay guarantee names a revoke that resumes its own removal Final review of #8654 (P3): a revoke repeat whose own retirement receipt is outstanding resumes that removal first and answers that attempt (#8416), not the recorded outcome; the PR's own test repeats an entry recorded failed_clean and gets tombstone_limit, then committed. structure/remote-link.md, the capability text (and its generated reference), the constant's comment and the guide (English and Spanish) now say so. * docs(link): keep the guide's outcome list next to 'recorded outcome' Final review of #8654 (P3): '(retry a transient refusal such as link_operation_in_progress) (committed, failed_clean, residual or unknown)' read as if the second parenthesis listed transient refusals. In the English and Spanish guide the outcome list now follows 'recorded outcome' and the retry advice is its own clause. * test(link): point the tombstone_limit comment at journalledRevokeError Final review of #8654 (P3): the comment in tests/server/link-recover.test.ts said the CLI prints 'nothing was changed' for tombstone_limit through REVOKE_REFUSALS; at the head it comes from journalledRevokeError and says only that the attempt did not touch the link, its key or the Child. * docs(link): the journal's size bound includes entries a retirement receipt pins Final review of #8654 (P3): entries pinned by an outstanding retirement receipt (#8416, ownsRetirement) are kept past retention and the settled cap, at most two per receipt, and receipts have no cap of their own. The comment on OPERATION_JOURNAL_MAX_RECENT_SETTLED and structure/remote-link.md now include them in the stated file size. * fix(link): link_retirement_owned offers only the retries that can finish a journal-owned removal Lane review (P2): when a journalled operation owns the receipt, foreignRetirement refuses a revoke without --force that is not its id, whether or not the Child cleanup can run, so 'revoke without --operation-id (add --force if its cleanup cannot run again)' offered a retry that cannot finish. The text now says: repeat the owning operation id (ocx link operations lists the link's revokes) or ocx link revoke --link-id <link id> --force --yes without --operation-id; a revoke without --operation-id and without --force finishes it only when no journalled operation owns it and its cleanup can run again. The tombstone_limit hint names --force --yes too. * fix(link): operation_journal_unreadable makes no state claim on a journalled revoke Final review of #8654 (P2): a repeat of a journalled revoke whose own retirement receipt is outstanding resumes the removal first (#8416); if that finishes and the replay's journal read then fails, the answer is operation_journal_unreadable while the link is already gone, and 'Nothing was changed; ... retry' sent the caller into link_not_found with exit 4. The text now makes no state claim, names the way out (keep a copy, move it aside, repeat with the same id) and says that a link_not_found then means the link is already gone. The 'changes nothing' lists in structure/remote-link.md and the constant's comment no longer include an unreadable journal or a 5xx. * docs(link): the structure doc describes the tombstone_limit advice the CLI now gives Final review of #8654 (P3): structure/remote-link.md still said the tombstone_limit text tells the caller to keep the original id when a new one answers link_retirement_owned, the advice 08ce109 removed because it could loop. It now describes the current text: an unfinished removal holds the link; repeat the revoke that owns it, or finish with ocx link revoke --link-id <link id> --force --yes without an operation id. * fix(link): name the owner of an unfinished removal by what the CLI can show Final review of #8654 (P3): 'repeat the operation id that owns it (ocx link operations lists this link's revokes)' pointed at a list that shows no link id and marks no owner; the owner id is only in the server's message, which the CLI drops. The tombstone_limit and link_retirement_owned texts now say: repeat the open or unknown revoke of this link (ocx link operations --json shows each entry's linkId), or finish with a plain forced revoke. A closed owner field is a later change. * fix(link): generic revoke refusals name a next step, and an unknown outcome repeats before resolving Final review of #8654 (P3): link_changed and operation_journal_failed printed a bare 'Link revoke did not complete (code ...)'. They now add a next step that holds on every path that answers them: repeat the revoke with the same operation id (for operation_journal_failed, a new id if the same code comes back; for link_changed, after reading ocx link status). For an unknown outcome the CLI said 'check the Child, then resolve', skipping the repeat that finishes a removal this id still owns (#8416); it now says to repeat with the same id first and only then check the Child and resolve. * fix(link): the mode-mismatch text makes no state claim and offers no retry that answers operation_mismatch Final review of #8654 (P3): 'interrupted after its cleanup ran' claimed a state that is false for a force-mode receipt, and 'or with --force' with the same operation id answers operation_mismatch. With --operation-id the code is unreachable at this head (foreignRetirement admits only this operation's own receipt, resumed in its own mode), but the closed text now says only that the removal was interrupted in another mode and offers the revoke that started it with its options, or ocx link revoke --link-id <link id> --force --yes without --operation-id. * fix(link): the tombstone_limit message and the guide no longer say the link and key stay active Final review of #8654 (P3): the clause the CLI dropped in 74bf9a2 survived in the server's tombstone_limit message and in the recover paragraph of both guides. A repeat of an interrupted forced revoke can meet the limit after its earlier attempt already revoked the key and stopped the tunnel. The server message now says only that this attempt was refused before its own effects and names ocx link recover --link-id/--list; the guide (English and Spanish) says a fresh refusal changes nothing and to check ocx link status after a repeated one. * docs(link): resumes rather than finishes, a qualified pin bound, a valid recover command and --link-id in the hint Final review of #8654 (P3 nits): a revoke whose own removal was interrupted resumes it first (the resume can fail), in the guides, the capability text and its generated reference, structure/remote-link.md, the constant's comment and the CLI; the receipt pin is at most two entries per readable receipt and every revoke entry of a link whose receipt cannot be read; the tombstone_limit text names ocx link recover --link-id <id> (bare ocx link recover is a usage error) and the full repeat command with the link id the CLI knows; the describe title of the CLI tests now covers every refusal it holds. * docs(link): the truth table every journalled-revoke refusal text follows Final review of #8654 asked to change the method: structure/remote-link.md now holds the table, per code a journalled revoke can answer, of where it arises, what may already have changed on a first and on a resumed attempt (#8416, #8661), and what the CLI prints. A text claims a state only when it holds in every row for its code; journalledRevokeError's comments point here. * fix(link): the owner of a removal can be in any state, and operation_journal_failed keeps the same id Lane review (P2, P2, P3): a failed_clean revoke can own a retirement receipt too, so the tombstone_limit and link_retirement_owned texts now say to repeat the revoke of the link that owns it, whatever its recorded state (another revoke's id answers its own outcome or the same refusal). A resumed owner can meet the same live journal-write failure again and keep its receipt, so operation_journal_failed now says to fix the journal's disk and repeat the same id, and that a new id, if tried and answered with link_retirement_owned, means this id may still own the removal. The table's tombstone_write_failed row now says the write's outcome is uncertain: recordTombstone can throw after its atomic write, before this revoke counts the tombstone as its own. The table in structure/remote-link.md follows all three. * fix(link): link_changed says what a second answer means instead of claiming the link changed during this revoke * fix(link): an unknown revoke resumes a removal on repeat only if its id still owns one * fix(link): revoke and recover commands in the guidance carry the link id so they run as printed * docs(link): the truth table says what operation_journal_failed and a resumed tombstone_limit can leave behind * fix(link): an add refusal says only that the apply changed nothing, since confirm-host already pinned the host key * fix(link): the tombstone_limit message and the guide name only what the refused attempt left alone * fix(link): an unknown revoke resolves only once its entry reads unknown or residual; an open one is repeated * docs(link): the truth table tells a replayed link_changed from a resumed one and names what a first-intent failure leaves
… revoke removes a tombstone it did not write (#8662) * feat(client): ocx disconnect --expect-link refuses unless this machine is that link's Child A Home's revoke sends a plain disconnect, so a revoke delayed past a re-enrollment could disconnect the newer link. ocx disconnect now takes --expect-link <linkId>: the same identity check ocx sync --expect-link makes (ClientSyncExpectation), read-only under the client lifecycle and config locks, before the client-link teardown and again inside disconnectClient before anything is written. A mismatch changes nothing, exits 5 and ends stderr with {"phase":"child_link_mismatch","reason":...}; a malformed or repeated flag, or one combined with --orphaned-token, exits 2. An older ocx rejects the flag as an unexpected argument (exit 2) before doing anything, which lets the Home fall back. * fix(link): ordinary and --purge revokes are bound to their link, and only a bound answer settles a tombstone A revoke sent a plain disconnect (or the managed purge) to whatever answered at the alias, so a revoke delayed past a re-enrollment could disconnect the newer link, and its commit then removed the tombstone unconditionally. An ordinary revoke now runs disconnect --expect-link <id>, and --purge passes --expect-link <id> to the managed binary. A Child that answers 5 (another link, a hub, no connection) or 6 (an ocx-child residual) changed nothing: 502 remote_disconnect_failed with hint child_link_mismatch or child_residual, the tunnel restarts and the link stays. A Child older than the flag rejects it as a usage error (exit 2) before acting, and the command reruns without it, unbound. The commit removes a tombstone left for this link only after a bound answer. ocx disconnect --expect-link is exempt from the root Codex-shim repair so a refusal changes nothing. Docs: structure/remote-link.md, structure/cli-management.md, the Remote Link guide (en, es). * fix(client): a link-bound disconnect skips the client-link teardown and may resume its own link's unfinished disconnect With --expect-link, teardownClientLink ran between the identity check and the locked disconnect, so a machine re-enrolled in that gap could have its new tunnel reaped and its Home link revoked. The Home sends --expect-link only for Home-initiated links, whose tunnel and record it owns, so the teardown no longer runs there. The check is now classifyDisconnectLinkExpectation: the sync expectation, except that an unfinished disconnect resumes when the machine is still connected to that link and the receipt's owner is that connection, so a Home whose bound disconnect lost its answer can finish it. * fix(link): the unbound fallback runs only while the link is still alone on its alias, and a pending disconnect is not clean After an older Child rejects --expect-link (exit 2), the Home reruns the command unbound only while this link still exists and no other Home-initiated link names its alias (re-read just before the retry); otherwise it answers expect_link_unsupported with nothing changed. A bound exit 5 whose reason is disconnect_pending counts as cleanup attempted (child_disconnect_pending), never failed_clean. Docs: structure/remote-link.md, structure/cli-management.md, the guide (en, es). * test(link): the explicit-route enrollment test expects the link-bound revoke disconnect * fix(client): a link-bound disconnect refuses a client-initiated link instead of skipping its teardown ocx disconnect --expect-link skipped the client-link teardown for any matching link, so a person or script running it on a client-initiated link would leave that link's Home record and key active. A Home sends the flag only for Home-initiated links, so a sidecar naming the expected link (a client-initiated link) is now refused before anything changes: exit 5, reason client_initiated_link (invalid_state for an unreadable sidecar), with the instruction to disconnect without --expect-link. Exit 2 is avoided on purpose: the Home reads it as a Child older than the flag. Docs: structure (cli-management, remote-link known limits incl. cross-Home re-enrollment), the registry details. * fix(client): a link-bound disconnect skips dev's lone native-intent drain and refuses --recover-config Needed by the merge of #8416, beyond picking lines: dev's disconnectClient drains lone native-intent originals on a disconnected machine before any identity check, so a link-bound disconnect racing a local disconnect could change state where it must change nothing; it now skips the drain and refuses under the locks. dev's new --recover-config is a person's own recovery, never sent by a Home, so combining it with --expect-link is a usage error (exit 2). The teardown test now ignores the config loader's repair notice dev prints on stderr and asserts only that no refusal was printed. * fix(client): a link-bound disconnect also refuses a client-initiated link whose sidecar is lost, and reports an unfinished disconnect first The Home-initiated check moves under the client locks (assertHomeInitiatedDisconnect), runs before teardown and again inside disconnectClient, and reads the Child-initiated marker that survives a lost sidecar (isChildInitiatedLink, fail-closed on an unreadable marker). When this link's own unfinished disconnect is on record, a refusal says disconnect_pending instead of client_initiated_link or invalid_state, so the Home counts the cleanup as attempted and never journals failed_clean after a partial cleanup. * fix(link): a link-bound cleanup settles the old tombstone when the Child answers, before the commit Round-4 review: a retry resumes a retirement without running the cleanup again, so linkBound stayed false and the commit left the tombstone even though the first attempt's Child had confirmed the link. The settle now follows the bound answer itself (ordinary and --purge); nothing in the journal or receipt schema changes, so an older Home can still read both. Test: a bound cleanup followed by a failed key revoke settles the tombstone (both rows failed before). * fix(link): the bound settle removes only the tombstone read before the Child command, and only while the link exists Round-5 review: a force revoke in another process can write a fresh tombstone while the bound command is in flight (for example against a Child an enrollment has not attached yet); the early settle removed it, leaving no recovery evidence. removeTombstoneIfUnchanged removes the tombstone only when it still equals the version read before the command and the link is still listed. Tests: a tombstone written during the bound command stays, with and without an older one (both failed before). * fix(link): no revoke removes a tombstone; recover settles it once the link is gone Round-6 review: a forced revoke in another process can write its tombstone just before an ordinary revoke reads it, then pause before removing the record while an enrollment attaches the Child. Rounds 4 to 6 moved the settle to the commit, to the bound answer and to an unchanged snapshot; each left a race with a forced revoke the ordinary revoke is not serialized with. Beside a listed link a tombstone always belongs to a forced revoke in flight or one that died, so no revoke removes one now, including dev's purge revoke at commit; ocx link recover settles it under the alias lock once the link is gone. removeTombstoneIfUnchanged is dropped, so tombstones.ts matches dev. Tests: an ordinary bound revoke and a purge revoke leave the tombstone and recover then settles it (both failed at 982955e). * docs(link): a tombstone left after an unbound cleanup of an older Child needs a person's --forget Round-7 review: recover cannot prove an unbound cleanup (an older ocx-child purges without a link-bound receipt, or answers child_recover_unsupported), so the guide (en, es) and structure name the manual path and its cost against the 256 limit. * fix(link): a tombstone write that throws after writing the file drops that tombstone Final review P3-1 of #8661: recordTombstone writes the file and then chmods; if the chmod or the lock COMMIT throws, the revoke answered tombstone_write_failed and kept the link with the tombstone beside it. The catch now marks it written and drops it by its attempt token. Structure: that drop, like every own-tombstone drop, is best effort under busy_timeout 0. Test failed before the fix. * fix(cli): ocx link recover names its refusal, and says what alias_linked means Final review P3-2 of #8661: every recover refusal printed only "Link management request failed (409)", so alias_linked looked like child_residual, whose remedy (ocx-child detach on the machine) would there detach the other link. runLinkRecover now names the code with the CLI's own text for alias_linked, link_present, link_retirement_pending, tombstone_not_found and host_key_changed, and a hint only when it is a plain word; the server message is never printed and the exit code is unchanged. Tests failed before. * fix(link): recover also waits while a link lists the alias among its routes Final review P3-3 of #8661: the alias_linked guard compared each link's primary alias only, so a Home-initiated link that reaches the same machine through a sibling route was missed. It now compares the alias and every route (effectiveLinkRoutes). Test failed before. * docs(link): recover refuses alias_linked at once; the CLI reference lists it and link_present Final review P3-4 of #8661: the guide said recover waits (it answers 409 at once) and another link (a Home-initiated one, by alias or route); the Spanish text used resuelva, narrower than settling (an open revoke can only be repeated); the CLI reference (en, es) listed recover refusals without alias_linked and link_present. The structure note on throws before the commit landed with the P3-1 commit. * test(link): a forced revoke that throws after its commit keeps its tombstone Final review P3-5 of #8661 (coverage): after the commit the link is gone, so a later throw answers link_remove_failed and the tombstone stays as the only cleanup evidence. * fix(link): a forced revoke keeps a tombstone already written for its link Security review P2-C: recordTombstone replaced any tombstone of the same link, and removeOwnTombstone dropped the slot by the new token. A forced revoke F0 in another runtime writes T0 and has not committed; F1 replaces it with T1, fails before its commit and drops T1; F0 commits with no tombstone and recover answers tombstone_not_found. recordTombstone now keeps an existing tombstone ("kept") and the attempt then owns none it could drop. Tests: F1 failing keeps T0, and F1 committing keeps T0 (both failed before); the tests that simulate another writer swapping a tombstone now do so explicitly. * fix(link): the unbound fallback for an older Child is refused while another link may reach the same machine Security review P2-A: enrollment refuses a second link with the same primary alias, so the guard (no other Home-initiated link with this alias) never fired in a state this Home can create. It now refuses the unbound disconnect, and the unbound --purge, while another Home-initiated link has the same pinned host key (the machine enrolled under another alias or address) or names this alias as its alias or among its routes. Tests use stores enrollment can produce, on the ordinary and the --purge path (all four failed before); the old test with two links of the same alias is replaced. Known limits: the machine enrolled with another Home, or under a new host key. * fix(link): a bound revoke finishes its own interrupted cleanup on full ocx and ocx-child Security review P2-B, a regression from dev, where the plain command resumed both: full ocx resumed only while still connected, so once clearClientConnection had run every bound retry answered disconnect_pending; ocx-child answered residual for a detach interrupted after state.json went. Full ocx now resumes an unfinished receipt once the connection is cleared and no connect is pending (connect refuses while a disconnect is unfinished, so no link is attached and the cleanup cannot detach a newer one; no receipt schema change, which an older ocx would refuse). ocx-child resumes when the owner record names this link in phase detaching and no attach rollback is left; an attach interrupted before its state write (phase attaching) stays residual. Tests: the classifier rows and owner_link detach resume both failed before; another link is still refused. cargo fmt --check, clippy -D warnings and cargo test pass locally (1.100.0). * fix(link): only a recognised no-write refusal settles a bound revoke as failed_clean Security review P3: lastStderrReason failed open, so any exit 5 whose last stderr line was not disconnect_pending (an unknown reason, garbled or extra output) settled failed_clean, and every exit 6 did. classifyBoundRefusal (remote-plant.ts) reads the last line against a closed set: full ocx child_link_mismatch with a no-write reason, or ocx-child detach --expect-link <this link> refused (conflict|residual); anything else counts as a cleanup attempted, on the ordinary and the --purge path. Also drops the dead purged.bound store. Tests: the outcome each answer settles as in a journalled revoke, ordinary and --purge, and the expect_link_unsupported refusal (the four fail-open rows failed before). * fix(link): an unreadable Child-initiated marker refuses as invalid_state; recover text ignores prototype keys Security review P3: a corrupt marker made every bound revoke refuse as client_initiated_link and print that the machine joined its Home itself; readChildLinkMarker tells absent, naming a link and unreadable apart, and the bound check refuses an unreadable one as invalid_state (isChildInitiatedLink keeps failing closed for its other callers). RECOVER_REFUSALS read prototype keys such as constructor; it now uses Object.hasOwn. Both tests failed before. * docs(link): outcomes of bound refusals, the wrappers' own exits, and each hint's remedy Security review P3: structure/remote-link.md listed failed_clean causes without recognised exit 5/6 refusals and expect_link_unsupported, and called every other nonzero exit unknown without saying which exit 5/6 count; it now names classifyBoundRefusal, child_disconnect_pending, the wrappers' own exits (POSIX 125/127 or 125/1, a failed exec 126/127, Windows 1/126/127) and that an older full ocx runs its root preflight before the usage error (cli-management too). The guide (en, es) gives what child_link_mismatch, child_residual and child_disconnect_pending mean and what to do. * fix(link): a forced revoke re-establishes its tombstone at the commit when the kept one was dropped Review round 10 P1: F1 kept F0's T0 (written null); F0 then failed while the link was listed and dropped T0; F1 committed with no tombstone. The commit step now checks, under the lock that removes the record and before the key revoke, that a tombstone for the link exists, records this attempt's own (owned, so a later failure drops it) when it does not, and answers tombstone_write_failed with link and key intact when it cannot. Test failed before. * fix(link): a commit-time tombstone write that throws after writing is owned and dropped Review round 11 P3: written was set only after recordTombstone returned, so a write whose chmod threw left an unowned tombstone beside the kept link. The catch now owns it before returning tombstone_failed, and the non-ok path drops it by its token; a read error in the presence check also answers tombstone_write_failed. Test failed before. * fix(link): a commit-time tombstone the cap refuses answers tombstone_limit Security review P3-c: a LinkTombstoneLimitError at the commit-time tombstone write was answered 503 tombstone_write_failed; it now answers 409 tombstone_limit. Both answers say what holds for this attempt only (it revoked no key and removed no record; a forced revoke never contacts the Child), since an earlier attempt of a resumed revoke may have done more, and the limit text offers --forget for a machine that is gone or whose cleanup cannot be proven. Test failed before. * fix(client): a link-bound disconnect with nothing attached or pending answers already disconnected Security review P3-e: after a full ocx disconnect finished but its SSH answer was lost, the bound retry answered disconnected (exit 5), so the Home kept the link where the plain retry succeeded on dev. With no connection, no unfinished disconnect and no pending connect, nothing of the link is left on the machine, so the bound call now answers exit 0 with alreadyDisconnected and writes nothing, as ocx-child answers NotAttached; a leftover sidecar or marker naming the link (or an unreadable one) still refuses, and a machine that became disconnected after that check refuses inside disconnectClient. Tests failed before (the sidecar case answered disconnected). * test(client): both full-ocx resume rules run through handleDisconnectCommand; the --expect-link connect tests stub the Codex probe Security review P3-h: only the pure classifier covered the two resume rules; a bound disconnect now resumes its own prepared receipt while connected, and finishes one whose connection was already cleared (a last step made to fail once leaves connection_cleared; this failed on the classifier before df3db1c). The four --expect-link tests in client-link-connect.test.ts needed --timeout 60000 because connectClient probed the real Codex for its supported efforts; they now stub catalogCompatibility as the other tests there do, and run in about 25 ms. * docs(link): split the child_link_mismatch remedy; never tell an operator to disconnect a machine another link owns Security review P2-1: the guide (en, es) gave one remedy for every child_link_mismatch state, "disconnect it there and revoke with --force", which for a machine enrolled again as a new link (or joined to a hub or another Home) disconnects the newer link. Now: if it belongs to another link, a hub or another Home, revoke the old link with --force and do not disconnect it there; if a connect or key rotation is in progress or its state is unreadable, repair it first. The guide also says what child_residual, child_disconnect_pending and expect_link_unsupported mean and what to do (P3-f), that the guard counts Home-initiated links of this Home (P3-d), and that the cap refusal comes before the key is revoked. The server answers each of the four hints with its own fixed message carrying the same remedies, on the ordinary and the --purge path. * docs(cli): --expect-link's promise names the cleared-disconnect resume and the already-disconnected answer Security review P2-2: the registry, the capability flag summary and the generated skills reference promised that --expect-link disconnects only a connected Child of that link and that every other state, disconnected included, changes nothing. Since the cleared-disconnect resume a disconnected machine with an unfinished disconnect finishes it, and with nothing attached or pending the call writes nothing and answers already disconnected (exit 0). All three, and structure/cli-management.md, now say so; the list of refusing states reads another connection's unfinished disconnect while connected. * docs(link): structure and help sentences hold in every state (sentence audit), and name the guard's client-initiated limit Security review P3-b, P3-d and the sentence audit: structure/remote-link.md no longer says a later forced revoke replaces a tombstone (recordTombstone keeps one); it states that a tombstone whose owner died or whose drop met the busy lock stays until the link is removed, counts toward the cap, and may carry stale routes (recover reads only the alias, explicit route and key); "no revoke removes a tombstone it did not write"; the guard counts only Home-initiated links, so a Child that joined this Home by itself is outside it; a recognised refusal restarts the tunnel and settles failed_clean except on a resumed retirement (tunnel down, unknown); the commit-time tombstone failure answers tombstone_write_failed or tombstone_limit before this attempt revoked a key; no connection answers already disconnected unless a sidecar or marker names the link. The registry and the guide (en, es) carry the same conditions. * fix(cli): a journalled revoke names the link-bound refusal hint; #8654's truth table covers the commit-time tombstone Follow-up to the #8654 merge. journalledRevokeError dropped the remote_disconnect_failed hints, so a journalled revoke could not tell child_link_mismatch from a timeout; it now prints the hint and the CLI's own text for it, from a closed set (Object.hasOwn, plain-word pattern), never the server message; child_disconnect_pending keeps the unknown outcome's conditional repeat guidance. The truth table gains rows for those hints (their texts claim a state) and corrects tombstone_limit and tombstone_write_failed for the commit-time check: it runs after the key_revoked intent and stopLink and before the key revoke, so a fresh revoke settles unknown and "this attempt did not touch the link" no longer holds; the CLI tombstone_limit text and its test now claim only no key revoked, no record removed and no Child contacted (the server's early refusal keeps #8654's sentence). Tests: one per hint, closed-set rejection (ssh_failed, constructor, a path), and the journalled commit-time limit settling unknown. * docs(link): a cap refusal at the final step has also stopped the tunnel Sentence audit after the #8654 merge: the guide (en, es) said a fresh tombstone_limit refusal leaves the link, its key and the Child as they were; one met at the commit-time check has also stopped the tunnel. * test(client): every link connect in client-link-connect.test.ts stubs the Codex effort probe Security review P3-h, continued: three older connect-then-disconnect tests timed out at 5 s locally because connectClient probed the real Codex for its supported efforts; a timed-out test kept running into the next one (an unhandled error between tests), which made the following --expect-link and config-import tests fail too. All five connectClient calls that lacked it now stub catalogCompatibility as the rest of the file does; the whole file runs 66/66 in about 2 s at the default timeout. * Revert "fix(client): a link-bound disconnect with nothing attached or pending answers already disconnected" Review round 13 P1: a Home-initiated enrollment writes its link record before it sends the Child's connect, so a concurrent ordinary revoke could receive alreadyDisconnected, remove the record and key, and the delayed connect then attaches that link on the Child with no record and no tombstone. The exit-5 refusal (disconnected) keeps the record. The lost-answer case this covered becomes a known limit with --force as the way out. The two resume tests that came later stay; the leftover-sidecar test, which existed only for the reverted answer, goes. * docs(link): drop the already-disconnected answer; child_link_mismatch and child_residual give safe remedies Review round 13. P1 follow-up: the registry, capability summary, skills reference, cli-management and structure no longer promise exit 0 for a disconnected machine; structure names the lost-answer case as a known limit (the bound retry keeps the link, --force removes it) and why (an enrollment writes its record before its connect). P3: child_link_mismatch is an identity or state refusal, which also covers a disconnected machine and a link the Child started (run ocx disconnect there). P2: child_residual says to inspect first, since what is left can be an interrupted attach of another link and a plain ocx-child detach would remove that link too. Guide en and es. * fix(link): the child_link_mismatch and child_residual messages and CLI hints carry the safe remedies Review round 13 P2 and P3, in the server's fixed messages (BOUND_REFUSAL_MESSAGES) and the journalled CLI hints (BOUND_REFUSAL_HINTS): child_residual no longer recommends a plain ocx-child detach unconditionally, and child_link_mismatch covers a disconnected machine and a client-initiated link. * fix(cli): a forced revoke's success text never sends the operator to disconnect a Child another link owns Review round 14 P2: --force is now the remedy when the Child belongs to another link, a hub or another Home, yet its success text said to run ocx disconnect on the remote client, or a plain ocx-child detach on a lightweight one, either of which removes the link the refusal protected. The text, the revoke usage line and the guide's Remove here only step (en, es) now require checking there that the Child is still connected to this link first, and point a lightweight Child at the link-bound ocx link recover. Tests updated first; they failed on the old text. * docs(cli): the revoke capability, its skill reference and the CLI reference check Child ownership before a disconnect Review round 15 P2: the link revoke capability (and the generated skills reference) still said to run ocx disconnect on the remote client after a forced revoke, and the CLI reference (en, es) did too. All now say to check there that the Child is still connected to this link first, to leave it if another link, hub or Home owns it, and to use the link-bound ocx link recover for a lightweight Child. * docs(link): recover's residual and unsupported answers say to inspect before a plain ocx-child detach Review round 16 P2 (recover side): child_residual from recover can be an interrupted attach of another link, which a plain ocx-child detach would restore and then remove. The management message, the link recover capability (and its generated skill reference) and the CLI reference (en, es) now say to inspect first and run it only when that is safe. child_recover_unsupported likewise no longer sends the operator to a bare detach: an older ocx-child cannot check which link it belongs to, so plant a current one, check ownership first, or forget a machine that is gone. * docs(link): child_recover_unsupported also asks to inspect an interrupted attach before a plain detach Review round 17 P2-1: checking current ownership is not enough, since an interrupted attach can keep a rollback to another link that a plain ocx-child detach restores and then removes. * fix(link): every revoke and recover remedy names the machine check before any disconnect, and the next step follows the recorded outcome Final security review of #8662 at 29be1bd. P2-1: the child_link_mismatch remedy said "if it joined this Home by itself, run ocx disconnect on it", which also matches a machine whose stale Home-initiated link L1 sits beside the live client-initiated L2, and disconnects L2. The branch is deleted in the server message, the journalled CLI hint, both guides and the structure row; a client-initiated link cannot answer a Home's revoke. P2-2: the journalled child_residual hint said to repeat with the same operation id, which only replays a failed_clean answer. The hints are now functions of the outcome the answer recorded: a new operation id after failed_clean, the same id after unknown, "revoke again" for a plain revoke (child_link_mismatch, child_disconnect_pending, expect_link_unsupported). Rule for every remedy: ocx disconnect or ocx-child detach is named only after the check that allows it (ocx connect status --json shows this link's id or no connection); every other branch says what not to do and which Home-side command to run. child_residual and recover's child_residual and child_recover_unsupported no longer offer a plain detach (an interrupted attach of another link would be restored and removed); a person can forget the tombstone of a machine that is gone or whose cleanup cannot be proven (P3-10: the --forget command now carries --link-id <id> --yes; "plant a current ocx-child" is gone). P3-2: --force for a Child that shows no connection is safe only once any enrollment of this link has finished (said in the hint, guide and structure). P3-3: child_disconnect_pending checks whose disconnect it is first, finishes it only for this link or no connection, and names the unsafe-receipt refusal. P3-4: no POSIX-only ocx-child path remains in these remedies (they no longer name a detach). P3-5: expect_link_unsupported says an older planted ocx-child cannot be updated from this Home. P3-6: a plain ocx link revoke prints the validated closed-set hint text too (plainRevokeError). P3-7: the guide's Remove here only block gives ocx link recover --link-id <id> for a lightweight Child and the check-then-disconnect order with the window for a full install, in en and es with identical code blocks. P3-8: the commit-time tombstone refusals say the retirement receipt stays claimed (structure, guide, link-routes comment). P3-9: link_present says --purge only for a lightweight Child. P3-11: the revoke usage line and the full-Child force text use the same check (this link's id or no connection); the ephemeral force text keeps only the link-bound recover. P3-1: structure states the ocx-child NotAttached race as a known limit. P3-12: the client_initiated_link row (unreachable for a Home's revoke) is gone and the cap test's title no longer claims a key it does not observe. Tests failed first on the old texts: the journalled hint table (each hint with each outcome, with absent texts), the plain-revoke hint tests, the force texts, recover's link_present, and the server message rows. * fix(link): child_link_mismatch's lightweight check runs the planted ocx-child by its path A planted ocx-child is usually not on PATH (POSIX or Windows), so a bare ocx-child connect status --json may not run. The hint, the server message and the en/es guides now name the planted copy: ~/.cache/opencodex/bin/ocx-child, or %LOCALAPPDATA%\opencodex\bin\ocx-child.exe on Windows. Found while writing the sentence-by-state table; the CLI test failed first. * fix(link): the lightweight check names the Windows fallback location, and the forced-revoke recipe follows the receipt's own recovery Terra round 19: when LOCALAPPDATA is not set the plant uses %USERPROFILE%\.cache\opencodex\bin\ocx-child.exe, which the child_link_mismatch check (CLI hint, server message, en/es guides) now names. The skill recipe for a forced revoke said to follow an ocx disconnect recovery; it now gives the full-Child check-then-disconnect and the lightweight ocx link recover. The CLI test failed first. * fix(link): alias_linked revokes the other link only if it is stale too, and otherwise leaves the machine and lets the tombstone wait Final review of #8662 at 2166a43, P2. A force-revoked ephemeral L1 leaves a tombstone; the same machine is enrolled again on this Home under the same alias as L2 (enrollment takes only the alias lock). Recover then answers alias_linked, whose step was to settle that link's operations, revoke it and recover: followed, L2's bound revoke succeeds, the live L2 and its key go, and the recover purges the binary of a machine with nothing attached. The step is now conditional in the CLI text, the server message, the en and es guide and the en and es CLI reference: check which link the machine runs; revoke the other link first only if it is stale too; if the machine runs it, leave it: the tombstone waits until that link is removed and recover runs then, or a person forgets it once the machine is confirmed clean. The CLI and server tests failed first and now also assert the unconditional step is gone. * fix(link): expect_link_unsupported revokes the other link first only if it is stale too Final review of #8662, P3-e, the same shape as the alias_linked P2: "or revoke the other link first" had no condition. Under the same pinned host key that link's revoke meets the same guard and loops; through a shared route it would disconnect that link. The CLI hint, the server message and the en and es guide now name both and revoke it only if the machine does not run it. The CLI hint test failed first. * docs(link): the guide's forced revoke carries --link-id and --yes, and the unbound-retry guard names the alias itself Final review of #8662, two P3-h items. The guide wrote `ocx link revoke --force`, which the CLI refuses without --yes (and a link id); it now writes `ocx link revoke --link-id <id> --force --yes`. The description of the guard that refuses an unbound retry left out a link whose own alias is this alias; it now says "as its alias or among its routes". English and Spanish.
Summary
Lane O5b, part 1 of the disposable-machines follow-ups to #8612 (
ocx link recover): the correctness fixes from #8612's final reviews. The larger follow-ups go in their own pull requests (see "Not in this pull request").1. A forced revoke's tombstone no longer outlives a revoke that threw. A forced revoke of an ephemeral link writes its tombstone first, before any journal intent and before the tunnel stops. Before this change, the explicit drops covered refusals and failed steps, but not a throw between that write and the record-removal commit (for example
stopLinkrejecting). Such a throw left the tombstone beside a live link: recover refused it (link_present), and it counted toward the 256 cap until a later committed revoke settled it.removeReserved(src/server/management/link-routes.ts) now setscommittedonce the one locked step that revokes the key and removes the record (from dev's #8416) has succeeded, and itsfinallydrops this revoke's own tombstone (matched by its attempt token, and only while the link still exists) whenevercommittedis unset. The explicit drops from #8416 (a changed link, a commit step that did not succeed, a failure after it) stay, and repeating a drop is harmless; the one at the first intent, which runs before thetry, stays too. The tunnel hold is now taken inside thetryas well, so a hold that throws is covered too. The supervisor'sholdLink(src/link/supervisor.ts) releases its own hold when the cancellation it runs throws, so it never leaves a hold that nobody can release. A stale comment that said a later ordinary revoke would strand the tombstone is corrected: a committed ordinary revoke removes it.2. Recover waits while another link names the machine's alias. Recovering a force-revoked link L0 runs
detach --purge --expect-link L0on whatever machine answers at L0's alias. If that machine was enrolled again as L1, or L1's revoke ran its disconnect but did not commit (a plain revoke journals nothing), the Child can answerNotAttached. Recover would then settle L0 and purge the binary under L1. Inside the alias lock, before any SSH, recover now answers409 alias_linkedwhile any Home-initiated link names the target's alias, compared without case as the alias lock does. When L1 is still attached the Child already refused (child_conflict), so this refusal changes nothing on the path that was already safe. Client-initiated links do not block recover. The way out is to settle any open operation on L1 (settling alone keeps the link), revoke L1, then recover; the message and the guide say so. Inside the lock, recover first applies the checks from #8416 (link_presentwhen this link still exists,link_retirement_pendingwhile its removal receipt is outstanding), then this alias check.This guard adds no deadlock of its own, including at the 256 cap. If L1's machine is unreachable, recovering L0 already failed (
ssh_failed), because it is the same machine. If L1 is reachable and attached, the Child already refused (child_conflict). The guard changes only the case where L1's disconnect ran, and there recover would have freed a slot by settling L0 and purging the binary under L1, which is the case it prevents. A full cap that refuses the forced revoke of an unreachable L1 is the cap problem itself, with or without the guard. The proposal below addresses it. The guard matches by alias, so it also blocks two machines that share an alias through different explicit routes and the same pinned host key; recovering the older one waits until the newer link is gone. That is a limit of alias-based identification, accepted here as the conservative choice. Documented in the Remote Link guide (English and Spanish),structure/remote-link.mdand the recover capability text (regenerated skill surface).3. Stale maintainer text. In
structure/remote-link.md:binary_in_use: recover never answers it, and settles on a report naming the link withrestored: true,purged: falseand the in-use marker;binary_in_usehint is described as a--purgerevoke's only;NotAttachedreport is trusted as the link's own restore whether or not the binary stays.The
src/link/link-recover.tsdocblock names the in-use case. A new test row pins the check order: the in-use marker on a report for another link answersreceipt_unbound.Proposal, nothing built: tombstones for disposable machines destroyed on purpose. Each forced revoke of an ephemeral link writes one tombstone. Only
ocx link recover(which needs the machine to answer) or a person'socx link recover --forget(refused from agents and CI) removes it. At mostMAX_TOMBSTONES= 256 wait; beyond that a forced revoke of an ephemeral link is refused, and its link and key stay active. A provisioner that destroys its VMs and then force-revokes them never settles any. Starting from an empty store:After that, every routine revoke of a destroyed VM is refused, which leaves a dead machine's link key valid. Proposed rule, for the owner to decide:
Revoke before destroying (documentation only). A provisioner revokes with
--purgewhile the VM still answers, then destroys it. That revoke cleans the Child itself and writes no tombstone.--forcestays for a VM that is already unreachable, or whose purge failed. Those cases still write a tombstone, as today.For the tombstones that remain, a destruction claim needs authority the Home can check. The Home cannot verify a provider's word, and an unverified claim would lose the only durable cleanup path for a machine that comes back (a mistaken claim, a restored snapshot, a VM still running). The journal's retention is bounded, so it cannot replace the tombstone either. Two options, both opt-in per Home:
--forgetfor tombstones of links that key enrolled, with each use appended to a durable audit file;In both, the claim is part of the revoke's replay identity, and
--forgetstays a person's command otherwise.I will build nothing for the second part until the owner picks an option. Alternatives considered and not proposed: a larger cap (moves the cliff), and age-based expiry (a machine that returns later keeps a restored
~/.codexpointing at a revoked key, with nothing left to clean it).Not in this pull request (each its own pull request, in this order):
ocx disconnect --expect-linkon full Children, a version gate on the Home, and the ordinary revoke's commit-time tombstone removal only after a link-bound answer;ocx link recover --operation-id,resolveLinkOperationonce recover proves the Child clean);Stays inert by default. Nothing changes for a Home that never force-revokes an ephemeral link. A recover that today reaches a machine still linked under its alias now answers 409 before contacting it.
Verification
Tests that failed first, each against the code before its fix:
tests/server/link-recover.test.ts"a throw after the early tombstone write (stopLink rejecting) drops that tombstone and keeps the link": the tombstone stayed.tests/server/link-recover.test.ts"a throw while taking the tunnel hold drops the tombstone and keeps the link": the tombstone stayed.tests/clients/link-route-supervisor.test.ts"a hold whose cancellation throws is released, so the link can be reconnected": the hold stayed andreconnectansweredfalse.tests/server/link-recover.test.ts"recover while another link names the alias ... is refused with 409 before any SSH, whatever the alias's case": recover ran the purge.tests/server/link-revoke-operation.test.ts"a journalled force revoke whose first intent cannot be written leaves the tunnel running" gains the tombstone assertion. With the drop at the first intent removed, it fails.The runs below were made at 64f33ea, before the merge of dev (#8416) that re-resolved
removeReserved. On the merged head 80a7bde the evidence is hosted CI run 43381913375 (gates, test changed, structure gate and docs site build pass) and a fresh final review of that head (no P0-P2). The tombstone drop is best effort: it runs under the non-waiting config lock, so a drop that finds the lock busy leaves the tombstone until the next revoke of that link replaces or removes it, as before this change.At head 64f33ea:
bun testontests/server/link-recover.test.ts,link-revoke-operation,link-management-routes, the fourlink-enrollment*suites,tests/clients/link-revoke-suspend,link-operations-journalandlink-alias-lock,tests/cli/cli-link-recoverandcli-link-enrollment, both layout tests,docs-spanish-localization,skill-ocxandstructure-ssotand both supervisor suites (tests/clients/link-supervisor.test.ts,link-route-supervisor.test.ts): 484 pass, 0 fail (at e52ef60). At 64f33ea, the two supervisor suites andlink-recover: 176 pass, 0 fail.bun run typecheck,bun run structure:check,bun run skill:surface:check,bun run privacy:scan: exit 0.NOT RUN: the full
bun run test;bun run test:changed; the Rust crate's suites, since this pull request does not changenative/ocx-child.Checklist