feat(disk-hygiene): handoff-apply, a Linux route for an acknowledged checkout - #5541
Conversation
…te for an acknowledged checkout On Linux, an operator-acknowledged throwaway checkout had no in-engine deletion route: accept_unpublished exists only in handoff-verify, and preview and apply keep VCS protection categorical. handoff-apply takes --execute --snapshot --path --vcs-evidence --report --data-root. It refuses off Linux through execution_blockers(), then runs validate_handoff_paths, validate_vcs_evidence and handoff_verify in-process for exactly that one path, and deletes only on a clear verdict. No verdict is read from a file. preview() and apply_plan are unchanged, and the acknowledgement is evaluated only inside handoff_verify; the report copies the verdict's accept_unpublished entries so the ack shows in the result. After the verdict, every non-VCS check apply_plan runs is repeated per entry: target fd identity, fresh mounts, hard_protection with baseline and snapshot names, consumer globs, same_removal_identity, is_linkish, handle state, and the O_NOFOLLOW fd-relative removal. Only vcs-tracked-content is satisfied by the verdict, and only when it verified the repository evidence. Two additions beyond apply_plan's loop were required, because its anchored removal cannot delete a git checkout: the snapshot records .git without descendants, so the removal refuses it as not empty, and tracked_blocker cannot answer for a path inside .git. The route relaxes the .git marker protections through evidence_adjusted_protections, as handoff-verify does, and empties each verified repository's .git fd-relative (links unlinked, never followed; a mount point or consumer glob match inside it blocks the purge) before the existing anchored rmdir. The route has no plan, so no owner: the native-managed-report-only check has nothing to read here. handoff-apply is a new grammar subcommand rather than a second form of apply, so the apply token shape and its guard admission are unchanged. The guard denies the new name until it is wired. Refs #5178 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…y removes anything handoff-apply deletes a directory's entries deepest first, so the working tree went before .git. The mount, consumer-glob and unreadable-directory checks on the uninventoried contents of .git ran only when .git itself was reached, which left a gutted checkout with .git intact. Run those checks for every verified repository's .git before the first removal, and keep the per-entry recheck as the race defense. A directory the walk cannot read now blocks as needs-elevation or filesystem-state-unverified instead of being skipped. The relaxed .git marker protections apply only when the verdict verified the repository evidence. Refs #5178 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
handoff-apply was declared in the grammar, so the classifier recognized it, but _decide had no branch for it and denied it as not an exact engine command. The guard now sorts every admitted subcommand into a hand-placed read-only or mutating set. A mutating subcommand gets the hook-issued ask when execution is enabled and a kill-switch denial, under its own rule, when it is not. The exact handoff-apply shape asks with a prompt naming the one approved path and the acknowledged loss of unpushed commits and untracked or ignored files. The kill-switch denial text lists the read-only subcommands in grammar order instead of a hand-written list. A newly declared subcommand stays denied until it is placed in one set; a test fails until every grammar subcommand is in exactly one. Tests cover the ask, each malformed variant (missing --vcs-evidence, --plan or --approval-token beside --path, repeated --path, a flag-shaped value, missing or unauthorized --data-root, missing --execute), the kill switch, the recorded rules, and unchanged apply, preview and handoff-verify verdicts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e 0.29.0 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Release handoff-apply as 0.30.0 above main's 0.29.0 and use consumer_protection_matches where main removed consumer_path_protected. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… does handoff-apply is not a read-only evidence mode and not acknowledgement-only: it deletes on any clear handoff-verify verdict, asks in the guard alongside apply, and is the one lane that empties Git metadata contents the snapshot never inventoried. - README: the VCS exception, the guard's two ask shapes, the snapshot-only traversal claim and the standalone-checkout pointer now name handoff-apply. - safety-model: state the purge and the checks that bound it (mount, consumer glob over a live walk, unreadable directory, per-directory device, links unlinked not followed), that the hard-protection name check is not applied to those contents, and drop the stale shape count and apply-only prompt claim. - SKILL.md: section 6 says any clear verdict deletes; restore the unsupported-platform and Gotchas wording the route had compressed. - CHANGELOG: describe the purge and the any-clear-verdict semantics. - opaque_contents_blocker docstring lists what it checks; add a test that a fully verified checkout is deleted without an acknowledgement. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Codex Review SummaryThis 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. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0adbddee53
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 4m 42s —— View job Security review complete
No security issues found. This PR adds
Things specifically checked and found sound:
GitHub Actions hardening (workflow triggers/permissions/pinning) is out of scope for this lane and this PR doesn't touch |
|
Claude finished @kyle-sexton's task in 6m 9s —— View job Code review complete
No blocking findings. I read through the new Specific things I checked and ruled out as bugs:
Test coverage ( Docs (README, SKILL.md, safety-model.md, unsupported-platform-handoff.md, fan-out-worker-brief.md, CHANGELOG) accurately describe the new Linux route, the purge's bounds, and continue to state the loss warning; I didn't find drift between the prose and the implementation. |
…t metadata The pre-purge scan cannot see an entry created after it ran. The purge now matches every child against the consumer protection globs as it reaches it and refuses the removal on a match. Refs #5178 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 5m 8s —— View job Security review complete
No security issues found. This PR adds
Note: this HEAD already includes the fix for the one
Other things specifically checked and found sound:
GitHub Actions hardening is out of scope for this lane; this PR doesn't touch |
Code review in progress
|
…t-unpublished-route Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 28s —— View job Security review complete
No security issues found. I diffed Only two files under
No instruction-surface deletions: this PR's own changed-file set (11 files) contains no GitHub Actions hardening is out of scope for this lane; this PR doesn't touch |
|
Claude finished @kyle-sexton's task in 3m 50s —— View job Code review complete
No blocking findings. This is the CODE-REVIEW lane (security is scoped out here since a dedicated security lane already ran three completed passes on this branch, the most recent at I diffed
Specifically checked and found sound, not just the security properties already covered:
I did not independently run |
…t-unpublished-route Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 48s —— View job Security review complete
No security issues found. This lane has already run four completed security passes on this branch ( I diffed that last-reviewed head against the current head to scope this pass to what's actually new: Only three files differ, all documentation/changelog, and none of them are code:
None of this narrows or removes a guardrail: the prose still states the belt is session-long and does not reach subagents, now with a more precise citation. No instruction-surface deletions: this update only reinforces existing hook-lifetime/subagent-reach documentation with better evidence; it removes no guardrail language from GitHub Actions hardening is out of scope for this lane; this PR doesn't touch |
|
Claude finished @kyle-sexton's task in 1m 18s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I diffed the previously-reviewed head ( Only three files differ, and all three changes come from an unrelated PR (
None of this touches No new findings for this PR's actual scope. The only content since the last full review is doc prose belonging to a different, already-merged PR that arrived here as a side effect of merging I did not independently run |
…t-unpublished-route Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 2m 8s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies.
and cross-checked it against this PR's actual diff vs
So the actual No new findings for this PR's actual scope. I did not independently run |
|
Claude finished @kyle-sexton's task in 1m 52s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. Five security passes already ran on this branch ( I confirmed the current head (
No instruction-surface deletions: this PR's changed-file set contains no No new security findings for this PR's scope. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
…y model SKILL.md sat at the 500-line hard cap after the merge with main. The Linux command block moves next to the standalone checkout evidence it consumes, and the skill bullet links to it. Refs #5178 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 50s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies.
Five files changed, none of them the logic this lane already reviewed in full:
I confirmed the move is self-consistent:
No new findings for this PR's scope. I did not independently run |
|
Claude finished @kyle-sexton's task in 44s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. Six security passes have already run on this branch, the most recent full one at
No new security findings for this PR's scope. No instruction-surface deletions. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
Renumber to disk-hygiene 0.33.0 above main's 0.32.0 and carry main's catalog subcommand through the guard's read-only set and the docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 46s —— View job Security review complete
No security issues found. Seven security passes have already run on this branch. The most recent full one, at I confirmed this PR's actual scope against Fifteen files differ, but every one of them is unrelated content pulled in from
No instruction-surface deletions: No new security findings. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
|
Claude finished @kyle-sexton's task in 1m 54s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies.
still shows the same 11 files as the PR's stated diff (+1068/-64), and I diffed the previously fully-reviewed head (
No new findings for this PR's scope. The one prior finding on this thread (Codex |
Keep disk-hygiene 0.34.0 above main's 0.33.1 with this PR's entry on top. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 57s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. This PR's actual scope against I diffed the previously fully-reviewed head ( Three files differ, and none touch
No instruction-surface deletions: No new security findings. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
|
PR body contract — issue linkage This PR body conforms to the issue-linkage contract. Nothing to do. |
|
Claude finished @kyle-sexton's task in 1m 15s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I confirmed this PR's actual contribution against
Only three files differ:
No instruction-surface deletions: No new findings for this PR's scope. I did not independently run |
Bump disk-hygiene to 0.35.0 above main's 0.34.0. The mutation prompt table maps each mutating subcommand to a reason function so apply keeps main's plan-listing reason and handoff-apply keeps its own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 23s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. This PR's actual scope against I diffed the previously fully-reviewed head ( Eight files differ. All of it is content merged in from
No instruction-surface deletions: No new security findings. This is the eleventh security pass on this branch; the most recent full ones ( GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
|
Claude finished @kyle-sexton's task in 1m 10s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I confirmed this PR's actual contribution against
Eight files differ, and every change belongs to that merged-in, already-landed PR, not to this branch's own
No new findings for this PR's scope. I did not independently run |
Keep disk-hygiene 0.35.0 above main's 0.34.1 with this PR's entry on top. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 36s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I confirmed this PR's actual contribution against
Only two files differ, and both are unrelated content pulled in from
No instruction-surface deletions: No new findings for this PR's scope. I did not independently run |
|
Claude finished @kyle-sexton's task in 37s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. This PR's actual scope against I diffed the previously fully-reviewed head ( Only two files differ, both pure documentation, and both come from an unrelated, already-merged PR (
This is a guardrail addition, not a deletion or softening — it closes a gap where a container-wide empty-after-recycle could have silently defeated reversibility, and it doesn't touch this PR's own
No instruction-surface deletions: No new security findings. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
Keep disk-hygiene 0.35.0 above main's 0.34.2 with this PR's entry on top. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 39s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. This PR's actual scope against
Four files differ, and every change is content merged in from
No instruction-surface deletions: No new security findings. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
|
Claude finished @kyle-sexton's task in 2m 22s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I confirmed this PR's actual contribution against
Four files differ, and every change is unrelated content pulled in from
None of this touches That head, and the ones before it, received thirteen prior review passes on this thread (code-review and security-review alternating) that already covered the No instruction-surface deletions: No new findings for this PR's scope. I did not independently run |
Keep disk-hygiene 0.35.0 above main's 0.34.3 with this PR's entry on top. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 57s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I confirmed this PR's actual contribution against
Only three files differ, and every change is unrelated content pulled in from
No instruction-surface deletions: No new findings for this PR's scope. I did not independently run |
|
Claude finished @kyle-sexton's task in 40s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. This PR's actual scope against I diffed the previously fully-reviewed head ( Only three files differ, all pure documentation (fixing #5520, "SKILL.md and fan-out-worker-brief.md docs match the engine"), pulled in from
No instruction-surface deletions: No new security findings. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 22s —— View job Code review complete
Skip gate: this head already has a successful review from this lane that still applies. I confirmed this PR's actual contribution against
Eight files differ, and every change belongs to an unrelated, already-merged fix (
No instruction-surface deletions: No new findings for this PR's scope. The I did not independently run |
|
Claude finished @kyle-sexton's task in 59s —— View job Security review complete
Skip gate: this head already has a successful security review that still applies. This PR's actual scope against I diffed the previously fully-reviewed head ( Eight files differ, and every change is content merged in from
No instruction-surface deletions: No new security findings. GitHub Actions hardening is out of scope for this lane; this PR doesn't touch I did not independently run |
Main took disk-hygiene 0.35.0 (handoff-apply, #5541), so the inventory release moves to 0.36.0 above it. The destructive guard's read-only set now lives in main's frozenset beside the mutating set, and inventory joins the read-only side; the tests that named the old tuple or pinned apply as the last subcommand follow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main's handoff_apply (#5541) also reaches anchored_remove, and its purge_directory_contents and write_text_atomic delete too, so the guard's apply-lane set and the one-caller assertions no longer described the engine. Deleting is now allowed only in apply_plan, handoff_apply, anchored_remove, purge_directory_contents and write_text_atomic (its own temporary file). A registry command or tool may appear only in apply_plan: handoff_apply takes no plan, so it has no owner claim, and the test pins that signature. Each lane has main as its only caller, anchored_remove has exactly those two, and only the handoff lane asks it to empty Git metadata. The engine is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…engine-gate denial (#5582) Refs #5519 ## Summary The Bash engine-gate denial in `destructive_guard.py` gave no hint which token failed the exact-engine grammar, what the flag-order rule is, or which mention forms are gated. The denial now says all three. No behavior change: the guard matches and denies exactly the same commands. This PR uses `Refs`, not `Closes`; whether it closes #5519 is left to the owner. ## Fix - `_engine_mismatch_reason` names what the classifier refuses (parse, word count, interpreter, engine script, subcommand, `--data-root`, per-subcommand grammar via `engine_grammar.explain_mismatch`). It runs only on the deny path. - An engine operand of a command that is not the hook's Python (`grep foo "<engine path>"`, `cat "<engine path>"`) is named first, as an absolute engine path or as a relative word that resolves to the engine from the current directory. Before, the reason blamed the command word (`grep`) as "not this hook's Python". - A word the gate reads as an engine call (a quoted payload holding an interpreter and the engine filename, such as `gh issue list --search "python3 <engine>"`) is named as the gated word. Before, the reason named `gh` and asked for the hook's Python. The gate and the reason share one helper, `_reads_as_engine_payload`, so they cannot disagree on which word gated. - An unparsable command names the first operator class present (pipe, redirect, `;`, `&`, substitution, glob, newline, `!`/`#`, backslash, quote) instead of listing all of them. A test pins the label table to the characters the literal parser rejects. - `_engine_flag_order_rule` states the flag-order rule from the declared subcommand specs, and `_ENGINE_GATE_SCOPE` states the gated mention forms and the read-only forms in the owner's words, with the condition the owner chose (option 2, PR comment 2026-09-30T19:04Z): a relative path or bare name that resolves to the installed engine from the current directory is still gated. - Relaxing the guard (option a) is deferred by the owner's decision to a separate, security-reviewed change. - `disk-hygiene` 0.41.1 with a CHANGELOG entry above 0.41.0. No doc quotes the old denial text. ## Owner decision applied The Codex P2 thread found that the advertised read-only forms are denied when the word resolves to the installed engine (the literal branch of `_engine_gate_relevant` gates on file identity). The owner took option 2: keep the forms and add the condition. `test_engine_gate_gates_a_relative_word_that_resolves_to_the_engine` pins both the gated shapes and that their denial states the condition. `_engine_gate_relevant` result per working directory: | Working directory | Command | Gated | |---|---|---| | plugin root or repo root | `grep foo <relative path to the engine>` | yes | | plugin root or repo root | `git grep foo -- <relative path to the engine>` | yes | | repo root | `rg foo <bare engine name>` | no | | the engine's directory | `rg foo <bare engine name>` | yes | | the engine's directory | `git grep foo -- <bare engine name>` | yes | | any directory tried | `git show <rev>:<path to the engine>` | no | | an unrelated directory | `grep foo <relative path to the engine>` | no | ## Verification - `test_hygiene` (run as CI does, from the scripts directory): 674 tests OK (1 skipped) on the merged head, including tests for the denial text, agreement between the explainer and the classifier over every declared subcommand (`handoff-apply` included), the advertised read-only forms and their resolving-word condition, the engine operand reason, the payload-word reason, and the operator reason. The payload-word test also asserts `_engine_gate_relevant` still gates those commands and still defers a plain mention. - The rest of the disk-hygiene Python suites (scripts, lib, setup): OK. - `scripts/run-ruff.sh check` on the changed files: all checks passed. - `scripts/check-changelog-parity.sh --check`, `--check-order`, and `scripts/validate-plugins.sh`: pass. ## Related - Message-only precedent: #3348. - #5214 is the parent issue. #4218 and #3527 are the same-fault items for the deferred relaxation. - Version: 0.41.1, above main's 0.41.0. This branch merged main, which carries #5541 (`handoff-apply`), #5526, #5590 and #5628 for disk-hygiene. The final deny in `_decide` is now main's single `not-exact-engine-command` call with `command=command` added, and the explainer reads the declared subcommand specs, so it covers `handoff-apply`'s required flags. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 participant
Closes #5178
Summary
On Linux an operator-acknowledged throwaway checkout had no deletion route inside the engine:
handoff-verifyran only on Windows and macOS, andapplykeeps VCS protection categorical. This addshandoff-apply, a Linux-only engine route for one exact approved path. The acknowledgement (accept_unpublishedinvcs-evidence.json) is evaluated only in the handoff verification path; preview and tokenapplystay categorical, as the owner decided on the issue.Fix
hygiene.py: newhandoff-applysubcommand (--execute --snapshot --path --vcs-evidence --report --data-root). It refuses off Linux, runshandoff_verifyin-process for the one path, deletes only on aclearverdict, repeats the non-VCS checks per entry, and waives onlyvcs-tracked-content. The verdict reportsaccept_unpublished..gitwithout its descendants, sohandoff-applyis the one lane that removes entries outside the snapshot: it empties the repository metadata fd-relative, refusing on a mount point, a consumer protection glob match (re-checked per child as the purge reaches it), an unreadable directory or a device change, and unlinking links rather than following them.destructive_guard.py: the exacthandoff-applyshape asks when the plugin is enabled (exact-engine-handoff-apply); the kill switch denies it (kill-switch-disabled-handoff-apply).safety-model.md,unsupported-platform-handoff.md, the fan-out worker brief and the README name the Linux route and keep the loss warning (unpushed commits and untracked or ignored files are lost).Verification
bash plugins/disk-hygiene/skills/clean/scripts/hygiene.test.sh(fromskills/clean/scripts): 624 tests OK on the merged tree, covering the Linux route, an unacknowledged repository staying contested, the per-child protection recheck and the guard shapes.check-changelog-parity.shwith--check,--check-order,--check-bump origin/mainand--check-preserved origin/main, andvalidate-plugins.sh: pass.Related
handoff-verifyto engineapplyroute that re-checks gates 3+, acknowledgement only in handoff-verify, preview and apply categorical.🤖 Generated with Claude Code