Report per-workspace disk size in dl --ls

[blooop]

Question

devlaunch reports zero size information anywhere: dl --ls --json (dl.py:490-503) has checkedOut, lastUsed, unsaved — no bytes; no shutil.disk_usage/du/st_size exists in the codebase. The disk work on this map needs a measurement primitive before anything is "reduced": add a per-workspace disk-size field to dl --ls / --ls --json.

Scope (deliberately narrow — measure what devlaunch owns):

• Size = bytes on disk of the workspace clone directory (<cache>/repos/<owner>/<repo>/<id>), computed with hardlink awareness (count each inode once — the clone shares pack files with the bare cache via hardlinks, so a naive du -s per workspace double-counts what is actually shared; report the workspace's exclusive bytes, or clearly label the number as apparent size — decide during build, document the choice in --help and README).
• Docker named volumes and image sizes are explicitly out: volume reporting is owned by issue Build: persist the devpod workspace id instead of re-deriving it, and reconcile the orphans #88's reconciler; image layers belong to Docker.
• JSON field name and human rendering consistent with the existing table; must not slow --ls unacceptably on many workspaces (a size walk is O(files) — if it costs more than ~100ms per workspace, make it opt-in, e.g. --ls --size, and say so).
• Failing test first: a workspace tree of known content reports the expected bytes; JSON schema gains the field; hardlinked pack files are not double-counted (or the apparent-size choice is pinned by test).

Pointers: dl.py:490-503 (--ls rendering), devlaunch/workspace_state.py (per-workspace facts, PR #134's seam), test coverage for --ls in test/.

[blooop]

breadcrumb: build stage started — fresh wf-tdd subagent, branch perf/153-ls-disk-size, base f03158b.

[blooop]

breadcrumb: resumed by a fresh wf-auto run. Verified against origin: branch perf/153-ls-disk-size does NOT exist, no PR — nothing was pushed. Stage reset to ready. Holding this build until the two disk grillings (#154 clone object sharing, #155 orphaned-disk reclamation) resolve, so the reporting surface is designed once against their answers rather than churned twice.

[blooop]

breadcrumb: claimed and building against the now-settled #154/#155 answers. Seams and the one real decision, stated before any code.

Seams I will test at.

1. A new self-contained disk-usage primitive: one pure-filesystem function, directory in, a sum type out. No devpod, no git, no metadata — so the caller that is classifying (dl --prune: remove clone directories no workspace references #159 --prune) imports the same function the caller that is rendering (--ls) uses, exactly as Reclaim orphaned disk: stale clone directories and left-behind images #155 required. This is where the hardlink semantics are pinned by test.
2. The JSON listing, which gains one field per row.
3. The human listing table, which gains one column.

Exclusive, not apparent. The number reported is what deleting that workspace directory would actually free: each inode counted once, and a file inode counted only when every one of its links lies inside the tree being measured. Measured on this host's real cache, a workspace clone of a ROS repo reads 755.0 MiB apparent against 488.8 MiB exclusive — the 266 MiB gap is one pool of pack files hardlinked out of the bare and shared by three workspaces. Apparent would bill each of the three for the whole pool, reporting 2.48 GiB where the disk really holds 1.70 GiB. That is not a rounding difference: it is #154's headline saving reported as if it had never happened. It also gets worse as the design gets better, since #154 extends the same hardlinking to LFS. And it is the wrong number for the caller that is about to act — "how much do I get back" is the only question --prune is asking.

The honest cost of that choice, recorded rather than hidden: exclusive bytes do not sum to total disk. The shared pool is billed to nobody, because deleting any one holder frees none of it. That is true, and a total that over-counts by 46% is not.

No zero for "could not tell". Principle 3, taken literally: the result type has an arm for a complete measurement and an arm for a floor with the unreadable paths named — a walk that hit a directory it could not read reports "at least N", never N. Container-written directories are the normal case here, not the exotic one.

Opt-in, behind --size. Measured, warm page cache, three runs: 38.8–46.2 ms per real workspace clone (9,050–9,386 entries). That is under the ticket's 100 ms trigger for a bare checkout — but the cost is O(files) with no ceiling, and the ordinary devlaunch workspace is not a bare checkout: a devcontainer that builds its environment inside the clone (this repo's own does) adds a tree that measures 8,956 entries / 45.5 ms by itself, and a 114,611-entry tree measured 224 ms warm and 707 ms on first read. Plain --ls is today one devpod round-trip and zero filesystem work, and #155 already ruled that --ls is not where a third unrelated question goes. So --ls stays exactly as fast as it is, and --ls --size / --ls --json --size is where the walk lives. Only devlaunch's own clones are walked; a workspace devlaunch did not make is reported as no measurement rather than having someone's home directory walked on their behalf.

[blooop]

breadcrumb: built and pushed as PR #165. --ls --size / --ls --json --size report exclusive bytes — what deleting a workspace would actually free, counting a file only when every one of its hardlinks lies inside it. Apparent size was rejected on measurement, not taste: on a bare plus two clones, du bills each workspace 2,539,520 B for a .git that costs 258,048 B to keep, which is #154's saving reported as if it had never happened; across a real cache the same error reads 2.48 GiB against the 1.70 GiB the disk holds. The choice is pinned by test and mutation-checked — swapping in an apparent size fails that pin and nothing else. Documented in --help and the README, including the honest cost: exclusive bytes do not sum to total disk, because bytes shared by three workspaces are freed by deleting none of them.

Opt-in behind --size. Measured warm, a real workspace clone walks in 27.6–32.2 ms — under the 100 ms trigger — but the walk is O(files) with no ceiling and the ordinary workspace has its built environment inside it (measured: another 8,956 entries / 45.5 ms; a 114,611-entry tree took 224 ms warm, 707 ms on first read). Plain --ls keeps its one devpod round-trip and zero filesystem work, pinned; --size adds no subprocess at all.

A measurement that could not finish is never a number: two arms, a total or a floor, so an unreadable directory reports "at least" rather than a small-looking total. The primitive is free of devpod, git and metadata so the orphan classifier can import it rather than grow its own walk.

[blooop]

breadcrumb: PR #165 is green on every check — the four-python matrix, e2e, prek, gate and both codecov gates. One follow-up commit after the first push: the SIZE heading was wider than a column of dashes, which shifted every date after it on a listing with no devlaunch clones in it, and the walk's refusal arms are now exercised rather than argued for (a tree behind an untraversable parent, entries a directory will name but not stat), taking the size primitive to 100% covered. Build stage ends here; nothing parked.

[blooop]

breadcrumb: review stage complete on #165 — verdict Request changes (1 blocking: test_ls_with_sizes_spawns_nothing_extra calls exclusive_usage 0 times and stays green with a subprocess regression injected, full-suite selection). Two-axis report: #165 (review)

[blooop]

breadcrumb: the review's blocking finding was real and the guard was empty. The case that claimed to pin "asking for sizes adds no subprocess" listed a workspace whose source sat outside the cache directory the test had patched, so nothing about it was measurable, the walk never ran, and the assertion counted a code path that did not execute — a du per workspace passed it under every selection. The fixture now puts a real clone with a payload under the patched cache, and the rendered size is asserted before the spawn counts, so an unmeasured cell fails the test instead of emptying it. Proved by injecting that exact subprocess and running the whole suite: red with it (one failure, exactly this test), green without it, same tree both times.

I re-asked the same question of every other pin this ticket added. The unit tests all do real filesystem work — real hardlinks, real closed doors — and the exclusivity pin still fails under a whole-suite run when the exclusivity condition is replaced with an apparent size, so it is effective in CI and not only in isolation. No second hollow one found.

The table and the machine-readable listing were deciding "may we measure this workspace" from two different things, and already disagreed: a clone sitting in devlaunch's own cache that devlaunch had no metadata record for was given a size in the table and reported as not-measurable in JSON. Metadata can go missing from a cache that is very much on disk, and the same workspace is one a purge would delete, so the record is the wrong thing to gate on. Both now ask the one predicate that decides ownership everywhere else, and a test pins that the two renderings name the same set.

The walk timings are all re-measured with the shipped code and the machine and conditions published beside them; the figure the docs carried matched no measurement anyone had taken and is gone. No cold-cache number is quoted, because none was taken — dropping the page cache needs root here. The docs also stopped attributing a du figure to file lengths; du counts blocks, which is what the code measures.

Folded in while open: an exported accessor for "the bytes, whichever arm", so the prune work can order workspaces without reaching into the sum type; and a file or directory that vanishes between being named and being weighed is now worth nothing rather than unknown — a cache in use does that on its own, and only a door that will not open should turn a total into a floor.

[blooop]

breadcrumb: re-verdict after retry on #165 — Approve; the blocking hollow-guard finding is closed (re-derived: injected devpod du now fails test_ls_with_sizes_spawns_nothing_extra under full-suite selection; 12/12 mutations bite). One pre-merge docs tidy, non-blocking: README/disk_usage.py still ship the un-verifiable 2.48 GiB/1.70 GiB/755.0/488.8 MiB figures un-hedged. #165 (review)

[blooop]

breadcrumb: docs-only follow-up, no executable line changed.

The four figures the shipped docs argued the exclusive-vs-apparent choice from came from a cache that has since been emptied of its workspace clones. They were stated in the present tense next to timings that carried their full conditions, so nothing signalled to a reader that one set was measured here and the other inherited — and one of them was also the example value in the README's sample table. The hedge I wrote about them existed only in the pull request body, which nobody installs. They are gone from every shipped file.

What replaces them is the measurement I actually took while re-checking this work, published with its conditions: one real clone against du, the bare it hardlinks out of, and the two together — four rows from which the over-bill (5.2x, traced to one named pack file with two links) and the non-summing consequence can both be read directly rather than asserted. The claim that argument supports is now independently reproduced three separate times by three different people on three different sets of repositories, so nothing rests on a number only one person has seen.

The explanation had also accumulated in five places and the figures in three, which is exactly where the next re-measurement drifts. There is now one home for why-and-how-much — the module that does the measuring — with the rendering adapters and the test modules pointing at it, and the timings live once, in the README.

Left alone deliberately, all raised as non-blocking and none of them docs: the exported "bytes, whichever arm" accessor still has no production caller and may be better landed with the pruning work that wants it; the documented zero-for-a-hand-removed-clone answer and the directory-blocks term of the walk are both unpinned; and the containment test is lexical with no symlink resolution, which is benign for measuring but must not be reused as-is by the pruning work. Recorded here so they are not lost.