Repository navigation
Description
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_qualifierscaveat 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-onlyonce 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-onlyadds 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-onlyperforms a full walk with no per-entry inventory and no entry cap, and returns an exactchildren_rollupin 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-onlyover 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 --runselects 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-onlyoutput 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.
Activity
kyle-sexton commentedon Sep 23, 2026
This was generated by AI during triage.
Agent Brief
Type: Feature
Summary: Add a
scan --sizes-onlymode 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:
scanalways produces a per-entry inventory bounded by an entry-count cap, and, when depth-limited, achildren_rollupwhose 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-onlymode on thescansubcommand performs a full walk and returns an exactchildren_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:
scansubcommand: new--sizes-onlyflagchildren_rollupoutput field: exact and uncapped when produced by--sizes-only, carrying a marker that distinguishes it from a depth-cut or capped rollupAcceptance criteria:
scan --sizes-onlyagainst a target performs a full walk and returns an exactchildren_rollupwith no per-entry inventory list in the output.scan --sizes-onlyagainst a fixture whose entry count would exceed the ordinary inventory cap completes successfully with no truncation and no cap-exceeded error.--sizes-onlyoutput 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.--sizes-only, and the evidence-only reporting rule.Out of scope:
--sizes-only) scan's entry cap or depth-limiting behavior.--sizes-onlyoutput.chore(disk-hygiene): release 0.27.0 for scan --sizes-only (#4009)
fix(disk-hygiene): sizes-only still honors a depth cut (#4009)
fix: advisory hooks fail open with one stderr line (#3713) (#4853)
feat(disk-hygiene): scan --sizes-only and fan-out worker brief (#4009) (
fix(disk-hygiene): report partial rollup precision when subtrees fail…
docs(disk-hygiene): move scan-flag detail into a reference spoke
chore(disk-hygiene): release 0.29.0
kyle-sexton commentedon Sep 29, 2026
This was generated by AI during fix work on the 2026-09-29 audit of the unattended Cursor run.
Reopened: delivery gaps fixed, one owner question open
What the audit found. The
rollup_precisioncorrectness bug and the missing comparison and unreadable-directory tests are fixed in #5336 (Refs). One question is the owner's:--sizes-only, merged in #4832, skips the large-target confirmation gate (hygiene.pyabout lines 4378 and 4452), skips VCS-boundary and protected-path truncation (about 1952, 1957), and still retains oneentries[]item per path in memory. The issue asked only to drop the entry cap. Reopened withneeds-humanandstatus: needs-decision.Decision needed
Question. Keep that behavior, or route it through the same confirmation gate? Sub-question: sum without retaining entries to bound memory?
Options.
Recommended (not a decision): B, plus not retaining entries. Basis: the confirmation gate exists so a human confirms an unbounded walk of known-large roots, and the issue never asked to remove it; exactness (criterion 1) requires walking protected and VCS directories, which is read-only. Settling evidence: the owner's answer on whether the cost or surprise of an unconfirmed full walk is acceptable.
Unblocks. Whether the SKILL.md and safety-model wording from #5336 is kept or replaced, and any code change.
docs(disk-hygiene): state gate behavior without decision framing
kyle-sexton commentedon Sep 29, 2026
Owner decision (2026-09-29): Option B, plus not retaining entries.
scan --sizes-onlykeeps walking protected and VCS directories (exact totals need it; read-only) but must go through the same large-scan confirmation gate as an ordinary unbounded walk, and must sum sizes without keeping oneentries[]item per path in memory. Owner note: accepted the recommendation as written.Next: an agent changes the gate and the memory use in the disk-hygiene scan engine, updates the SKILL.md and safety-model wording from #5336 to match, then closes #4009.
fix(disk-hygiene): repair audit findings in guards, scan ladder, docs…
kyle-sexton commentedon Sep 30, 2026
Owner decision (2026-09-30): Implement the 2026-09-29 decision (Option B plus not retaining entries) in plugins/disk-hygiene, then close #4009 when the PR merges.
and not sizes_onlyexemption (line 4443) so--sizes-onlygoes through the same--confirmed-large-scangate as an ordinary unbounded walk. Keep walking VCS and protected directories (lines 2002-2007 already skip truncation undersizes_only), since exact totals need it.entries[]item per path whensizes_onlyis true. Keep theinventory_mode: sizes-onlyandrollup_precision: exactmarkers and the payload shape unchanged.--confirmed-large-scanasks the question; with the flag it proceeds) and a memory test (a sizes-only snapshot holds no per-path entries and its totals match the ordinary scan over the same fixture). Keep the existing truncating-fixture, cap-exceeded and comparison tests passing. Runscripts/affected-tests.sh --run.--confirmed-large-scanwhere needed. Check docs/conventions/skill-argument-shape/README.md line 87 for the flag list.Closes #4009and the required body sections.No credentials, elevation or deletion are needed.
Approved by the owner with all consensus recommendations on 2026-09-30 (three read-only researchers, majority or judge).
Next: an agent picks this up from the
agent-readyfrontier, implements it in a draft PR, and #4009 closes when the PR merges.docs(disk-hygiene): fix run-directory, fan-out brief and --project-di…