disk-hygiene: POSIX has no support lane (Bash denies all non-engine) and macOS manual-handoff has no deletion lane

[kyle-sexton]

Summary

On Linux/macOS the disk-hygiene guard leaves the model with no shell lane for the evidence
gathering the skill itself requires, and on macOS the documented manual deletion handoff has no
lane to execute through.

E1 — Bash lane denies ALL non-engine commands; POSIX has no read-only support lane

• destructive_guard.py:302,324-329 denies any Bash command that is not an exact scan/preview/apply
  shape.
• SKILL.md step 2 requires establishing ownership/liveness ("Is the owner active?") and provenance
  — which on POSIX means ps, lsof, git log, stat, etc.
• The "read-only support" escape (SKILL.md:222-225) is the PowerShell lane, which only exists
  where a PowerShell tool is present (effectively Windows).

Net: on Linux/macOS the only support tools are Read/Grep/Glob; the model cannot run process/liveness
or VCS-provenance checks, so its tier classification is materially weaker on the platform where the
engine actually deletes.

This session hit the Windows-analog symptom: once the skill's hook was active, every non-engine
Bash command in the session was denied — routine ls/find for inspection included — forcing a
switch to PowerShell. On a host without PowerShell there is no fallback at all.

Fix: add a read-only allowlist lane for POSIX support commands (ps, lsof, stat, git,
file, …), mirroring the PowerShell read-only lane's intent.

B3 — macOS manual handoff is documented but impossible to perform

• SKILL.md:177-195 describes a Windows/macOS post-approval manual handoff (Recycle Bin / Trash).
• On macOS there is no PowerShell tool, and the Bash guard denies every non-engine command
  (rm, trash, osascript, mv) via _bash_denial_guidance (destructive_guard.py:302,324-329).

So after a human approves an exact list on macOS, there is literally no lane to delete through — the
documented handoff is dead. (Windows has the PowerShell lane; Linux has the engine.)

Fix: provide a macOS deletion lane (a scoped allowlist for the approved handoff), or scope the
manual-handoff doc to Windows only.

Severity

MEDIUM. Together these make the skill much weaker on POSIX than its docs imply.

[kyle-sexton]

This was generated by AI (decide lane — decision-brief pass; surfaced via coverage sweep — this decision was unlabeled).

Decision brief: macOS deletion handoff has no lane — build one, or scope the doc?

Problem. disk-hygiene documents a post-approval manual deletion handoff for macOS (Recycle Bin / Trash), but on macOS there is no lane to execute it through: the engine is disabled on that platform, there is no PowerShell tool, and the Bash guard denies every non-engine command. The team must decide whether to make macOS a real deletion platform (build a scoped lane) or make the docs honest (scope the handoff to Windows).

Scope note: this fork decides B3 (the dead macOS deletion handoff) only. The issue's E1 (POSIX has no read-only support lane for ps/lsof/git/stat liveness/provenance) is a separate remediation in the same issue — a read-only POSIX allowlist — and is unaffected by whichever B3 option is chosen. (The issue's cited line numbers have drifted; current main line numbers are shown below.)

Today (verified against main)

• Engine is disabled on macOS. Preview returns execution-platform-unsupported on Windows and macOS; the engine never deletes there — SKILL.md:151, SKILL.md:179.
• The documented macOS handoff exists in the doc. SKILL.md:177-200 ("Unsupported-platform handoff (Windows, macOS)") describes a manual Trash/Recycle Bin removal after an exact-list AskUserQuestion approval.
• Its only executing lane is PowerShell. SKILL.md:193-195: "The PowerShell guard lane turns deletion spellings into a final human permission prompt … Engine invocations from PowerShell stay hard-denied." In the guard, powershell_decision (destructive_guard.py:265-296) returns ask for a deletion spelling — the handoff lane. The guard only branches on tool_name == "PowerShell" (destructive_guard.py:336).
• On macOS that lane does not exist. No PowerShell tool on macOS. Everything else falls through to the Bash lane, which denies any command not classified scan/preview/apply — destructive_guard.py:343,365-370, guidance at _bash_denial_guidance destructive_guard.py:299-315 ("Use non-Bash read-only tools for supporting inspection").

Net: after a human approves an exact list on macOS, there is literally no lane to delete through. Windows has the PowerShell lane; Linux has the engine; macOS has neither. The documented handoff is dead on macOS.

Options

Option A — Scope the manual-handoff doc to Windows-only + defer the macOS lane behind a trigger. [RECOMMENDED]
Reword SKILL.md:177-200 so the handoff explicitly covers Windows only, and state macOS is out-of-lane (report-only; no deletion). File a deferred item to build a real macOS lane, triggered by demonstrated macOS demand and resolution of the guard-determinism blockers below.

• Rationale (grounded in what's verified, not demand I can't measure): A new macOS deletion lane would be built on a guard whose determinism is already broken on that surface — disk-hygiene: guard hook launches via bare python — fails to run (fail-open risk) on python3-only hosts #380 (guard may fail-open on python3-only hosts, common on macOS) and disk-hygiene: apply/handoff ask gate and unattended-stop are advisory, not deterministic — apply can run with no human #381 (the apply/handoff ask gate is advisory, not deterministic — the very prompt the handoff relies on). Adding a deletion path there compounds unresolved security defects. Doc-scoping is cheap, honest, and regresses nothing: the macOS engine is already disabled, so no capability is lost — only a false promise is removed. macOS demand is currently unknown (no signal either way), which argues for a trigger, not for building speculative deletion surface now.
• Tradeoffs: macOS users get report-only (must delete by hand outside the skill). Removes a documented capability that never actually worked.
• Reversibility: Trivially reversible — a doc edit; Option B can supersede it later with no lock-in.

Option B — Build a scoped macOS deletion lane (real macOS support).
Add a macOS read-only-plus-approved-deletion allowlist (e.g. an osascript/trash/mv-to-Trash lane) mirroring the PowerShell ask lane's intent, gated on the same exact-list approval.

• Tradeoffs: Real, non-trivial scope: new allowlist surface + tests + platform matrix, on top of the engine's own macOS support gaps. New attack surface (every added spelling is a bypass risk the Bash lane deliberately avoids by denying unknowns — SKILL.md:218-221). Should not land before disk-hygiene: guard hook launches via bare python — fails to run (fail-open risk) on python3-only hosts #380/disk-hygiene: apply/handoff ask gate and unattended-stop are advisory, not deterministic — apply can run with no human #381 are fixed, or it inherits fail-open + advisory-gate on a platform that can now delete.
• Reversibility: Hard to reverse — once shipped, users depend on it; new surface carries ongoing maintenance and security-review cost.

Option C — Defer both (status quo, no doc change).
Leave the doc as-is and track later.

• Tradeoffs: Cheapest now, but the doc keeps promising a macOS handoff that cannot execute — the honesty defect persists. Strictly worse than A, which fixes the false promise for the same near-zero cost.
• Reversibility: Fully reversible.

Cross-links

• disk-hygiene: guard hook launches via bare python — fails to run (fail-open risk) on python3-only hosts #380 (guard fails-open via bare python on python3-only hosts) and disk-hygiene: apply/handoff ask gate and unattended-stop are advisory, not deterministic — apply can run with no human #381 (apply/handoff ask gate advisory, not deterministic) — both area: security, priority: high. These are the verified blockers that make building Option B now unsafe on macOS specifically.
• disk-hygiene: disk_hygiene_enabled kill switch does not gate the PowerShell lane and is inert under the env-injection failure #382 (kill switch does not gate the PowerShell lane) — same handoff/ask-lane surface; relevant if a macOS lane is later modeled on the PowerShell lane.
• E1 (same issue) — the POSIX read-only support lane gap; distinct remediation, still open regardless of this fork's outcome.

Routing recommendation (triage lane): apply status: needs-decision — this fork is currently unlabeled for the decision queue.

[kyle-sexton]

The Windows half of B3 is real and was hit end to end in a live /disk-hygiene:clean run. Adding it here rather than opening a separate issue, since it is the same defect on the other platform. Also confirming E1 independently.

B3 on Windows: the mandate has no implementation, and the consumer ends up writing the delete primitive

SKILL.md:271 instructs "Prefer reversible removal (Windows Recycle Bin / macOS Trash) over permanent deletion, and say which was used." Nothing in the plugin implements it on Windows either.

Verified in-session:

• PowerShell 7 has no reversible-delete cmdlet. Remove-Item unlinks permanently.
• Add-Type -AssemblyName Microsoft.VisualBasic succeeds, but [Type]::GetType('Microsoft.VisualBasic.FileIO.FileSystem') returns null — FileIO is not in .NET Core.

And this is the only lane that exists here: execution_blockers() returns execution-platform-unsupported off Linux (hygiene.py:1192-1195), so on Windows and macOS the manual handoff is the sole deletion path. The plugin's stated preference is therefore unachievable-by-default on both platforms where it is the only option.

What actually happened as a result, and this is the part worth fixing:

• Honouring the mandate required hand-writing a SHFileOperation P/Invoke wrapper with the allow-undo flag. Every consumer improvises the single highest-risk primitive in the workflow, unreviewed.
• That improvised helper now lives inside the plugin's own state, at runs/<run-id>/recycle-one.ps1 under the plugin data root. Consumer-authored deletion code is accumulating in plugin-managed state with no provenance marker.
• The PowerShell belt never fired on it, correctly per its own design: _POWERSHELL_MUTATION_WORDS (destructive_guard.py:850-855) enumerates spellings, and recycle-one.ps1 -Path <x> matches none. The belt is blind to the one deletion command the workflow actually used.
• Step 2's reversibility caveats — bin size caps, policy-disabled bin, non-NTFS or network volume — are stated as things to disclose, but nothing shipped can observe them, so the disclosure is guesswork. (In this run they were checked by hand: NTFS, NukeOnDelete=0 on all volumes, ~192 GB cap, no NoRecycleFiles policy.)
• The section 6 summary contract compounds it: a recycled byte still occupies the volume, so "logical bytes removed" plus an unchanged free-space delta reads as the documented "concurrent activity" caveat rather than as "nothing was actually reclaimed yet." Observed here: 1,963,095 bytes removed, free space rose 7.8 GB.

Suggested fix

Ship the primitive. A bundled recycle.py or recycle.ps1, invoked per verified path, added to the guard's allowed exact shapes, using SHFileOperation or IFileOperation with the allow-undo flag on Windows and NSFileManager trashItemAtURL: on macOS, returning a machine-readable outcome that distinguishes recycled from permanent and names the reason.

That converts a prose mandate into a mechanism, makes the belt's flagged set authoritative over one known command instead of blind to an improvised one, and gives the section 6 summary a real value to report. It is also a far smaller surface than the Windows engine apply lane this repo deliberately declined to ship, so it does not reopen that decision.

Cheapest interim if that is too much: downgrade the mandate to conditional — "if your platform provides one" — and name the exact per-platform command, so the skill stops requiring what it cannot supply.

E1 confirmed independently, and it resolved an open question for us

E1 says that once the skill's hook was active, every non-engine Bash command in the session was denied, routine ls/find included.

Confirmed. A parallel audit could not verify skill-hook lifetime from any official source — the hooks page says component hooks are "scoped to the component's lifetime and cleaned up when it finishes" but never defines a skill's lifetime — and had to mark the deny-by-default belt's lockout risk as unproven. E1 is the empirical answer, so that assumption is now settled by this issue rather than still open.

One further live instance, in the same class but from the always-on plugin-level gate rather than the belt: read-only sed, wc, and Test-Path were denied from both Bash and PowerShell for any command whose text merely mentions hygiene.py. It is disclosed in the denial text ("use non-shell file tools"), so not a new defect — but it meant an audit's own source line-number verification could not be done through a shell at all, and it is a second instance of the "marker-free fallback taxes unrelated work" concern the guard's own docstring raises.

Both point the same way as E1's proposed fix: a read-only allowlist lane is the missing piece, and the deny-unknown posture is what creates the lockout rather than the engine's own containment, which is the stated authority anyway.

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as not planned for this drain wave.

Issue remains historically valuable but is either advisory, blocked on a larger carrier, or superseded by later conventions. Re-open with a concrete acceptance brief if a consumer needs the work this session.

Title: disk-hygiene: POSIX has no support lane (Bash denies all non-engine) and macOS manual-handoff has no deletion lane