Skip to content

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
lidge-jun merged 49 commits into
devfrom
fix/link-operation-cli-guidance
Nov 13, 2026
Merged

lidge-jun merged 49 commits into
devfrom
fix/link-operation-cli-guidance

Conversation

@lidge-jun

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

Copy link
Copy Markdown
Owner

Summary

Follow-ups from the final review of #8638 (the operation journal behind ocx link add and ocx link revoke with --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 linkRequest keeps 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.

  • A full journal. 409 operation_journal_full carries 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-ephemeral refusals say only that the apply changed no key, link or Child file, because a refused census still records its journal entry.
  • A revoke refused before it ran. Only operation_mismatch, link_operation_open and a revoke's operation_journal_full say nothing was changed.
  • Codes that may follow a resumed revoke.
    • link_operation_in_progress and tombstone_limit say only that this attempt did not touch the link, its key or the Child.
    • operation_journal_unreadable makes no state claim. It says what a later link_not_found means, because a replay after a resumed removal can meet it once that removal finished.
    • link_retirement_owned and link_retirement_mode_mismatch claim 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_failed adds a next step: fix the journal's disk and repeat the same id; try a new id only through link_retirement_owned's guidance.
    • link_changed says that the link, or the record of its unfinished removal, no longer matches what the removal started from. Read ocx link status, then repeat the same id. If it answers link_changed again, 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.
    • An unknown outcome 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. For unknown or residual, check the Child and resolve. For open, 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 --yes with --force), so it runs as printed, with one exception left for a follow-up: the operation_journal_unreadable text mentions ocx link revoke --force without --link-id and --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 own tombstone_limit message 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 answers link_changed to 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_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 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:

  • Within 2 hours: a repeat with the same operation id and the same parameters that reaches the journal within 2 hours of the answer gets the recorded outcome (status, code and outcome). A revoke whose own removal was interrupted resumes that removal first and answers that attempt.
  • Transient refusals: link_operation_in_progress after the lock wait changes nothing and is retried. After operation_journal_unreadable or a 5xx the caller repeats with the same id; neither proves that nothing changed.
  • After the window: the id may be treated as a new operation.
    • An enrollment whose link exists meets link_exists.
    • A revoke whose link is gone meets link_not_found.
    • An enrollment whose link was removed meanwhile enrolls the machine again, if it still answers with the pinned host key.

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 (journalledRevokeError in src/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.

Code Where it arises; what may already have changed The CLI prints
operation_mismatch Replay with another digest; this request changed nothing Nothing was changed; the first attempt's flags, or a new id
link_operation_open openRevokeConflict, only for an id with no entry; nothing Nothing was changed; repeat the unfinished revoke first
link_operation_in_progress Alias-lock wait or Child-job reservation, fresh or resumed; at most the receipt was re-owned This attempt did not touch the link, its key or the Child; retry
operation_journal_unreadable First read, openRevokeConflict or foreignRetirement: nothing; a replay after a resumed removal answered 200: the removal finished No state claim; keep a copy, move it aside, repeat with the same id; a later link_not_found means the link is gone
operation_journal_full openRevokeJournal, only for an id with no entry; nothing The bound's guidance; nothing was changed
operation_journal_failed Opening the entry: nothing. The first intent (before stopLink): 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 as link_present); for a resumed revoke an earlier attempt may already have stopped the tunnel or revoked the key. A later intent comes after stopLink: the tunnel is down, and for the key_revoked intent or the purge's remote_cleanup completion the Child cleanup has run; at the record_removed intent 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 receipt Generic; fix the journal's disk, repeat with the same id; a new id only through link_retirement_owned's guidance
tombstone_limit Fresh: settled failed_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 its stopLink, so it wrote no tombstone or intent and stopped nothing, but it may have taken back a receipt a plain --force disowned (reownLinkRetirement), and an entry already open settles unknown with this code (settleResumedRevoke) This attempt did not touch the link, its key or the Child; recover; repeat the same id; a new id if it persists while capacity is free; on link_retirement_owned, the revoke of the link that owns it in whatever recorded state, or a plain --force --yes
tombstone_write_failed The write's outcome is uncertain: recordTombstone can throw after its atomic write, before this revoke counts the tombstone as its own, so the file may remain Generic, no claim
link_retirement_owned foreignRetirement, before the entry is opened No state claim; the revoke of the link that owns it, in whatever recorded state (ocx link operations --json shows linkId), or a plain --force --yes; a plain revoke without --force only when no journalled operation owns it
link_retirement_mode_mismatch Unreachable with --operation-id at this head No state claim; the revoke that started it with its options, or a plain --force --yes
link_changed readRemovalTarget meets an outstanding receipt whose copy differs from the stored record (it was edited after the receipt was claimed, for example by ocx 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, answering link_changed again while the record differs from the receipt's copy (the stale receipt above) Generic; the link or its removal record no longer matches what the removal started from; read ocx link status, repeat with the same id; if that answers link_changed again, the link may have been edited after its removal began, and a new id removes it only when no unfinished removal of the link remains
link_not_found readRemovalTarget, before the entry No revoke was journalled; exit 4
Any other code Disconnect and purge failures, key_revoke_failed, link_remove_failed, alias-lock failures, operation_interrupted, revoke_failed Generic, with this id's closed outcome; for unknown, repeat the same id first (it resumes a removal only if this id still owns one); if it does not finish, read its state: unknown or residual, check the Child and resolve; open, fix what stopped it and repeat the same id

Compatibility and what stays unchanged

  • bound is 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 add and ocx link revoke with --operation-id. These changes reach callers without one:

    • the link_suspended text of ocx link reconnect and the dashboard's Retry;
    • the server's tombstone_limit message, which any client of the management API sees;
    • the add's --require-ephemeral refusal texts, which are printed whether or not --operation-id is passed.

    A revoke without --operation-id and 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:

  • CLI texts: each one's test in tests/cli/cli-link-operation.test.ts failed on the earlier wording, then passed. In this round that covers the link_changed text, the conditional unknown hint with its open-state branch, --link-id in the printed commands (all but the operation_journal_unreadable mention above), and the add-side and --require-ephemeral wording. The validated-link-id helper test guards the fix; it already passed before, because the old text printed a placeholder.
  • Server message: tests/server/link-recover.test.ts asserted the new tombstone_limit message, 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 no bound field.
  • Horizon: three tests with literal times failed against the 24-hour constant.
  • After the window: the post-window scenario revokes through the route, prunes for real and repeats the enrollment.
  • Receipt owner at the limit: tests/server/link-revoke-operation.test.ts pins a failed_clean receipt owner at the tombstone limit. It is refused, refused again while capacity is still full, a new id answers link_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 0
  • bun run privacy:scan → exit 0
  • bun run structure:check → exit 0
  • bun run skill:surface:check → exit 0; the generated reference reads "Declared capabilities: 51"
  • bun scripts/test.ts --parallel=2 over 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.
  • git merge-tree --write-tree origin/dev HEAD → exit 0 against dev 85fbba8.

Merges of dev, each with one conflict:

NOT RUN:

  • the full bun run test suite (this machine runs focused files only);
  • the Rust-dependent tests/clients/link-ocx-child-e2e.test.ts and the conformance runner;
  • a passing run of tests/clients/link-child-binary-cache-fill.test.ts (see above);
  • Windows and macOS.

Handoffs, not in this PR:

Checklist

  • Targets dev
  • Behaviour changes in src/ have focused regression tests in their domain folders
  • Owned structure doc updated in the same change
  • Inert by default (see above)
  • No GUI change

… 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.
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Caution

Review failed

The pull request is closed.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Share

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 13, 2026
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.
@lidge-jun lidge-jun changed the title fix(link): the CLI explains a full operation journal and an unfinished journalled revoke; clearer open-revoke wording and the journal's throughput limit fix(link): the CLI explains a full operation journal and an unfinished or refused journalled revoke; clearer open-revoke wording and the journal's throughput limit Nov 13, 2026
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.
@lidge-jun lidge-jun changed the title fix(link): the CLI explains a full operation journal and an unfinished or refused journalled revoke; clearer open-revoke wording and the journal's throughput limit fix(link): the CLI explains journal refusals and unfinished revokes; the operation journal keeps replays for 2 hours Nov 13, 2026
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.
@lidge-jun lidge-jun changed the title fix(link): the CLI explains journal refusals and unfinished revokes; the operation journal keeps replays for 2 hours fix(link): the CLI explains journal refusals and unfinished revokes from a truth table; the operation journal keeps replays for 2 hours Nov 13, 2026
@lidge-jun lidge-jun changed the title fix(link): the CLI explains journal refusals and unfinished revokes from a truth table; the operation journal keeps replays for 2 hours fix(link): the CLI explains journal refusals and unfinished revokes from a truth table; the operation journal keeps replays for at least 2 hours Nov 13, 2026
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 09:47
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 09:47
@lidge-jun
lidge-jun merged commit 41344a5 into dev Nov 13, 2026
32 checks passed
@lidge-jun
lidge-jun deleted the fix/link-operation-cli-guidance branch November 13, 2026 09:47
@chatgpt-codex-connector

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

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T09:49:46.903844Z c4701ec Draft marked ready
ℹ️ About Codex in GitHub

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

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

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

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.
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant