Repository navigation
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
Merged
Conversation
… 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.
…e 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.
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.
…e 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.
Contributor
|
Caution Review failedThe pull request is closed.
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. |
Contributor
|
✅ Deterministic PR hygiene checks passed. |
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.
… 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.
…e 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.
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.
…ournal 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.
One conflict, docs-site/src/content/docs/es/guides/remote-link.md: this branch's journal paragraph and #8612's recover paragraph are kept in the English page's order (journal, then recover). The generated skills reference is regenerated on the merged tree (51 declared capabilities); everything else merged on its own.
…g 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.
…ad 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.
… 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.
…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.
One conflict, tests/server/link-revoke-operation.test.ts: both sides added imports and tests. The imports are united (OPERATION_JOURNAL_MAX_RECENT_SETTLED from this branch, the retirement helpers and resolveLinkOperation from #8416), and this branch's recent-bound refusal test sits before #8416's retirement and resumed-cleanup tests. The rest merged on its own; the skills reference was checked against the merged capability registry.
…d 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.
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.
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.)
…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.
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.
…e 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.
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.
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.
…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.
…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.
…n 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.
…utcome 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.
…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.
…e 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.
…lid 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.
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.
…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.
…aiming the link changed during this revoke
…id still owns one
… id so they run as printed
…resumed tombstone_limit can leave behind
…ince confirm-host already pinned the host key
…he refused attempt left alone
…wn or residual; an open one is repeated
…med one and names what a first-intent failure leaves
lidge-jun
marked this pull request as ready for review
November 13, 2026 09:47
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. |
lidge-jun
added a commit
that referenced
this pull request
Nov 13, 2026
Conflicts: link-routes.ts keeps #8654's early tombstone_limit message verbatim (the attempt touched nothing) and this branch's commit-time tombstoneLimit, reworded for an attempt that already stopped the tunnel; structure/remote-link.md keeps this branch's bound-refusal outcome sentences and #8654's way out for an open entry; the guides keep this branch's recover paragraph with #8654's cap sentences, and in Spanish #8654's paragraph order.
lidge-jun
added a commit
that referenced
this pull request
Nov 13, 2026
…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.
lidge-jun
added a commit
that referenced
this pull request
Nov 13, 2026
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.
lidge-jun
added a commit
that referenced
this pull request
Nov 13, 2026
… 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.
3 tasks done
lidge-jun
added a commit
that referenced
this pull request
Nov 13, 2026
…und detach finishes its own interrupted attach (#8691) * fix(cli): O1c-8, the journalled revoke's guidance runs as printed and 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. * fix(link): alias_linked checks the machine first, keeps it when the check 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. * fix(link): expect_link_unsupported says how to tell the other link is 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. * fix(link): child_disconnect_pending finishes a disconnect by hand only 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. * fix(link): child_link_mismatch has a branch for a machine that shows 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. * fix(link): a forced revoke's full-Child step uses ocx disconnect --expect-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. * fix(link): a forced revoke of a link without a recorded Child type names 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. * fix(ocx-child): a bound detach finishes this link's own attach interrupted 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. * fix(link): child_recover_unsupported gives a way out that runs as printed, 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. * fix(link): the Windows planted path is said to be a Command Prompt path, 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. * fix(cli): ocx link cleanup's Windows steps run as printed and use the 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. * fix(gui): the force-remove dialog and notices use the link-bound commands, 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. * docs(ocx-child): the residual classification comment no longer calls a plain detach the way out * fix(link): alias_linked leaves the other link, since no status check can show it is stale * fix(link): expect_link_unsupported no longer judges the other link stale from a status check * fix(link): no remedy advises a plain ocx-child detach on the strength of a status check * fix(gui): the unknown-type notice offers no unbound ocx-child detach, in every locale * fix(cli): ocx link recover prints its own child_recover_unsupported text with the link id * docs(link): the structure note and recover reference describe the bound detach finishing its own interrupted attach
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-ups from the final review of #8638 (the operation journal behind
ocx link addandocx link revokewith--operation-id), the replay horizon chosen for disposable-machine churn, and CLI guidance for every refusal a journalled revoke can answer. That guidance is derived from a truth table that holds with #8416's resumed revokes, #8661's tombstone handling and stale retirement receipts.The CLI explains refusals it used to hide. The CLI never prints an API error body: some carry secrets, so
linkRequestkeeps only filtered, closed fields. These paths used to print only "Link management request failed (N)". Every text is now taken from the table below. A text claims a state only when that state holds in every row for its code. Where a repeat can give the same answer again, the text says what that second answer means and which different step to take, so it never sends the caller round the same step forever.409 operation_journal_fullcarries a closed field,"bound": "unsettled" | "recent", and gets its own guidance on add and revoke. It adds(code operation_journal_full), and(bound <bound>)when the Home sends it, and keeps exit 5. On a revoke it says nothing was changed. On an add it says only that the apply changed nothing, because confirm-host has already written the known_hosts pin. The add's--require-ephemeralrefusals say only that the apply changed no key, link or Child file, because a refused census still records its journal entry.operation_mismatch,link_operation_openand a revoke'soperation_journal_fullsay nothing was changed.link_operation_in_progressandtombstone_limitsay only that this attempt did not touch the link, its key or the Child.operation_journal_unreadablemakes no state claim. It says what a laterlink_not_foundmeans, because a replay after a resumed removal can meet it once that removal finished.link_retirement_ownedandlink_retirement_mode_mismatchclaim nothing about what an earlier attempt changed. They name the way out: the revoke of the link that owns the removal, in whatever recorded state, or a plain forced revoke.operation_journal_failedadds a next step: fix the journal's disk and repeat the same id; try a new id only throughlink_retirement_owned's guidance.link_changedsays that the link, or the record of its unfinished removal, no longer matches what the removal started from. Readocx link status, then repeat the same id. If it answerslink_changedagain, the link may have been edited after its removal began. A new id can remove it only when no unfinished removal of the link remains.unknownoutcome says to repeat the same id first: if this id still owns an unfinished removal, the repeat resumes it. If the repeat does not finish, read the entry's state. Forunknownorresidual, check the Child and resolve. Foropen, fix what stopped the revoke and repeat; resolve refuses an open entry.Printed text is built only from closed or validated values: the caller's validated operation id and link id, a closed outcome, a closed bound, and an error code matching the filter's pattern. Every revoke and recover command it prints carries
--link-id(and--yeswith--force), so it runs as printed, with one exception left for a follow-up: theoperation_journal_unreadabletext mentionsocx link revoke --forcewithout--link-idand--yes, which is a usage error as printed and runs nothing. The helper re-checks the outcome, the code and the link id itself, and the server's message is never printed. The server's owntombstone_limitmessage and both guides say only what the refused attempt left alone; they no longer claim the link and its key stay active.Known limit, not fixed here (#8678): a route edit (
ocx link routes) does not check for an outstanding retirement receipt. A link edited after its removal claimed a receipt therefore answerslink_changedto every revoke, including a new id, the owner's resume and a plain--force, until the record matches the receipt's copy again. The CLI text says so conditionally.The replay horizon is 2 hours instead of a day.
OPERATION_REPLAY_MIN_MSis 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 recently-settled bound stays. That allows about 500 journalled operations per hour sustained (1024 / 2.05 h). With a one-day horizon the limit was about 42 per hour, and ten disposable machines that each live ten minutes (about 120 operations per hour) hit it after about 8.5 hours. Now they put about 246 entries inside the window, a quarter of the bound.The file holds about 512 entries (about 0.5 MiB), at most about 1.5 MiB in a burst. On top of that come the entries an outstanding retirement receipt pins: at most two per readable receipt, and every revoke entry of a link whose receipt cannot be read. Unsettled entries are never pruned and the 30-day retention is unchanged.
What a caller can rely on:
link_operation_in_progressafter the lock wait changes nothing and is retried. Afteroperation_journal_unreadableor a 5xx the caller repeats with the same id; neither proves that nothing changed.link_exists.link_not_found.Truth table (also in structure/remote-link.md, "Operation journal")
What a journalled revoke's refusal may leave changed, per code, on a first and on a resumed attempt (#8416), and what the CLI prints for it (
journalledRevokeErrorinsrc/cli/link.ts). A text may claim a state only when it holds in every row for its code; otherwise it names the next step only. Only a non-forced cleanup touches the Child.operation_mismatchlink_operation_openopenRevokeConflict, only for an id with no entry; nothinglink_operation_in_progressoperation_journal_unreadableopenRevokeConflictorforeignRetirement: nothing; a replay after a resumed removal answered 200: the removal finishedlink_not_foundmeans the link is goneoperation_journal_fullopenRevokeJournal, only for an id with no entry; nothingoperation_journal_failedstopLink): this attempt changed only its journal entry (a fresh one opened it; a resumed one may also have taken back its receipt,reownLinkRetirement) and a forced revoke's own tombstone, which it then drops at best effort (a busy config lock leaves it beside the live link, where recover refuses it aslink_present); for a resumed revoke an earlier attempt may already have stopped the tunnel or revoked the key. A later intent comes afterstopLink: the tunnel is down, and for thekey_revokedintent or the purge'sremote_cleanupcompletion the Child cleanup has run; at therecord_removedintent the key is revoked too and the receipt stays claimed with the record still listed. Before the receipt is cleared (beforeReceiptCleared): the removal finished. A resumed owner can meet the same live failure again and keep its receiptlink_retirement_owned's guidancetombstone_limitfailed_clean, nothing else. Resumed: an earlier attempt may have revoked the key, stopped the tunnel and dropped its tombstone; this attempt meets the limit before its first intent and itsstopLink, so it wrote no tombstone or intent and stopped nothing, but it may have taken back a receipt a plain--forcedisowned (reownLinkRetirement), and an entry already open settlesunknownwith this code (settleResumedRevoke)link_retirement_owned, the revoke of the link that owns it in whatever recorded state, or a plain--force --yestombstone_write_failedrecordTombstonecan throw after its atomic write, before this revoke counts the tombstone as its own, so the file may remainlink_retirement_ownedforeignRetirement, before the entry is openedocx link operations --jsonshowslinkId), or a plain--force --yes; a plain revoke without--forceonly when no journalled operation owns itlink_retirement_mode_mismatch--operation-idat this head--force --yeslink_changedreadRemovalTargetmeets an outstanding receipt whose copy differs from the stored record (it was edited after the receipt was claimed, for example byocx link routes, which does not check for a receipt: #8678): nothing this time, and every revoke (a new id, this id's resume, a plain--force) answers it until the record matches the copy again. The claim (the record changed in another process before any receipt was claimed): a cleanup may have run, and the answer is journalled with no receipt for this id, so this id replays it while a new id reads the record afresh. The commit (the record or the receipt changed after this id claimed its receipt): a cleanup may have run, and while the receipt is still this id's its repeat resumes the removal before any replay (it may run the cleanup again) and meets the same comparison, answeringlink_changedagain while the record differs from the receipt's copy (the stale receipt above)ocx link status, repeat with the same id; if that answerslink_changedagain, the link may have been edited after its removal began, and a new id removes it only when no unfinished removal of the link remainslink_not_foundreadRemovalTarget, before the entrykey_revoke_failed,link_remove_failed, alias-lock failures,operation_interrupted,revoke_failedunknown, repeat the same id first (it resumes a removal only if this id still owns one); if it does not finish, read its state:unknownorresidual, check the Child and resolve;open, fix what stopped it and repeat the same idCompatibility and what stays unchanged
boundis additive. An older CLI drops it and still refuses with its plain message and exit 5.Exit codes are unchanged. Every new text is raised with the original status.
Callers without an operation id. Most new CLI texts run only for
ocx link addandocx link revokewith--operation-id. These changes reach callers without one:link_suspendedtext ofocx link reconnectand the dashboard's Retry;tombstone_limitmessage, which any client of the management API sees;--require-ephemeralrefusal texts, which are printed whether or not--operation-idis passed.A revoke without
--operation-idand the other add refusals behave as before. Nothing here adds a Home or Child effect.The horizon only shortens how long a settled entry is protected, once more than 256 settled entries exist.
Verification
Test-first:
tests/cli/cli-link-operation.test.tsfailed on the earlier wording, then passed. In this round that covers thelink_changedtext, the conditional unknown hint with its open-state branch,--link-idin the printed commands (all but theoperation_journal_unreadablemention above), and the add-side and--require-ephemeralwording. The validated-link-id helper test guards the fix; it already passed before, because the old text printed a placeholder.tests/server/link-recover.test.tsasserted the newtombstone_limitmessage, failed on the old one, then passed; it also pins that a fresh refusal stops nothing and revokes no key.bound: server assertions failed with noboundfield.tests/server/link-revoke-operation.test.tspins afailed_cleanreceipt owner at the tombstone limit. It is refused, refused again while capacity is still full, a new id answerslink_retirement_owned, and the original id commits once a slot is freed.Commands on c4701ec (bun 1.4.4,
TMPDIR=/tmp):bun run typecheck→ exit 0bun run privacy:scan→ exit 0bun run structure:check→ exit 0bun run skill:surface:check→ exit 0; the generated reference reads "Declared capabilities: 51"bun scripts/test.ts --parallel=2over tests/cli/link, tests/clients/link, tests/server/link, the test-layout tests, the file-size ratchet, structure-ssot, skill-ocx, docs-spanish-localization and tests/clients/link-boundary (144 files) → exit 1: 2539 pass, 27 skip, 53 fail.tests/clients/link-ocx-child-conformance.test.ts(1) andtests/clients/link-ocx-child-e2e.test.ts(2). Each stops at "cargo build failed: rustup could not choose a version of cargo"; see NOT RUN.tests/clients/link-child-binary-cache-fill.test.ts(feat(link): fill ocx-child builds under ocx-child-builds/ when an upgraded Home starts, from digests in its verified package #8624), each with "unsafe cache directory". Earlier rounds found it failing the same way on dev on this machine. This branch does not touch that code.git merge-tree --write-tree origin/dev HEAD→ exit 0 against dev 85fbba8.Merges of dev, each with one conflict:
tests/server/link-revoke-operation.test.ts; both sides kept.-F nonesentence appears once per--proxy-commandflag.NOT RUN:
bun run testsuite (this machine runs focused files only);tests/clients/link-ocx-child-e2e.test.tsand the conformance runner;tests/clients/link-child-binary-cache-fill.test.ts(see above);Handoffs, not in this PR:
remote_disconnect_failed;--forgetfor unbound cleanups of older Children;link_retirement_pending's advice on the revoke path without--operation-id.tombstone_limitsentences and fix(link): a revoke names its link (disconnect --expect-link), and no revoke removes a tombstone it did not write #8662'salias_linkedand bound text. After fix(link): a revoke names its link (disconnect --expect-link), and no revoke removes a tombstone it did not write #8662, thetombstone_write_failedrow and the comment above its CLI test become stale.Checklist
devsrc/have focused regression tests in their domain folders