disk-hygiene: scan has no output-verbosity flag (~63,000 tokens of children_rollup in one run)

[kyle-sexton]

plugins/disk-hygiene v0.20.21. Split out of the audit umbrella. F7, medium.

Problem

No subcommand has an output-verbosity flag. Every scan emits its full children_rollup — one row per immediate child, with every field — regardless of what the caller needs.

A --max-depth 1 scan of a user home directory produced roughly 9,000 tokens of JSON (estimated from output size, not counted). The audited run performed seven such scans, so on the order of 63,000 tokens went into context to surface a frontier the caller then summarized in a paragraph.

The pipe rejection is correct — do not relax it

The obvious workaround is to trim at the call site, and the Bash guard rejects it: pipes, redirects, and shell operators all fail closed. That rejection is load-bearing and should be kept. Shell expansions are exactly the surface a deny-by-default lane exists to close, and an exception for | head is an exception for everything that can be spelled like | head.

So the fix belongs in the engine, not the guard.

Suggested fix

Add --quiet (or --summary) to scan, emitting the decision-relevant fields and omitting the per-child detail:

• status, target, entries, hinted_entries, unhinted_entries
• empty_directory_count
• target_logical_bytes, target_reclaimable_local_bytes
• truncated_paths
• errors, policy_sources, os_autoclean

The full children_rollup stays available by default and in the snapshot file on disk, which is where a caller that needs per-child detail should read it — the snapshot is written regardless, so emitting it to stdout as well is pure duplication for the common case.

Worth noting the same argument applies, less urgently, to handoff-verify, whose note block is re-emitted verbatim on every single-path call. On a 17-path run that note was printed 17 times.

Related

Umbrella: #3347. The per-path round-trip that multiplies this: the --path issue filed alongside this one.

🤖 Generated with Claude Code

[claude]

---

Generated by Claude Code

[claude]

This was generated by AI during triage.

Triage: verified → briefed (delegable)

Lane: autonomous triage, instance vm-triage-202609050304. Claimed via the tracker seam.

Verification

Filed against v0.20.21; current main ships v0.21.7. The defect survives the version gap.

Confirmed in plugins/disk-hygiene/skills/clean/scripts/hygiene.py:

• children_rollup is built at L867 and emitted into the scan payload at L1605, and again into the snapshot structures at L3525 and L3594.
• No --quiet, --summary, or any other output-verbosity flag exists on any subcommand. Searched the argparse surface for all three spellings; zero hits.
• The snapshot on disk already carries children_rollup (L3525, L3594), which confirms the issue's central point: emitting it to stdout as well is duplication for the common case, not the only copy.

The issue's own instruction to leave the pipe rejection alone is correct and is reinforced here: the Bash guard fails closed on pipes, redirects and shell operators by design, and this triage session was itself denied a read-only inspection command for naming the engine file. That lane is load-bearing. The fix belongs in the engine.

Classification

• Work class: work-class: scoped retained — additive output flag, no behavior change to scanning itself.
• Priority: priority: medium retained; matches the reporter's own severity. The ~63,000-token figure is the reporter's estimate from output size rather than a token count, and is treated as an order-of-magnitude signal, not a measurement.
• Exit: briefed → delegable. No open decision — the issue enumerates the exact field set to keep.

Brief (executable from this comment alone)

Goal. Give scan an output-verbosity flag so a caller that only needs the frontier does not pay for per-child detail it will not read.

Change. In hygiene.py, add --quiet to the scan subparser. When set, the emitted JSON carries the decision-relevant fields and omits children_rollup:

• status, target, entries, hinted_entries, unhinted_entries
• empty_directory_count
• target_logical_bytes, target_reclaimable_local_bytes
• truncated_paths
• errors, policy_sources, os_autoclean

Default output is unchanged — full children_rollup still emitted when --quiet is absent, so no existing caller changes behavior.

The snapshot must be unaffected. children_rollup continues to be written to the snapshot file on disk in every mode. --quiet is a stdout-shaping flag only. A caller that needs per-child detail reads the snapshot, which is where the issue argues it should have been reading all along. Assert this explicitly — a --quiet run whose snapshot lost the rollup would be a data-loss regression wearing a verbosity flag.

Guard interaction — do not miss this. destructive_guard.py validates engine invocations against an expected argument shape (_ALLOWED_ENGINE_SUBCOMMANDS at L308, canonical-invocation parsing around L866-L931). A new --quiet token on scan will be denied by the Bash guard until the accepted shape admits it. Update the guard in the same change and cover it by test, or the flag is unreachable from the lane that needs it most.

Second surface, same argument, lower urgency. The issue notes handoff-verify re-emits its note block verbatim on every single-path call — 17 times on a 17-path run. Fold that into this change if it is cheap (suppress the note under --quiet); if it is not cheap, leave it and say so in the PR rather than silently dropping it.

Acceptance criteria.

• scan --quiet emits exactly the listed fields and omits children_rollup.
• scan without --quiet is byte-identical to today's output.
• The snapshot file written to disk contains children_rollup in both modes — asserted by test.
• destructive_guard.py accepts the --quiet spelling on scan and still denies malformed variants; covered by test.
• No pipe, redirect, or shell-operator allowance is added anywhere. The guard's fail-closed posture on those is untouched.

Verification

scripts/run-ruff.sh check plugins/disk-hygiene; select suites with scripts/affected-tests.sh --run.

---

Raw marker cleared; agent-ready + status: ready applied. Lease released on completion of this triage.

---

Generated by Claude Code

[kyle-sexton]

Claimed by the autonomous worker lane.

• instance: vm-worker-202609050257
• lease expires: 2026-09-05T23:30:00Z (60 min TTL, renewed while active)
• scope: implement, test, independently review, open a close-linked draft PR. This lane does not merge.

Selected as the lead of the disk-hygiene group. #3352, #3351, #3349 and #3348 all converge on destructive_guard.py and hygiene.py, so they must be worked one at a time rather than in parallel; this one goes first because its brief is executable as written.

---

Generated by Claude Code

[kyle-sexton]

Handoff: PR #3783 is open, close-linked and review-ready. Lease released; the merge lane owns it from here.

--quiet is opt-in and the default is byte-identical to origin/main, independently verified at four frontier widths, with three tests pinning the default against a future flip. Compression runs 87-94% and per-child growth drops from 320 B to 17 B, so the saving holds at any frontier width.

One correction to this issue's premise: the ~63k tokens per run does not reproduce. Real measurement puts the audited seven-scan run at roughly 12,700 tokens on this host — the direction was right, the magnitude was about 5x over. Any sizing argument in the #3349/#3351/#3348 group that leans on 63k should be re-derived; detail on #3351.

---

Generated by Claude Code