disk-hygiene: preview exits 3 on Windows when the only blocker is execution-platform-unsupported, making the mandatory preview step a guaranteed failure

[kyle-sexton]

Drafted by an AI agent from an operator-confirmed interview (run 20260908-home-d1).

Parent

Parent: #4004. Refs #3347, whose F3 records the whole-lane platform gate this exit code is a symptom of.

Superseded if #4007 lands. An engine-native Windows Recycle Bin apply removes the blocker entirely, and this issue closes with it. Until then, Windows operators hit this on every run.

Problem

The skill makes preview a mandatory step before the manual handoff lane. On Windows that mandatory step always fails.

On this run, preview against plan-medium.json returned, for every candidate, exactly one blocker: execution-platform-unsupported. That blocker is a fact about the platform, not about any path. It is expected, it is documented, and it is identical for all five candidates. preview still exited 3.

A non-zero exit that occurs on every invocation on a platform carries no information. It is worse than no signal, because it trains the operator to ignore the exit code of the one command whose job is to say "do not proceed" — and to reach past it into the manual lane, which is exactly what the run did five times.

The verdict content was correct. Only the exit status was wrong.

Proposed fix

Distinguish a platform-capability blocker from a per-path blocker.

If the only blockers across all candidates are execution-platform-unsupported:

• exit 0, or a distinct reserved code that is not 3, and
• report the manual handoff lane as the outcome, since that is what the operator is being routed to.

Reserve exit 3 for a blocker that is about a path: a candidate that changed, a container that is not empty, a path that cannot be validated. Those are the cases where "do not proceed" means something.

If any per-path blocker is present alongside the platform blocker, exit 3 as today. The platform blocker must not mask a real one.

Design constraints

• No change to which paths are eligible, or to the blocker verdicts themselves. This is exit-status semantics only.
• The distinction must survive the mixed case: a run with one drifted path and a platform blocker still exits 3.
• If a distinct reserved code is chosen over 0, it must be documented alongside the existing exit codes.

Acceptance criteria

• preview whose only blockers are execution-platform-unsupported does not exit 3, and its output names the manual handoff lane as the outcome.
• preview with any per-path blocker still exits 3, including when a platform blocker is also present, demonstrated by a test over a mixed fixture.
• The exit-code table in the skill and engine docs reflects the new semantics.
• No blocker verdict content changes; a test shows the reported blockers are identical before and after.
• scripts/affected-tests.sh --run selects and passes the suites mapped to the changed files.

Out of scope

• Building the Windows apply lane, which is disk-hygiene: build an engine-native Windows Recycle Bin apply instead of model-composed deletion commands #4007 and supersedes this.
• The per-primitive platform gating question, which is disk-hygiene: re-gate execution blockers per primitive instead of excluding macOS as a whole lane #3857.
• handoff-verify's own exit-status defect, filed separately in this umbrella.

[kyle-sexton]

This was generated by AI during triage.

Decision defaulted: exit 0 for a platform-only blocker; status field carries the distinction (shares one exit-code-table edit with #4012, #4216) — veto before merge

[kyle-sexton]

This was generated by AI during triage.

Agent Brief

Type: Bug
Summary: preview's exit status does not distinguish a platform-capability blocker (present on every run on an unsupported platform) from a per-path blocker, so the mandatory preview step always fails on a platform where engine-native deletion isn't supported.

Current behavior:
preview sets its overall status to blocked (and its process exit code to a non-zero value) whenever any candidate carries any blocker, including execution-platform-unsupported — a blocker that is a fact about the platform, identical for every candidate on that platform, not about any candidate's path state. On an unsupported platform, preview therefore always exits non-zero, even when every path-specific check is otherwise clear.

Desired behavior:
Defaulted decision: when the only blocker present across all candidates is execution-platform-unsupported, preview exits 0 and its output names the manual handoff lane as the outcome; the status output field still records the distinction (a value other than ready-for-explicit-approval for this platform-only case) so a caller reading status rather than exit code still sees it. Maintainer-vetoable alternative: reserve a distinct non-zero exit code (other than the current blocked code) for the platform-only case instead of exit 0, documented alongside the existing exit codes. Whichever is chosen, a per-path blocker (drifted, changed-since-scan, unresolvable, or any other candidate-specific blocker) present on any candidate alongside the platform blocker still produces the current blocked exit behavior — the platform blocker must never mask a real one. No blocker verdict content changes.

Key interfaces:

• preview subcommand: exit-status decision distinguishes "only execution-platform-unsupported present across all candidates" from "any per-path blocker present"
• status output field: continues to carry the platform-only distinction even where the exit code no longer does
• Documented exit-code table for preview: updated to state the new semantics

Acceptance criteria:

• Running preview over a plan where every candidate's only blocker is execution-platform-unsupported exits 0 (per the defaulted decision), and the output names the manual handoff lane as the outcome.
• Running preview over a plan with a mix of one candidate blocked only by execution-platform-unsupported and another candidate carrying a per-path blocker (for example changed-since-scan) still exits with the current blocked exit code.
• A test shows the set of reported blockers per candidate is identical before and after this change; only the exit-status decision changes.
• The documented exit-code table for preview reflects the new semantics.

Out of scope:

• Building an engine-native deletion lane for the currently-unsupported platform (tracked separately; landing it would supersede this issue).
• The broader per-primitive platform-gating question (tracked separately).
• handoff-verify's own exit-status semantics for a gone verdict, and scan's root-children-selection-required/large-target-confirmation-required exit status — both tracked separately as sibling issues sharing this same exit-code-table documentation edit. Coordinate the shared documentation update across all three; do not fold their subcommand-specific logic into this issue.