Repository navigation
Description
.dag: issue-dag/2
.id: flyingrobots/devcontainers#5
.kind: task
.type: feature
.blocked_by: [flyingrobots/devcontainers#3]
.size_hours: 6
source: Maintainer rule of 2026-11-08 (no Docker litter; ULTRAMAX PARANOIA hygiene)Feature
Read docs/hygiene.md sections 5, 8, 9, and 11.
Before and after each run, list containers, volumes, networks, and images with their labels. Fail the run when a new resource is unnamed, unlabeled, or not in the section 5 table, or when the run container still exists.
Before each run, refuse to start when the host or the Docker VM has less than 50 GiB free.
After each run, measure the target and scratch volumes in a labeled measuring container with --network none, and fail above the budgets.
Write a JSON receipt for every run (image digest, copy mode, source SHA, tarball SHA-256, command, network mode, limits, exit code, duration, audit result, volume sizes) into the export folder.
Test the audit with a fake docker that injects an anonymous volume, an unnamed network, and a leftover container.
Run every Docker command through the code under test or the workstation git-locks keys host/docker/devcontainers-dev/ and host/heavy-work. Never build or test on the host outside Docker.
1. Background Context
The maintainer asked that no unnamed volumes, networks, or other litter be left behind. The global working rules also require measured budgets and a record of each heavy run.
2. Problem Description
A runner without an audit can leave litter that nobody notices.
2b. Proposed Solution
A before-and-after inventory diff with an allowlist from the hygiene table, a volume measurement, a free-space check, and a receipt.
2c. Alternatives considered and rejected
docker system pruneafter runs: rejected, because it removes other projects' resources.
2d. Acceptance Criteria
- Injected litter of each kind fails the run, and the failure names the resource.
- A target volume over a small test budget fails the run.
- Low free space refuses the run before any container starts.
- Every run, failed or not, leaves a receipt.
2e. Test Plan
Golden: a clean real run has an audit result of clean.
Edges: other projects' resources appear during the run (they are ignored because they lack the owner label).
Known failure modes: the measuring container itself counted as litter.
Fuzz and stress: not applicable.
3. Prerequisites
- Write the guarded runner devrun (copy-in, isolation, network phases, lifecycle) #3: the core runner.
4. Scope
In:
- Audit, free-space check, budget measurement, and receipts.
Out:
- Cleanup of other projects' resources.
Size: about 6 hours of focused work.
5. Why now
The maintainer asked for it explicitly.
6. Risks
A concurrent run of another project creates resources during the audit. The owner-label filter handles it.
7. Definition of Done
The audit is merged with tests, and a real run reports clean.
8. Stakeholders
- James Ross (maintainer).
Activity
flyingrobots commentedon Nov 8, 2026
Follow-ups from the Baker Street review of #6, disclosed in its PR body as known gaps:
scripts/build-imageandtests/smoke-image, thedocker buildx inspect,image inspect,psandrmcalls have no alarm. A hung Docker daemon could outlast the git-locks lease, and the lease would then admit a second heavy job. Bound each call, or the whole command, below the lease.GITHUB_ACTIONS=trueorDEVCONTAINERS_LOCK_HELDskips the lock.GITHUB_ACTIONS=truealso skips the free-space and leftover checks. That is correct on single-use GitHub-hosted runners, but not on a self-hosted runner on the workstation. A run's audit and receipt should record which guards ran.flyingrobots commentedon Nov 8, 2026
One more follow-up from the same review: BuildKit cache from
scripts/build-imagecarries no labels, and thedocs/hygiene.mdsection 8 budgets measure volumes only. The audit should measure builder cache against the build-output budget, for example withdocker buildx du.Bring devrun up to the hygiene rules that landed with the base image