fix(runtime-host): reap stale Runtime Host control directories
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## What happened
Every State Root ever opened leaves a permanent directory under the Runtime Host control namespace — `~/.cache/maka/runtime-hosts//` on Linux (see `resolveRootControlNamespace` in `packages/storage/src/root-authority.ts`) — containing only a 0-byte `owner.lock`. There is no reaping path anywhere in the codebase: the namespace is created with `mkdir` and locked, but never cleaned up.
On one long-lived machine this has accumulated to **91,026 directories** (first seen 2026-07-20, still growing as of 2026-09-04). The bytes are negligible (~908 KB total), but the accumulation is unbounded and the directory itself becomes hostile to tooling — a plain glob over it fails with `Argument list too long`, and backup/indexing tools scan 91k dentries. Normal (non-development) usage accumulates one entry per State Root ever opened, forever.
Expected: stale control directories are reaped. The design already makes this safe — the durable State Root owner lock lives separately under `state-root-owners/`, and the code comment states the cache directory is disposable ("deleting a cache directory while a Host is running must never make the same State Root acquirable again", preserved by the durable lock). A reaper can e.g. attempt to acquire a directory's `owner.lock` on Host startup: if acquirable, no live Host holds it, and the directory can be removed after a grace period.
## How to reproduce
1. Run Maka (or its test suites) for some time; each new State Root mints one entry.
2. `ls ~/.cache/maka/runtime-hosts | wc -l` — count grows monotonically.
3. Inspect any entry: it contains only an empty `owner.lock`.
## Environment
- Maka version or commit: source checkout `b39e8d36ef`; observed installation tracks recent main
- OS and version: Ubuntu 26.04 LTS, x86_64
- Surface: Runtime Host
- Node.js version, if running from source: v26.3.0
## Logs, screenshots, or additional context
```text
$ ls -f ~/.cache/maka/runtime-hosts | wc -l
91026
$ du -sh ~/.cache/maka/runtime-hosts
908K
$ ls ~/.cache/maka/runtime-hosts/
owner.lock # 0 bytes
```
Note: development machines mint State Roots much faster (every test run / temporary workspace creates one), so the slope there is steeper than for typical users — but there is no cleanup for either.
Contributor guide
Research direction
Start with resolveRootControlNamespace in packages/storage/src/root-authority.ts, then trace Runtime Host startup and the existing owner.lock acquisition path. Done means stale runtime-host directories are reaped without making a State Root with a live Host acquirable again, with coverage for live and stale entries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- backend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100