Managed disk usage and task cleanup
Projects shows allocated disk bytes on project, container and session rows in
the shared TUI/web/desktop interface. Mosaic cards show the session HOME and
its container's managed storage. Sizes use KiB/MiB/GiB/TiB and include the UTC
capture time. A partial total is a lower bound (≥), stale data is marked,
and unavailable/unmeasured data never becomes a misleading zero.
The execution host collects actual bind sources for checkouts, managed sessions, temporary directories, managed files and DinD data. Session HOME sizes are a breakdown of the sessions directory, not additional allocation. The same physical checkout mounted in multiple containers is counted once within a project. If a container hosts several repositories, its project row explicitly says shared environment storage; this is not unique per-project attribution. Shared image layers, container writable layers, account stores outside these directories and external mounted services are excluded. Their separate Docker/host statistics remain available in the existing resource view.
One low-priority background worker uses nice 19 and Linux idle I/O priority
(ionice -c3 when available, with a compatibility fallback). It uses allocated blocks (du, not apparent
file lengths), does not follow symlinks and stays on each source filesystem.
It refreshes cached measurements every 15 minutes. A scan takes at most 30
seconds, and each background batch has a 60-second/64-scope budget with a
30-second pause between unfinished batches. Sessions/HOME use one tree pass;
completed subtrees remain partial evidence if a huge tree times out. Optional
telemetry never blocks host inventory, session creation or navigation. Only
bounded, cached metadata crosses the controller API; no history or full
filesystem tree is downloaded by opening Projects. Deleted containers with
retained storage and projects without a placed container may be unmeasured;
use Storage for their separate retained-resource inventory.
Scoped MCP get_project_runtime returns container.managedDiskUsage with the
same components, HOME breakdowns, statuses and timestamps. No credentials or
raw host paths are included. The agent skills explain their scope.
Clean before the session ends
Press Shift+G on a project, container or session, or choose Inspect disk /
cleanup in the browser. A project opens its repository's sessions, a
container opens only that container, and a session opens only its own list.
The existing shutdown manifest supplies the inventory; there is no second
artifact format. Review the separate eligible and retained measured
sizes, unknown sizes and exact targets. Press c twice or use the confirmation
button to apply the reviewed SHA-256 manifest hash. Missing manifests do not
prove that no files or Docker resources remain.
For a running session, the agent must first stop and join task-owned processes and explicitly mark finished manifest entries:
{
"kind": "path",
"path": "/var/lib/devctl/session/homes/claude/tmp/finished-test",
"when": "exit-only",
"readyForCleanup": true
}
Live cleanup removes only marked descendants of the owning session's non-root-owned TMPDIR
and marked stopped DinD containers with its exact devctl.session.id label.
It rechecks ownership/state before deletion, never uses forced container
removal, and refuses active workloads, another session's files, shared checkout
paths, symlink escapes, host sibling jobs and session history. Retained Agent
Runs/configuration restarts remain protected. Stopped-session exit cleanup
keeps its existing behavior. The manifest is retained during live cleanup to
avoid overwriting concurrent agent updates; already removed entries are
idempotent and are no longer eligible in a fresh preview.
Live file cleanup pins parent directories with Linux file descriptors, then
uses physical GNU rm --one-file-system as the non-root TMPDIR owner. This
prevents a running agent from redirecting the root helper through a replaced
parent path. Custom containers without the Linux/GNU tools fail clearly and
retain their artifacts rather than using an unsafe fallback.
./devctl session cleanup-preview '<workspace-id>:<session-name>'
./devctl session cleanup '<workspace-id>:<session-name>' \
--manifest-hash '<reviewed-sha256>' --ready-only
Operator MCP run_devctl exposes the same commands. The controller API accepts
POST /v1/sessions/:id/cleanup with { "manifestHash": "…", "mode": "ready-only" }.
Administrator authorization and the reviewed hash are required; agent claims
alone do not authorize an operator action. Successful file/DinD cleanup
invalidates the host's disk cache and starts an asynchronous refresh. The TUI
and browser receive subsequent cached observations without restarting the
session or container. See session cleanup for exit,
restart, sibling and data-retention rules.