Session shutdown resources
Session cleanup follows declared ownership and retention, not whether a subscription is shared. Revoking a shared account does not stop providers or delete their history; authorization cleanup waits for confirmed process absence. Compute-resource deletion and session-history retention are separate decisions. Shared subscriptions (source access required), persistence.
Empty development containers also have an owner-scoped idle shutdown policy, enabled by default with a 15-minute grace period. It stops the retained execution container and its managed companions after all sessions end; it does not delete files or power off the server. Working, waiting, quota-paused, hidden and starting sessions keep their container active. This policy is separate from the task-artifact cleanup below.
DEVCTRL.AGENTS.MD is generated for each Project container. Each managed
session also receives DEVCTL_SESSION_ID and DEVCTL_SHUTDOWN_PATH. The latter
points to agent-interchange/shutdown/<session-id>.json; sessions sharing a
Project container never share a manifest. Agents must replace this file
atomically after creating or removing a tracked resource.
{
"version": 1,
"sessionId": "workspace-id:session-name",
"resources": [
{ "kind": "path", "path": "/tmp/job-123", "when": "restart-and-exit" },
{ "kind": "dind-container", "id": "0123456789ab", "when": "exit-only" },
{
"kind": "host-container",
"id": "abcdef012345",
"when": "exit-only",
"healthScript": "/project/scripts/job-health.sh",
"deleteDataPaths": []
}
]
}
restart-and-exit is cleaned before a managed session/configuration or Project
container rebuild resumes the provider. exit-only is cleaned after /exit,
explicit session deletion, or deletion of the Project container/Project in the
TUI. Stopping a container or parking an autonomous Agent Run is not a full
session end. Invalid manifests fail closed and remain available for repair.
Resources during a running task
The generated DEVCTRL.AGENTS.MD requires a cleanup strategy before creating
any resource-consuming entity, not just when the session ends. This applies
to folders, worktrees, dependency copies, caches, logs, containers, volumes,
networks, images, processes, subagents and external compute/storage resources.
Record the owning task/session, purpose, exact path or immutable ID, CPU/memory/
disk/count budget, cleanup trigger and procedure in the task checkpoint. Retained
resources also need a reason, expiry or review interval, size/count limit and
the owner responsible for the next cleanup. Keep secrets out of the inventory.
Clean authorized disposable resources after each job or test run, including
failure, cancellation and timeout, while the parent session remains running.
Use test teardown, try/finally or shell traps, stop and join owned processes,
and check long-running work periodically. Collect required test evidence before
removing stopped containers. Repeated tests must not accumulate a fresh stack
of old containers and temporary databases on every retry. Label DinD containers
with devctl.session.id=$DEVCTL_SESSION_ID and retain immutable IDs.
Containers, volumes, networks and images have separate lifecycles. --rm helps
with disposable containers but does not replace failed-setup handling or a
plan for named volumes. Preserve shared services, databases, another session's
resources and retained outputs. Task-authorized disposal does not require a
second approval; broader deletion requires its own authorization. Never use a
host-wide prune or wildcard deletion instead of exact ownership checks.
Update the inventory after creation/removal and report retained resources,
cleanup failures and measured reclaimed space at checkpoints. Existing MCP
report_session_handoff can record those facts in knownIssues and nextStep;
it does not perform deletion. A failed cleanup must not silently lead to
unbounded replacement resources.
The shutdown manifest is a final fallback with its existing supported kinds, triggers and 100-resource limit. It is not a task-completion scheduler or TTL collector and cannot express arbitrary Docker volumes or cloud resources. Agents must implement their in-task teardown explicitly. These are managed agent instructions, not automatic discovery or an enforced universal resource collector. Live guide upgrades replace only the resource-lifecycle section, preserve scoped grants, and require no provider/container restart.
Exit hooks and persistent containers
Managed Claude and Codex launches install their native SessionEnd lifecycle
hook. The hook writes a bounded local lifecycle record; it never deletes files,
talks to the host Docker socket, asks a model for permission, or waits for a
remote cleanup operation. The controller consumes the record and queues a
durable session.shutdown command to the execution host. A confirmed PTY exit
uses the same path. Detached providers without a usable exit hook are covered
by two consecutive host inventory samples confirming process absence. Cleanup
does not depend on an open TUI or browser. See the official
Claude hooks and
Codex hook configuration.
Claude also sends SessionEnd when /clear or interactive /resume switches
the conversation while the CLI process continues. These reasons do not trigger
full-exit cleanup. Managed configuration restarts preserve exit-only entries.
Leaving or detaching from a terminal does not end its agent process.
Finishing the only session does not remove the Project container. It is a persistent workspace: its checkout, installed tools, and retained volumes can be reused by the next session. Session cleanup removes only declared resources approved for that session, even when other sessions share the container.
Explicitly deleting a session runs host cleanup before removing its devctrl history row; it keeps the workspace container. Explicitly deleting a Project container or Project stops its managed sessions, processes their manifests, then removes that workspace's runtime, DinD, and egress containers by immutable Docker ID and owner labels. An unfinished managed sibling defers deletion; failed cleanup leaves the registration available for repair. Bind-mounted data, named/anonymous volumes, images, provider-account stores, and durable Project configuration are retained. They need a separate reviewed storage cleanup decision; there is no global Docker prune. Project deletion separately removes its managed remote checkout when authorized by the existing dirty-worktree confirmation, and preserves adopted external source directories.
path is confined to descendants of the Project checkout, ordinary /tmp,
/dev/shm, or the owning session's $TMPDIR below its managed HOME.
The session temporary root itself, another session's temporary directory,
provider history, account stores and other HOME contents cannot be targets.
Preview and deletion use the same path and symlink checks. Session temporary
files are persistent disk-backed storage; they have no automatic age-based
retention. By default, explicitly declared, authorized entries are removed after the
session stops; reviewed ready-only cleanup may remove finished task resources earlier. this does not turn missing manifests into an automatic sweep.
Checkout roots, Git metadata and exchange mounts cannot be targets. dind-container
requires an immutable Docker ID and the devctl.session.id label. Neither
entry executes arbitrary shell commands.
For long computations outside DinD, launch_sibling_container (devctl MCP)
queues a host-agent operation after explicit approval. The sibling receives
only a read-only /project mount and dedicated writable /data directory;
it has no host Docker socket, privileged mode, or host network. The Project
container sees the same data at /run/devctl/sibling-data/<resource-id>.
get_sibling_launch_status resolves the queued command to its container and
resource IDs. Existing Project containers need a rebuild once to gain the
data mount; launch fails clearly until it exists.
The host agent writes a host-container entry to the session manifest and a
durable ownership record under its devctl data directory. On full session end,
health script exit 0 means work is complete, 1 means still running, and any
other code means failure. A pending job keeps cleanup/deletion queued. Once
complete, devctl removes the container. It keeps every file under /data
unless deleteDataPaths names that exact relative path. No implicit data
directory deletion or host Docker prune occurs. Retained paths, ownership,
descriptions, sizes and cleanup strategies appear under Storage in the TUI.
For machine-readable ownership, a Project container has
devctl.workspace.id (not one session label, because sessions share it).
Join that label to workspaces[].id and sessions[].workspaceId in
/v1/state. A managed sibling has both devctl.workspace.id and
devctl.session.id; /var/lib/devctl/managed-workloads.json also records
its immutable container ID, session ID, workspace ID and Project ID.
User-requested exit checklist
Before exiting, stop and join all subagents and background agents owned by the current session. Do not stop independent sessions or other Projects unless explicitly requested. Write a durable handoff under agent-interchange/handoffs/: goal, progress, changed files, verified tests, blockers and the next step.
Finish cleanup already authorized by the task's resource plan. Show an itemized proposal for additional deletions and ask before performing them; asking to exit alone does not authorize those deletions. The shutdown JSON is an executable cleanup request, not a proposal: atomically record only approved items. If additional cleanup is declined, retain those proposed resources. Existing host-container entries also have durable ownership records; retaining those needs operator handling, not silent removal from the manifest. Record the handoff location and cleanup decision before exit.
The host agent processes a valid manifest on managed session exit. It does not automatically discover every temporary directory or container created by an agent. An absent manifest means no manifest-driven file/DinD cleanup; a missing manifest with registered host siblings is an error. Invalid manifests and failed cleanup are retained for diagnosis.
For ordinary files and DinD containers, manifest creation depends on the agent following the managed Markdown instructions. There is no automatic file-creation tracker or enforcement that every session writes this JSON. Host siblings launched through launch_sibling_container are the exception: devctl records those resources itself. Before exit, compare the manifest with the resources created during the task; report untracked or retained resources in the handoff. Do not claim cleanup is scheduled until the approved entries have actually been written and checked.
An audit event saying session shutdown cleanup completed (0 resources) is a successful no-op, not evidence that the session left no garbage. A missing JSON can mean either that it was never written or that a previous cleanup consumed it. Check the cleanup result and resource count before claiming resources were removed; counts are not measurements of reclaimed disk space.
Test coverage and limits
The focused suites cover manifest parsing and session identity, refusal while a process is active, missing sibling manifests, preservation across restart, changed preview hashes, read-only size previews, controller authorization and lifecycle replay, detached process exits, sibling registration, pending workspace deletion, physical container ownership, and TUI confirmation for stopped sessions:
pnpm --filter @devctl/host-agent exec vitest run src/session-shutdown.test.ts src/workspace-shutdown.test.ts src/cleanup-preview.test.ts src/managed-workloads.test.ts
pnpm --filter @devctl/controller exec vitest run src/session-cleanup.test.ts
pnpm --filter @devctl/runtime exec vitest run src/session-lifecycle.test.ts src/workspace-removal.test.ts
pnpm --filter @devctl/tui exec vitest run src/session-cleanup.test.tsx
These suites use temporary manifest files and mocked Docker/runtime operations. An additional opt-in Docker test creates UUID-owned inert fixtures with no network, credentials, image pulls, or global prune:
DEVCTL_SHUTDOWN_INTEGRATION_SOCKET=/absolute/path/to/docker.sock \
DEVCTL_SHUTDOWN_INTEGRATION_IMAGE=node:24-bookworm-slim \
pnpm --filter @devctl/runtime exec vitest run src/session-shutdown.integration.test.ts
The image must already exist on that daemon. This test verifies actual approved file removal, retained output, rejection of checkout-root deletion, unchanged workspace process, physical runtime/sidecar removal on explicit deletion, idempotent retries, and preservation of an unrelated container. Its sidecar is an inert container, not a nested Docker daemon. It does not prove a provider writes every required manifest or that every real nested volume is removable.
Review and retry cleanup in TUI
Press Shift+G on a session in Projects or Sessions to inspect its shutdown manifest. On a Project row this opens its repository sessions; on a container row it opens only that container. In Storage, select a host and press Shift+G for a host-wide session cleanup page.
The page lists tracked resources with paths/container IDs, lifecycle policy, measured sizes, unknown sizes, invalid manifests and connection errors. Scroll with arrows or Page Up/Down. Press r to refresh. Sizes are estimates: nested paths can overlap; Docker writable layer size excludes volumes and shared image layers. Untracked files are not counted; an absent manifest does not prove a session left no data.
Press c to review cleanup, then c again to confirm all eligible stopped sessions in the displayed scope. Running sessions can use the separate ready-only mode described in managed disk usage; retained Agent Runs cannot be cleaned. The controller checks status again at submission, the host waits for processes to stop and checks ownership, and SHA-256 binds manual cleanup to the reviewed manifest. If the file changes, refresh and review again. Cleanup preserves the session history and removes the manifest only after success. A stopped Project container may need to be started before its internal paths/DinD can be cleaned; this action does not start it automatically. Pending sibling jobs remain deferred until their health check succeeds.
./devctl session cleanup-preview '<workspace-id>:<session-name>'
./devctl session cleanup '<workspace-id>:<session-name>' --manifest-hash '<reviewed-sha256>'
Operator MCP exposes the same commands through run_devctl (timeoutSeconds: 180). Review the preview and obtain the user's cleanup decision before applying its hash. This is not docker system prune and never deletes a Project checkout root or another session's containers.