Runtime Prune
Intro
runtime-prune gives agents a provider-neutral cleanup workflow for
runtime-manager-owned state. It inventories selected cleanup scopes,
produces a dry-run plan, applies low-risk processkit-owned cleanup from
an explicit allowlist, and returns structured host-action evidence for
high-risk runtime-owner cleanup. It does not invoke host orchestrator
commands from inside the processkit runtime.
Overview
Use this skill when a project has accumulated runtime-home caches,
build caches, agent worktree state, container storage, or E2E companion
state and the user wants to inspect or reclaim disk space safely.
The workflow is:
- Call
analyze_disk_usage(project_root, scopes) to inventory
configured cleanup scopes without modifying the filesystem.
- Call
plan_prune(project_root, scopes) to produce a dry-run plan,
expected reclaimed bytes, risk labels, and the exact confirmation
token needed for apply.
- Call
apply_prune(project_root, scopes, confirmation) only after
the user has explicitly approved the plan. The apply tool may remove
only explicit processkit-owned allowlist targets; provider/runtime
owner cleanup returns an external host-action result for the owner.
MCP Tools
| Tool |
Purpose |
analyze_disk_usage(project_root, scopes) |
Return structured size and risk data for selected cleanup scopes. |
plan_prune(project_root, scopes) |
Return a dry-run prune plan and required confirmation token. |
apply_prune(project_root, scopes, confirmation) |
Apply processkit allowlist cleanup and return external host-action evidence for unsupported scopes. |
Scopes
| Scope |
What it covers |
Apply policy |
runtime-home |
Bounded runtime-home cache, diagnostics, tmp, and runtime paths. |
Processkit allowlist cleanup. |
build-cache |
Explicit build-cache paths such as Rust incremental and build subdirectories. |
Processkit allowlist cleanup. |
agent-worktrees |
Provider-created or runtime-manager-owned Git worktrees discovered from Git metadata. |
External host action after explicit confirmation. |
containers |
Host runtime container cleanup. |
External host action; no direct Docker or Podman calls. |
e2e-companion |
Nested companion environment cleanup. |
External host action; companion access must use owner-approved reachability checks. |
Gotchas
- Do not treat analysis as approval.
analyze_disk_usage() and
plan_prune() are read-only. Apply still needs the exact confirmation
token returned by the plan.
- Do not hand-roll destructive provider cleanup.
apply_prune() may
clean processkit-owned allowlist targets, but worktrees, containers,
and companion state must return structured external host-action
evidence instead of invoking a host orchestrator command.
- Do not remove the whole runtime home.
runtime-home targets only
narrow cache, diagnostics, tmp, and runtime subpaths, not the whole
.aibox-home tree.
- Do not inspect local Docker or Podman for E2E companion cleanup.
Companion state is remote from the devcontainer's perspective; use
the owner-approved host workflow that checks reachability.
- Do not count arbitrary project files as reclaimable. Only
explicitly scoped runtime and cache paths contribute to expected
reclaimed bytes.
- Do not delete provider worktrees by path heuristics. Worktrees
are inventoried for visibility, but deletion is delegated to the host
runtime manager because it owns provider-specific safety checks.
- Keep paths provider-neutral in user-facing output. Report scopes
like
agent-worktrees and runtime-home, not Claude-, Codex-, or
shell-specific state unless a discovered path itself contains that
name.
Full reference
analyze_disk_usage() resolves project_root to an existing directory
and defaults to all scopes when none are supplied. It never follows
symlinks during size walks.
plan_prune() returns:
required_confirmation, formatted as
apply-prune:<comma-separated-scopes>
- per-scope actions with
risk, apply_owner,
expected_reclaim_bytes, targets, dry_run_command, and
apply_command
apply_prune() accepts only the exact required_confirmation value
from the matching plan. For runtime-home and build-cache, it removes
only the allowlisted paths from the plan. For external scopes, it records
per-scope host-action evidence and leaves execution to the owner outside
the container.
1---
2name: runtime-prune-2
3description: >
4 Inspect, plan, and invoke safe cleanup for runtime-manager-owned state
5 without binding the workflow to a specific host orchestrator or agent
6 provider.
7metadata:
8 source: https://skillmd.com/skills/projectious-work/runtime-prune-2
9 processkit:
10 apiVersion: processkit.projectious.work/v2
11 id: SKILL-runtime-prune
12 version: "1.0.0"
13 created: 2026-05-13T00:00:00Z
14 category: processkit
15 layer: 2
16 uses:
17 - skill: skill-gate
18 purpose: >
19 Require explicit routing and confirmation before destructive
20 cleanup.
21 provides:
22 primitives: []
23 mcp_tools:
24 - analyze_disk_usage
25 - plan_prune
26 - apply_prune
27 assets: []
28---
29
30# Runtime Prune
31
32## Intro
33
34`runtime-prune` gives agents a provider-neutral cleanup workflow for
35runtime-manager-owned state. It inventories selected cleanup scopes,
36produces a dry-run plan, applies low-risk processkit-owned cleanup from
37an explicit allowlist, and returns structured host-action evidence for
38high-risk runtime-owner cleanup. It does not invoke host orchestrator
39commands from inside the processkit runtime.
40
41## Overview
42
43Use this skill when a project has accumulated runtime-home caches,
44build caches, agent worktree state, container storage, or E2E companion
45state and the user wants to inspect or reclaim disk space safely.
46
47The workflow is:
48
491. Call `analyze_disk_usage(project_root, scopes)` to inventory
50 configured cleanup scopes without modifying the filesystem.
512. Call `plan_prune(project_root, scopes)` to produce a dry-run plan,
52 expected reclaimed bytes, risk labels, and the exact confirmation
53 token needed for apply.
543. Call `apply_prune(project_root, scopes, confirmation)` only after
55 the user has explicitly approved the plan. The apply tool may remove
56 only explicit processkit-owned allowlist targets; provider/runtime
57 owner cleanup returns an external host-action result for the owner.
58
59### MCP Tools
60
61| Tool | Purpose |
62|---|---|
63| `analyze_disk_usage(project_root, scopes)` | Return structured size and risk data for selected cleanup scopes. |
64| `plan_prune(project_root, scopes)` | Return a dry-run prune plan and required confirmation token. |
65| `apply_prune(project_root, scopes, confirmation)` | Apply processkit allowlist cleanup and return external host-action evidence for unsupported scopes. |
66
67### Scopes
68
69| Scope | What it covers | Apply policy |
70|---|---|---|
71| `runtime-home` | Bounded runtime-home cache, diagnostics, tmp, and runtime paths. | Processkit allowlist cleanup. |
72| `build-cache` | Explicit build-cache paths such as Rust incremental and build subdirectories. | Processkit allowlist cleanup. |
73| `agent-worktrees` | Provider-created or runtime-manager-owned Git worktrees discovered from Git metadata. | External host action after explicit confirmation. |
74| `containers` | Host runtime container cleanup. | External host action; no direct Docker or Podman calls. |
75| `e2e-companion` | Nested companion environment cleanup. | External host action; companion access must use owner-approved reachability checks. |
76
77## Gotchas
78
79- **Do not treat analysis as approval.** `analyze_disk_usage()` and
80 `plan_prune()` are read-only. Apply still needs the exact confirmation
81 token returned by the plan.
82- **Do not hand-roll destructive provider cleanup.** `apply_prune()` may
83 clean processkit-owned allowlist targets, but worktrees, containers,
84 and companion state must return structured external host-action
85 evidence instead of invoking a host orchestrator command.
86- **Do not remove the whole runtime home.** `runtime-home` targets only
87 narrow cache, diagnostics, tmp, and runtime subpaths, not the whole
88 `.aibox-home` tree.
89- **Do not inspect local Docker or Podman for E2E companion cleanup.**
90 Companion state is remote from the devcontainer's perspective; use
91 the owner-approved host workflow that checks reachability.
92- **Do not count arbitrary project files as reclaimable.** Only
93 explicitly scoped runtime and cache paths contribute to expected
94 reclaimed bytes.
95- **Do not delete provider worktrees by path heuristics.** Worktrees
96 are inventoried for visibility, but deletion is delegated to the host
97 runtime manager because it owns provider-specific safety checks.
98- **Keep paths provider-neutral in user-facing output.** Report scopes
99 like `agent-worktrees` and `runtime-home`, not Claude-, Codex-, or
100 shell-specific state unless a discovered path itself contains that
101 name.
102
103## Full reference
104
105`analyze_disk_usage()` resolves `project_root` to an existing directory
106and defaults to all scopes when none are supplied. It never follows
107symlinks during size walks.
108
109`plan_prune()` returns:
110
111- `required_confirmation`, formatted as
112 `apply-prune:<comma-separated-scopes>`
113- per-scope actions with `risk`, `apply_owner`,
114 `expected_reclaim_bytes`, `targets`, `dry_run_command`, and
115 `apply_command`
116
117`apply_prune()` accepts only the exact `required_confirmation` value
118from the matching plan. For `runtime-home` and `build-cache`, it removes
119only the allowlisted paths from the plan. For external scopes, it records
120per-scope host-action evidence and leaves execution to the owner outside
121the container.