Summary

• inventory WP Codebox-owned runtime directories under the effective OS temp root in doctor and cleanup
• retain recent directories and any directories protected by live process references, active preview leases, or recent run heartbeats
• report candidate/retained counts and reasons plus estimated/reclaimed allocated bytes, then inode-revalidate before cleanup

Fixes #2086

Root cause

wp-codebox doctor and wp-codebox cleanup only inspected recipe-run process names and ZIP archive roots. Runtime producers use mkdtemp() under the effective TMPDIR, so abandoned Playground sites, release/package staging, overlays, read-only mounts, and other runtime directories were outside the cleanup lifecycle.

Ownership and liveness evidence

Ownership is restricted to direct, non-symlink directory children of the canonical effective temp root on the same filesystem. WP Codebox producers use an explicit registry of exact prefixes found in the runtime creation code; upstream node-playground-cli-site-* directories additionally require a WordPress filesystem layout. Arbitrary TMPDIR content and unknown wp-codebox-* names are not selected.

Candidates are retained when their newest filesystem activity is younger than the stale threshold, a live process command/cwd/file descriptor references them, any WP Codebox recipe/agent/held-preview process is active, an active preview lease exists in a checked registry, or a run registry heartbeat is recent. Removal rechecks canonical containment and the original device/inode immediately before recursive deletion.

Structured contract

Before, wp-codebox/doctor/v1 contained process and archive checks but no temp-runtime accounting. After, the wp-codebox.temp-runtime check includes:

• tempRoot, scannedCount, and ownedCount
• candidateCount, retainedCount, and retainedReasons
• estimatedAllocatedBytes and reclaimedAllocatedBytes
• per-directory kind, ownership evidence, age, allocated bytes, state, retention reason, and cleanup error

--run-registry is repeatable for doctor/cleanup, WP_CODEBOX_RUN_REGISTRY_ROOTS can provide additional registries, and ./artifacts/runs remains the default registry evidence root.

Safety boundaries

• scans only the effective temp root's direct children
• never follows a candidate-root symlink or recursively traverses directory symlinks
• does not use a broad wp-codebox-* glob
• requires registered producer evidence; upstream Playground sites also require structural evidence
• age-gates every cleanup candidate
• conservatively protects all owned candidates while a runtime process, lease, or recent run is active
• revalidates canonical path, device, and inode before removal
• leaves unrelated and unproven similarly named directories untouched

Tests

• npm run test:temp-runtime-cleanup - passed
• npm run build - passed
• npx tsx scripts/doctor-command-smoke.ts - passed with isolated custom TMPDIR

Focused coverage includes live process protection, age protection, active lease and recent-run protection, stale orphan removal, idempotency, custom TMPDIR, structured allocated/reclaimed byte reporting, and unrelated-directory preservation.

Residual risks

The producer registry must be updated when WP Codebox introduces a new temp-directory prefix. Externally owned wrappers and test harness directories are intentionally not inferred from names or removed; they need their owning layer's lifecycle contract. Non-Linux hosts do not expose /proc process path references, so cleanup relies on age and registry evidence there and remains conservative for recognized active runtime command lines where available.