Skip to content

Add the Docker litter audit, run receipts, and budget checks to devrun #5

Open

Description

@flyingrobots
.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 prune after 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

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).

9. Related Issues

Activity

  1. flyingrobots commented on Nov 8, 2026

    @flyingrobots
    OwnerAuthor

    Follow-ups from the Baker Street review of #6, disclosed in its PR body as known gaps:

    • Docker calls without a timeout. In scripts/build-image and tests/smoke-image, the docker buildx inspect, image inspect, ps and rm calls 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.
    • Guards skipped by inherited environment. GITHUB_ACTIONS=true or DEVCONTAINERS_LOCK_HELD skips the lock. GITHUB_ACTIONS=true also 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.
  2. flyingrobots commented on Nov 8, 2026

    @flyingrobots
    OwnerAuthor

    One more follow-up from the same review: BuildKit cache from scripts/build-image carries no labels, and the docs/hygiene.md section 8 budgets measure volumes only. The audit should measure builder cache against the build-output budget, for example with docker buildx du.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions