disk-hygiene: add scan --sizes-only and ship the fan-out worker brief

[kyle-sexton]

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

Parent

Parent: #4004. Refs #3352 (closed), which added --quiet after ~63,000 tokens of children_rollup in one run, and #2851 (closed), which restored a per-immediate-child roll-up. Both made the existing inventory cheaper to read. Neither gave the engine a way to answer "how big is this subtree" without paying for an inventory, which is the gap here.

Problem: the engine could not size its own target

The run's largest numbers did not come from the engine.

Every managed-state size in the audit report — Docker 103.1 GB, NVIDIA 32.2 GB, Cursor 20.8 GB, Microsoft 7.6 GB, Temp 7.0 GB — came from a read-only PowerShell recursion run outside the engine. The engine's own AppData subtrees returned descendant-not-walked at depth 2.

The report has to carry a standing caveat as a result: engine target_reclaimable_local_bytes for .aspire, Saved Games, claude-lane-sandbox, .cache\huggingface, .bun\install and all of AppData are floors, because of depth cuts. Where a real number is quoted, the measurement is authoritative and the engine's figure is not.

The scale: the depth-1 frontier held 81 entries, of which 48 subtrees truncated at depth 1 and were fanned out below. The engine's only lever for going deeper is more depth, which means more inventory, which means more entries, more cap pressure, and more tokens — to obtain one number per subtree.

What to build

1. scan --sizes-only

A full walk that returns an exact children_rollup in one pass, with:

• no per-entry inventory — nothing is described, only summed,
• no entry cap — the cap exists to bound inventory output, and there is no inventory to bound,
• exact totals, not floors, so the size_qualifiers caveat does not apply to its output.

This is the cheap answer to "how big is this", which is a different question from "what is in here" and currently cannot be asked separately.

2. Ship the fan-out worker brief

Three subagents were fanned out on this run, at roughly 550k subagent tokens. Operator observation from the run: the Bash contract had to be re-explained to each worker, because the plugin ships nothing a worker can be pointed at.

Ship the brief as a skill reference file, covering:

• the Bash contract — the exact guarded command shapes the belt permits, and what it denies,
• the scan invocation template — the flags a size or inventory worker should use, including --sizes-only once it exists,
• the evidence-only rules — a worker reports what the snapshot says and does not dispose, rank, or recommend.

A worker brief is not documentation for humans; it is the thing pasted into a spawn prompt. It should read as one.

Design constraints

• --sizes-only adds no new collection beyond the walk itself. It reads sizes, not metadata it would then discard.
• Its output must be distinguishable from a capped or truncated inventory's roll-up, so a consumer cannot mistake a floor for an exact total or the reverse.
• The worker brief is a reference file, not a second skill body. It restates nothing the skill already says beyond what a worker with no other context needs.
• The brief's Bash contract must stay accurate to the belt. If the belt changes, the brief is part of the change.

Acceptance criteria

• scan --sizes-only performs a full walk with no per-entry inventory and no entry cap, and returns an exact children_rollup in one pass.
• Its output is marked exact and is distinguishable from a depth-cut roll-up, demonstrated by a test over a truncating fixture.
• Running --sizes-only over a fixture that would exceed the inventory cap succeeds without truncation.
• A fan-out worker brief ships as a skill reference file and contains the Bash contract, the scan invocation template, and the evidence-only rules.
• The brief is referenced from the skill body at the point where fan-out is described, so a session composing a spawn prompt finds it.
• scripts/affected-tests.sh --run selects and passes the suites mapped to the changed files.

Out of scope

• Changing the default scan's cap or depth behavior.
• Anything that makes --sizes-only output eligible for a disposition. It sizes; it does not judge.
• Free-space or proportionality use of the resulting numbers, which belongs to disk-hygiene: decide whether the cleaner may distinguish a tidiness pass from a disk-full emergency #3855.

[kyle-sexton]

This was generated by AI during triage.

Agent Brief

Type: Feature
Summary: Add a scan --sizes-only mode that returns an exact size rollup in one full walk with no per-entry inventory and no entry cap, and ship a fan-out worker brief as a skill reference file.

Current behavior:
scan always produces a per-entry inventory bounded by an entry-count cap, and, when depth-limited, a children_rollup whose deeper subtrees can be marked not-walked — a floor, not an exact total. There is no way to get an exact size for a subtree without either inventorying every entry (risking the entry cap on a large target) or accepting a floor. Fanning size-only scanning out across multiple worker subagents currently requires re-explaining the Bash invocation contract to each worker by hand, because no reference document for it ships with the skill.

Desired behavior:
A new --sizes-only mode on the scan subcommand performs a full walk and returns an exact children_rollup (and an exact per-target total) with no per-entry inventory output and no entry-count cap, since there is no inventory to cap. Its output is clearly marked exact, distinguishable from a depth-cut or capped rollup, which reports floors. Separately, a worker brief ships as a skill reference file containing the exact guarded Bash command shapes a worker may run, the scan invocation template (including --sizes-only), and the rule that a worker reports what the snapshot says without disposing, ranking, or recommending. The skill body links to this reference at the point where fan-out to subagents is described.

Key interfaces:

• scan subcommand: new --sizes-only flag
• children_rollup output field: exact and uncapped when produced by --sizes-only, carrying a marker that distinguishes it from a depth-cut or capped rollup
• Worker brief: a skill reference file (not a second skill body) containing the Bash contract, the invocation template, and the evidence-only reporting rule

Acceptance criteria:

• Running scan --sizes-only against a target performs a full walk and returns an exact children_rollup with no per-entry inventory list in the output.
• Running scan --sizes-only against a fixture whose entry count would exceed the ordinary inventory cap completes successfully with no truncation and no cap-exceeded error.
• The --sizes-only output is marked so a caller can tell it apart from a rollup produced by a capped or depth-limited ordinary scan, demonstrated by a test comparing both outputs over the same truncating fixture.
• A worker brief reference file exists containing the Bash contract, the scan invocation template referencing --sizes-only, and the evidence-only reporting rule.
• The skill body's fan-out section links to the worker brief reference file.

Out of scope:

• Changing the default (non---sizes-only) scan's entry cap or depth-limiting behavior.
• Any disposition, ranking, or cleanup recommendation derived from --sizes-only output.
• Free-space or proportionality reasoning over the resulting sizes.