@vibelord/lanes 1.0.0

package/payload/lanes/libexec/tmpscan.py

@@ -0,0 +1,921 @@
+"""lanes tmp scan|plan|apply|reap — what fills a container's RAM-backed /tmp, and removing the DEAD part of it.
+
+  lanes tmp plan  [container…] [--budget S] [--fresh] [--all]   table (largest first) + $STATE/tmpscan/<c>.plan.tsv
+  lanes tmp scan  …                                             the same table, no plan file
+  lanes tmp apply [container…] --approve                        delete the plan's STALE units (without: list them)
+  lanes tmp reap  [container…] [--budget S]                     hourly timer: idle > 3 days, /tmp AND <home>/.tmp;
+                                                                DRY-RUN until $STATE/flags/tmpreap.armed exists
+
+Runs on the HOST, through /proc/<container-init-pid>/root/tmp (the path the viewers already use): no docker exec, no
+du, no subprocess at all. tmpfs metadata is never swapped out, so an lstat walk stays cheap on a thrashing host; it
+still runs at nice 19 under a wall-clock budget and RESUMES from $STATE/tmpscan/<container>.json on the next run.
+
+UNITS are what gets judged and removed as a whole: every top-level entry of /tmp, except that claude-<uid>/ is split
+into claude-<uid>/<project>/<session> (that one directory held 53 of the 95 GiB). A unit is KEEP when ANY of these
+holds, and STALE only when none does:
+  * its name is sacred (tmux-*, .lz, X11/ICE, systemd-private-*, snap-private-tmp) — these are not even walked;
+  * a process of the container uses it: cwd/root/exe/any fd (by path AND by st_dev+st_ino, so another path to the
+    same file counts) or a mapped file;
+  * it contains a socket, fifo or device;
+  * anything in it belongs to another uid than the container user;
+  * its newest mtime/ctime is younger than 24 h (reap: 3 days) — ctime too: a just-unpacked tarball has old mtimes;
+  * it is a Claude session whose transcript ~/.claude/projects/*/<session>.jsonl was written in the last 48 h, or
+    whose transcripts cannot be looked up at all;
+  * it is a Claude session that a LIVE process may own: a process that is not a lane fixture (shell, lane-run, tmux)
+    has the cwd <project> is named after, and the session was made or written to after that process started. An
+    idle agent holds no cwd and no fd under its session; this is the one rule that sees it. Not seen: a session
+    resumed under its old id by an agent that has not been given a prompt since;
+  * the scan of it was cut short, failed, or met a mount point.
+
+Deleting (apply, armed reap) re-judges every unit IMMEDIATELY before removing it — fresh walk, process references at
+most 5 s old — and removes it through directory fds only (openat O_NOFOLLOW, unlinkat): never by path, never
+through a symlink, never across a mount, never a special file. Every outcome is appended to
+$STATE/tmpscan/deleted.log. apply refuses a plan older than 6 h or made for another container init pid.
+Known blind spot, reported on every run: fds of processes of ANOTHER uid cannot be read without privilege.
+"""
+import collections
+import fnmatch
+import json
+import os
+import re
+import signal
+import stat
+import sys
+import time
+from pathlib import Path
+
+import guard as G
+import lanes_lib as L
+
+BUDGET = 120                    # s of wall clock per run and container
+PLAN_MAX_AGE = 6 * 3600         # apply refuses an older plan; an unfinished scan older than this starts over
+FRESH = 24 * 3600               # plan/apply: changed more recently than this => KEEP
+REAP_IDLE = 3 * 86400           # reap: the same rule, stricter
+TRANSCRIPT_FRESH = 48 * 3600
+# Directories that DECLARE themselves regenerable (bford.info/cachedir: cargo `target`, …). Measured 2026-09-19: agents
+# build inside their Claude scratchpads, and 26 of the 95 GiB of RAM-backed /tmp were idle cargo targets inside LIVE
+# sessions — units the unit rules rightly KEEP. A cache nobody wrote to or holds open for this long may go anyway.
+CACHE_TAG = b'Signature: 8a477f597d28d172789f06886806bc55'
+CACHE_IDLE = 6 * 3600
+REFS_MAX_AGE = 5                # s a process-reference pass may be reused for while deleting
+MAX_DEPTH = 100                 # one directory fd per level; deeper trees are KEEP, not an fd exhaustion
+SACRED = ('tmux-*', '.lz', '.X11-unix', '.ICE-unix', 'systemd-private-*', 'snap-private-tmp')
+CLAUDE_DIR = re.compile(r'^claude-\d+$')
+KEEP, STALE = 'KEEP', 'STALE'
+TICKS = os.sysconf('SC_CLK_TCK')
+START_SLACK = 300               # s: btime moves with clock steps, and a session directory is made AFTER its agent started
+# What sits in a project directory for the life of a LANE, not of an agent. Counting these would date every session
+# since the lane was made as "may be theirs". An exclusion list on purpose: a comm it does not know (the agent's is
+# `claude`, `node` or a version number) KEEPs more, a comm missing from an inclusion list would delete more.
+LANE_FIXTURES = frozenset(['bash', 'zsh', 'sh', 'dash', 'fish', 'lane-run', 'tmux', 'tmux: server', 'zellij'])
+
+# key: names the root in file names and logs · host: where THIS process opens it · view: the same directory as the
+# container's processes spell it (what /proc/<pid>/cwd and the fd links contain).
+Root = collections.namedtuple('Root', 'key host view')
+
+
+# ------------------------------------------------------------------ names
+
+def _sacred(unit):
+    return any(fnmatch.fnmatchcase(unit.split('/')[0], pattern) for pattern in SACRED)
+
+
+def _safe_name(unit):
+    """A unit we are willing to write into a line-oriented plan and to open again from it."""
+    parts = unit.split('/')
+    # isprintable: no tab/newline (the plan and the log are line-oriented) and no undecodable byte (surrogate).
+    return (all(part not in ('', '.', '..') for part in parts) and unit.isprintable()
+            and (len(parts) == 1 or (len(parts) <= 3 and bool(CLAUDE_DIR.match(parts[0])))))
+
+
+def _unit_of(rel):
+    """The unit a path below the root belongs to (or, for claude-<uid>[/<project>], the prefix of many units)."""
+    parts = rel.split('/')
+    return '/'.join(parts[:3]) if CLAUDE_DIR.match(parts[0]) else parts[0]
+
+
+def _holds_units(unit):
+    """claude-<uid> and claude-<uid>/<project> are not units but HOLD them. list_units never yields one as a
+    directory — a hand-edited plan could, and removing it would skip every per-session check below it."""
+    parts = unit.split('/')
+    return len(parts) < 3 and bool(CLAUDE_DIR.match(parts[0]))
+
+
+def _session(unit):
+    parts = unit.split('/')
+    return parts[2] if len(parts) == 3 and CLAUDE_DIR.match(parts[0]) else None
+
+
+def _project_name(cwd):
+    """claude-<uid>/<project>, like ~/.claude/projects/<project>, is the agent's cwd with every character that is
+    not a letter or a digit turned into '-' (checked: '/', '.' and '_' all are)."""
+    return re.sub(r'[^A-Za-z0-9]', '-', cwd)
+
+
+# ------------------------------------------------------------------ directory fds
+
+def _open_dir(name, dir_fd=None):
+    """A directory, and only a real one: O_NOFOLLOW turns a symlink planted in its place into an error."""
+    return os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0), dir_fd=dir_fd)
+
+
+def _open_parent(root_fd, unit):
+    """fd of the directory that holds the unit's last component; the caller closes it."""
+    fd = os.dup(root_fd)
+    for part in unit.split('/')[:-1]:
+        try:
+            below = _open_dir(part, fd)
+        finally:
+            os.close(fd)
+        fd = below
+    return fd
+
+
+def _names(fd):
+    """[(name, is_dir)], lstat semantics: a symlink to a directory is NOT a directory."""
+    with os.scandir(fd) as entries:
+        return sorted((entry.name, entry.is_dir(follow_symlinks=False)) for entry in entries)
+
+
+def list_units(root_fd):
+    units = []
+
+    def split(parent_fd, prefix, name, levels):
+        try:
+            fd = _open_dir(name, parent_fd)
+        except OSError:
+            units.append(prefix + name)   # unreadable: one unit, which the scan fails on => KEEP
+            return
+        try:
+            for child, is_dir in _names(fd):
+                if is_dir and levels > 1:
+                    split(fd, f'{prefix}{name}/', child, levels - 1)
+                else:
+                    units.append(f'{prefix}{name}/{child}')
+        finally:
+            os.close(fd)
+
+    for name, is_dir in _names(root_fd):
+        if is_dir and CLAUDE_DIR.match(name):
+            split(root_fd, '', name, 2)
+        else:
+            units.append(name)
+    return units
+
+
+# ------------------------------------------------------------------ scan
+
+class _Cut(Exception):
+    """The wall-clock budget ran out in the middle of a unit."""
+
+
+class _Acc:
+    def __init__(self, dev, inodes, deadline, clock):
+        self.dev, self.inodes, self.deadline, self.clock = dev, inodes or {}, deadline, clock
+        self.bytes = self.files = self.special = self.seen = 0
+        self.newest = 0.0
+        self.uids = set()
+        self.live = None
+
+    def tick(self):
+        if self.deadline is not None and self.clock() > self.deadline:
+            raise _Cut()
+
+    def add(self, st):
+        self.seen += 1
+        if not self.seen % 2048:
+            self.tick()
+        self.bytes += st.st_blocks * 512           # allocated, not apparent: what the tmpfs really holds
+        self.files += not stat.S_ISDIR(st.st_mode)
+        self.newest = max(self.newest, st.st_mtime, st.st_ctime)
+        self.uids.add(st.st_uid)
+        if not (stat.S_ISDIR(st.st_mode) or stat.S_ISREG(st.st_mode) or stat.S_ISLNK(st.st_mode)):
+            self.special += 1
+        if self.live is None and st.st_ino in self.inodes:
+            self.live = self.inodes[st.st_ino]
+
+
+def _walk(parent_fd, name, acc, depth):
+    fd = _open_dir(name, parent_fd)
+    try:
+        if os.fstat(fd).st_dev != acc.dev:
+            raise L.LanesError('mount point inside')
+        acc.tick()
+        below = []
+        with os.scandir(fd) as entries:   # entry.stat() is fstatat(fd, name, NOFOLLOW): fd must stay open
+            for entry in entries:
+                acc.add(entry.stat(follow_symlinks=False))
+                if entry.is_dir(follow_symlinks=False):
+                    below.append(entry.name)
+        # Recurse only after the iterator is closed: one fd per level, not two.
+        if below and depth >= MAX_DEPTH:
+            raise L.LanesError(f'deeper than {MAX_DEPTH} directories')
+        for child in below:
+            _walk(fd, child, acc, depth + 1)
+    finally:
+        os.close(fd)
+
+
+def scan_unit(root_fd, unit, dev, inodes=None, deadline=None, clock=time.monotonic):
+    """Walk one unit. Never raises: what could not be established becomes rec['error'] / rec['partial'] (=> KEEP)."""
+    acc = _Acc(dev, inodes, deadline, clock)
+    rec = {}
+    try:
+        parent = _open_parent(root_fd, unit)
+        try:
+            leaf = unit.split('/')[-1]
+            st = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+            rec['ino'], rec['dir'] = st.st_ino, stat.S_ISDIR(st.st_mode)
+            acc.add(st)
+            if st.st_dev != dev:
+                raise L.LanesError('mount point')
+            if stat.S_ISDIR(st.st_mode):
+                _walk(parent, leaf, acc, 1)
+        finally:
+            os.close(parent)
+    except _Cut:
+        rec['partial'] = True
+    except L.LanesError as error:
+        rec['error'] = str(error)
+    except OSError as error:
+        rec['error'] = error.strerror or str(error)
+    rec.update(bytes=acc.bytes, files=acc.files, newest=acc.newest, special=acc.special, uids=sorted(acc.uids))
+    if acc.live:
+        rec['live'] = acc.live
+    return rec
+
+
+# ------------------------------------------------------------------ who uses what
+
+def _boot_time(env):
+    try:
+        with open(f'{env.proc}/stat') as handle:
+            return next((int(line.split()[1]) for line in handle if line.startswith('btime ')), 0)
+    except (OSError, ValueError, IndexError):
+        return 0
+
+
+def _started(env, pid, btime):
+    """(comm, wall-clock start) from /proc/<pid>/stat: field 22 is the start in clock ticks since boot. What cannot
+    be read is start 0.0 — "older than every session" — so that the doubt KEEPs more, never less."""
+    try:
+        with open(f'{env.proc}/{pid}/stat') as handle:
+            text = handle.read()
+        comm, fields = text[text.index('(') + 1:text.rindex(')')], text[text.rindex(')') + 1:].split()
+        return comm, (btime + int(fields[19]) / TICKS) if btime else 0.0
+    except (OSError, ValueError, IndexError):
+        return '', 0.0
+
+
+def live_refs(env, pids, view, dev):
+    """One pass over the container's processes. paths: {unit or unit prefix: why}; inodes: {st_ino on `dev`: why};
+    projects: {a cwd as Claude spells a project: (earliest start of a process working there, why)}."""
+    paths, inodes, projects, unreadable = {}, {}, {}, 0
+    prefix = view.rstrip('/') + '/'
+    btime = _boot_time(env)
+
+    def by_path(text, why):
+        if text.endswith(' (deleted)'):
+            text = text[:-10]
+        if text.startswith(prefix) and text[len(prefix):].strip('/'):
+            paths.setdefault(_unit_of(text[len(prefix):].strip('/')), why)
+
+    def link(path, why):
+        try:
+            text = os.readlink(path)
+        except OSError:
+            return None
+        if not text.startswith('/'):
+            return None                              # socket:[…], pipe:[…], anon_inode:…
+        by_path(text, why)
+        if text.startswith(('/dev/', '/proc/', '/sys/')):
+            return text
+        try:
+            st = os.stat(path)                       # through the magic link: the file itself, whatever its path
+        except OSError:
+            return text
+        if st.st_dev == dev:
+            inodes.setdefault(st.st_ino, why)
+        return text
+
+    for pid in pids:
+        base = f'{env.proc}/{pid}'
+        for kind in ('cwd', 'root', 'exe'):
+            text = link(f'{base}/{kind}', f'pid {pid} {kind}')
+            if kind == 'cwd' and text:
+                # An agent holds NOTHING under its session directory while it idles — no cwd, no fd (checked) —
+                # but it keeps the cwd its project is named after.
+                comm, start = _started(env, pid, btime)
+                project = _project_name(text[:-10] if text.endswith(' (deleted)') else text)
+                if comm not in LANE_FIXTURES and (project not in projects or start < projects[project][0]):
+                    projects[project] = (start, f'pid {pid} ({comm or "?"})')
+        try:
+            for fd in os.listdir(f'{base}/fd'):
+                link(f'{base}/fd/{fd}', f'pid {pid} fd {fd}')
+        except PermissionError:
+            unreadable += 1                          # another uid: invisible without privilege — reported, not hidden
+        except OSError:
+            continue                                 # it exited
+        try:
+            with open(f'{base}/maps') as handle:
+                for line in handle:
+                    fields = line.rstrip('\n').split(None, 5)
+                    if len(fields) == 6 and fields[5].startswith('/'):
+                        by_path(fields[5], f'pid {pid} map')
+        except OSError:
+            pass
+    return {'paths': paths, 'inodes': inodes, 'projects': projects, 'pids': len(pids), 'unreadable': unreadable,
+            'at': env.clock()}
+
+
+def transcripts(home, sessions):
+    """{session: [transcript paths on the home volume]}; None = could not look (=> Claude sessions are KEEP). A home
+    without .claude/projects is "could not look" too: sessions exist, so their transcripts are kept somewhere else
+    (CLAUDE_CONFIG_DIR) and the 48 h rule would silently never apply."""
+    if not home or not os.path.isdir(home):   # unknown, or a volume path that is gone: NOT "no transcripts"
+        return None
+    found = {}
+    try:
+        with os.scandir(os.path.join(home, '.claude', 'projects')) as projects:
+            for project in projects:
+                if not project.is_dir(follow_symlinks=False):
+                    continue
+                try:
+                    with os.scandir(project.path) as files:
+                        for entry in files:
+                            if entry.name.endswith('.jsonl') and entry.name[:-6] in sessions:
+                                found.setdefault(entry.name[:-6], []).append(entry.path)
+                except OSError:
+                    return None
+    except OSError:
+        return None
+    return found
+
+
+def _ago(seconds):
+    seconds = max(0, int(seconds))
+    return f'{seconds // 86400}d' if seconds >= 2 * 86400 else f'{seconds // 3600}h' if seconds >= 3600 \
+        else f'{seconds // 60}m'
+
+
+def classify(unit, rec, live, scripts, now, idle=FRESH, uid=L.CONTAINER_UID):
+    """(KEEP|STALE, reason). Every doubt is a KEEP; STALE is what is left when nothing speaks for the unit."""
+    if _sacred(unit):
+        return KEEP, 'sacred name'
+    if not _safe_name(unit):
+        return KEEP, 'unsafe name'
+    if rec.get('error'):
+        return KEEP, f"scan failed: {rec['error']}"
+    if rec.get('partial'):
+        return KEEP, 'scan cut by the budget (plan again with --fresh and a larger --budget)'
+    if rec.get('dir') and _holds_units(unit):
+        return KEEP, 'holds units, is not one'
+    parts = unit.split('/')
+    for depth in range(1, len(parts) + 1):
+        why = live['paths'].get('/'.join(parts[:depth]))
+        if why:
+            return KEEP, f'in use: {why}'
+    why = rec.get('live') or live['inodes'].get(rec.get('ino'))
+    if why:
+        return KEEP, f'in use: {why}'
+    if rec.get('special'):
+        return KEEP, f"holds {rec['special']} socket/fifo/device"
+    foreign = [owner for owner in rec.get('uids', []) if owner != uid]
+    if foreign:
+        return KEEP, 'owned by uid ' + ','.join(map(str, foreign))
+    if now - rec.get('newest', now) < idle:
+        return KEEP, f"changed {_ago(now - rec.get('newest', now))} ago"
+    session = _session(unit)
+    if session:
+        if scripts is None:
+            return KEEP, 'Claude session, transcripts unreadable'
+        written = 0
+        for path in scripts.get(session, []):
+            try:
+                written = max(written, os.lstat(path).st_mtime)
+            except OSError:
+                pass
+        if now - written < TRANSCRIPT_FRESH:
+            return KEEP, f'Claude transcript written {_ago(now - written)} ago'
+        # An agent that idles over a weekend fails every rule above while it is alive. Its session can only be one
+        # that was made or written to AFTER it started: that bound is what keeps a lane that has lived for months
+        # from protecting every session its project ever had.
+        start, why = live.get('projects', {}).get(parts[1], (None, None))
+        if why and max(rec.get('newest', 0), written) >= start - START_SLACK:
+            return KEEP, f'may belong to {why}, alive in this project' + (f' for {_ago(now - start)}' if start else '')
+        if not written:
+            return STALE, f"idle {_ago(now - rec['newest'])}, no transcript found"
+    return STALE, f"idle {_ago(now - rec['newest'])}"
+
+
+# ------------------------------------------------------------------ delete
+
+def _remove(parent_fd, name, dev, depth, holds_units=False):
+    st = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
+    if holds_units and stat.S_ISDIR(st.st_mode):
+        raise L.LanesError(f'{name} holds units, it is not one')
+    if not stat.S_ISDIR(st.st_mode):
+        if not (stat.S_ISREG(st.st_mode) or stat.S_ISLNK(st.st_mode)):
+            raise L.LanesError(f'special file appeared: {name}')
+        os.unlink(name, dir_fd=parent_fd)             # unlinkat: a symlink goes, its target is never looked at
+        return
+    if depth > MAX_DEPTH:
+        raise L.LanesError(f'deeper than {MAX_DEPTH} directories')
+    fd = _open_dir(name, parent_fd)
+    try:
+        opened = os.fstat(fd)
+        if opened.st_dev != dev or opened.st_ino != st.st_ino:
+            raise L.LanesError(f'not the directory that was judged (mount or swap): {name}')
+        with os.scandir(fd) as entries:
+            children = [entry.name for entry in entries]
+        for child in children:
+            _remove(fd, child, dev, depth + 1)
+    finally:
+        os.close(fd)
+    os.rmdir(name, dir_fd=parent_fd)
+
+
+def delete_unit(root_fd, unit, dev):
+    """Remove one unit bottom-up through directory fds. The last line of defence repeats the name rules."""
+    if _sacred(unit) or not _safe_name(unit):
+        raise L.LanesError(f'refusing to delete {unit!r}')
+    parent = _open_parent(root_fd, unit)
+    try:
+        _remove(parent, unit.split('/')[-1], dev, 1, _holds_units(unit))
+    finally:
+        os.close(parent)
+
+
+def _log(env, container, root, outcome, unit, rec, reason):
+    path = env.state / 'tmpscan' / 'deleted.log'
+    path.parent.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(env.now()))
+    fd = os.open(str(path), os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+    with os.fdopen(fd, 'a') as handle:
+        handle.write(f"{stamp} {container} {root.key} {outcome} bytes={rec.get('bytes', 0)} files={rec.get('files', 0)}"
+                     f' unit={unit} :: {reason}\n')
+
+
+def _sweep(env, container, pid, root, root_fd, dev, units, idle, home, delete, deadline=None):
+    """Judge each unit AGAIN, right now, and remove it only if it is still STALE."""
+    scripts = transcripts(home, {_session(unit) for unit in units} - {None})
+    refs, done = None, {'deleted': 0, 'bytes': 0, 'kept': 0, 'failed': 0}
+    for unit in units:
+        if deadline is not None and env.clock() > deadline:
+            print(f"  budget used up: {len(units) - done['deleted'] - done['kept'] - done['failed']} units left for the next run")
+            break
+        if refs is None or env.clock() - refs['at'] > REFS_MAX_AGE:
+            # cgroup_pids also re-proves that `pid` is still that docker container: a restart aborts the sweep.
+            refs = live_refs(env, G.cgroup_pids(env, pid), root.view, dev)
+        rec = scan_unit(root_fd, unit, dev, refs['inodes'])
+        verdict, reason = classify(unit, rec, refs, scripts, env.now(), idle, env.uid)
+        if verdict != STALE:
+            done['kept'] += 1
+            print(f'  kept    {unit}: {reason}')
+            if delete:
+                _log(env, container, root, 'kept', unit, rec, reason)
+            continue
+        if not delete:
+            done['deleted'] += 1
+            done['bytes'] += rec['bytes']
+            print(f"  would delete {_size(rec['bytes']):>10}  {unit}  ({reason})")
+            continue
+        try:
+            delete_unit(root_fd, unit, dev)
+        except (OSError, L.LanesError) as error:
+            done['failed'] += 1
+            print(f'  FAILED  {unit}: {error}')
+            _log(env, container, root, 'failed', unit, rec, str(error))
+            continue
+        done['deleted'] += 1
+        done['bytes'] += rec['bytes']
+        print(f"  deleted {_size(rec['bytes']):>10}  {unit}")
+        _log(env, container, root, 'deleted', unit, rec, reason)
+    return done
+
+
+# ------------------------------------------------------------------ resumable scan
+
+def _state_file(env, container, suffix):
+    return env.state / 'tmpscan' / f'{container}.{suffix}'
+
+
+def scan(env, pid, root, root_fd, dev, path, deadline, inodes, fresh=False):
+    """Scan the units the manifest at `path` does not hold yet, until the deadline. Returns the manifest."""
+    manifest = L.read_json(path) or {}
+    if (fresh or manifest.get('version') != 1 or not isinstance(manifest.get('units'), dict)
+            or manifest.get('pid') != pid or manifest.get('dev') != dev
+            or manifest.get('root') != root.key or manifest.get('complete')
+            or env.now() - manifest.get('started_at', 0) > PLAN_MAX_AGE):
+        manifest = {'version': 1, 'pid': pid, 'dev': dev, 'root': root.key, 'started_at': env.now(), 'units': {}}
+    units = list_units(root_fd)
+    present = set(units)
+    manifest['units'] = {unit: rec for unit, rec in manifest['units'].items() if unit in present}
+    manifest['resumed'] = len(manifest['units'])
+    scanned = 0
+    try:
+        for unit in units:
+            if unit in manifest['units']:
+                continue
+            if _sacred(unit):
+                manifest['units'][unit] = {'bytes': 0, 'files': 0, 'newest': 0, 'special': 0, 'uids': []}
+                continue
+            rec = scan_unit(root_fd, unit, dev, inodes, deadline, env.clock)
+            # The unit the deadline fell into is retried by the next run — unless it was this run's first: then it
+            # alone is larger than a whole budget, and recording it as cut (=> KEEP) is what lets the scan move on.
+            if rec.get('partial') and scanned:
+                break
+            manifest['units'][unit] = rec
+            scanned += 1
+            if rec.get('partial'):
+                break
+    finally:
+        manifest['complete'] = len(manifest['units']) == len(units)
+        manifest['left'] = len(units) - len(manifest['units'])
+        L.atomic_write(path, json.dumps(manifest) + '\n')
+    return manifest
+
+
+# ------------------------------------------------------------------ plan file
+
+def write_plan(path, container, pid, root, now, complete, rows):
+    lines = [f'# lanes tmp plan v1\tcontainer={container}\tpid={pid}\troot={root.key}\tat={int(now)}\tcomplete={int(complete)}',
+             '# verdict\tbytes\tfiles\tnewest\tunit\treason   (apply deletes STALE rows only; delete a row to spare it)']
+    for unit, rec, verdict, reason in rows:
+        shown = unit if _safe_name(unit) else repr(unit)   # never STALE, see classify: only ever read by a human
+        lines.append(f"{verdict}\t{rec['bytes']}\t{rec['files']}\t{int(rec['newest'])}\t{shown}\t{reason}")
+    L.atomic_write(path, '\n'.join(lines) + '\n')
+
+
+def read_plan(path):
+    try:
+        lines = Path(path).read_text().split('\n')
+    except OSError:
+        raise L.LanesError(f'no plan at {path}: run `lanes tmp plan` first')
+    if not lines[0].startswith('# lanes tmp plan v1\t'):
+        raise L.LanesError(f'{path} is not a lanes tmp plan')
+    header = dict(field.split('=', 1) for field in lines[0].split('\t')[1:] if '=' in field)
+    units = [fields[4] for fields in (line.split('\t') for line in lines[1:]) if len(fields) >= 5 and fields[0] == STALE]
+    return header, units
+
+
+# ------------------------------------------------------------------ commands
+
+def _size(count):
+    for unit in ('B', 'KiB', 'MiB', 'GiB'):
+        if count < 1024:
+            return f'{count:.0f} {unit}' if unit == 'B' else f'{count:.1f} {unit}'
+        count /= 1024
+    return f'{count:.1f} TiB'
+
+
+def _home(env, container):
+    """Host path of the container's /home/coder volume, as sync recorded it."""
+    for source in (L.read_json(env.state / 'containers.json', {}) or {},
+                   (L.read_json(env.state / 'registry.json', {}) or {}).get('containers') or {}):
+        if (source.get(container) or {}).get('home'):
+            return source[container]['home']
+    return ''
+
+
+def _used(root_fd):
+    vfs = os.fstatvfs(root_fd)
+    return (vfs.f_blocks - vfs.f_bfree) * vfs.f_frsize
+
+
+def _judge(env, manifest, live, home, idle):
+    """[(unit, rec, verdict, reason)], largest first."""
+    scripts = transcripts(home, {_session(unit) for unit in manifest['units']} - {None})
+    rows = [(unit, rec) + classify(unit, rec, live, scripts, env.now(), idle, env.uid) for unit, rec in manifest['units'].items()]
+    return sorted(rows, key=lambda row: (-row[1]['bytes'], row[0]))
+
+
+def _refs_note(live):
+    blind = f", {live['unreadable']} of another uid could not be read" if live['unreadable'] else ''
+    return f"{live['pids']} processes checked{blind}"
+
+
+def cmd_plan(env, container, opts, write=True):
+    pid = G.container_pid(env, container)
+    pids = G.cgroup_pids(env, pid)   # first: this is also the proof that `pid` still is that docker container
+    root = Root('tmp', f'{env.proc}/{pid}/root/tmp', '/tmp')
+    deadline = env.clock() + opts['budget']
+    root_fd = _open_dir(root.host)
+    try:
+        dev = os.fstat(root_fd).st_dev
+        live = live_refs(env, pids, root.view, dev)
+        manifest = scan(env, pid, root, root_fd, dev, _state_file(env, container, 'json'), deadline, live['inodes'],
+                        opts['fresh'])
+        rows = _judge(env, manifest, live, _home(env, container), FRESH)
+        used = _used(root_fd)
+    finally:
+        os.close(root_fd)
+    print(f"== {container}: /tmp holds {_size(used)} · {len(rows)} units ({manifest['resumed']} from the previous run)"
+          f' · {_refs_note(live)}')
+    print(f"{'':7}{'SIZE':>10} {'FILES':>8} {'IDLE':>5}  UNIT")
+    limit = len(rows) if opts['all'] else 40
+    for unit, rec, verdict, reason in rows[:limit]:
+        idle = _ago(env.now() - rec['newest']) if rec['newest'] else '-'
+        print(f"{verdict:7}{_size(rec['bytes']):>10} {rec['files']:>8} {idle:>5}  {unit if _safe_name(unit) else repr(unit)}"
+              f'  — {reason}')
+    if len(rows) > limit:
+        print(f'… {len(rows) - limit} smaller units (--all shows them; the plan file has every one)')
+    for verdict in (STALE, KEEP):
+        chosen = [rec for _unit, rec, which, _reason in rows if which == verdict]
+        print(f"{verdict:7}{_size(sum(rec['bytes'] for rec in chosen)):>10} in {len(chosen)} units")
+    if not manifest['complete']:
+        print(f"scan NOT complete: {manifest['left']} units left — run the same command again to continue")
+    if write:
+        path = _state_file(env, container, 'plan.tsv')
+        write_plan(path, container, pid, root, env.now(), manifest['complete'], rows)
+        print(f'plan: {path}\nreview it, then: lanes tmp apply {container} --approve')
+    return 0
+
+
+def cmd_apply(env, container, opts):
+    header, units = read_plan(_state_file(env, container, 'plan.tsv'))
+    pid = G.container_pid(env, container)
+    if header.get('container') != container or header.get('root') != 'tmp':
+        raise L.LanesError('the plan was made for another container or root')
+    if header.get('pid') != str(pid):
+        raise L.LanesError(f"the container's init pid changed since the plan ({header.get('pid')} -> {pid}): plan again")
+    if not header.get('at', '').isdigit() or env.now() - int(header['at']) > PLAN_MAX_AGE:
+        raise L.LanesError(f'the plan is older than {PLAN_MAX_AGE // 3600} h: plan again')
+    root = Root('tmp', f'{env.proc}/{pid}/root/tmp', '/tmp')
+    root_fd = _open_dir(root.host)
+    try:
+        dev, before = os.fstat(root_fd).st_dev, _used(root_fd)
+        print(f"== {container}: {len(units)} STALE units in the plan"
+              + ('' if opts['approve'] else ' — DRY-RUN (add --approve to delete)'))
+        done = _sweep(env, container, pid, root, root_fd, dev, units, FRESH, _home(env, container), opts['approve'])
+        after = _used(root_fd)
+    finally:
+        os.close(root_fd)
+    print(f"{'deleted' if opts['approve'] else 'would delete'} {done['deleted']} units, {_size(done['bytes'])}"
+          f" · kept {done['kept']} that are no longer stale · failed {done['failed']}"
+          f' · /tmp used {_size(before)} -> {_size(after)}')
+    return 1 if done['failed'] else 0
+
+
+def _is_cache(fd):
+    try:   # A virtualenv tags itself as a cache too (so that backups skip it), but it is an ENVIRONMENT: removing it
+        # breaks the checkout until someone recreates it (2026-09-20: two idle .venv went with the cargo targets).
+        os.stat('pyvenv.cfg', dir_fd=fd, follow_symlinks=False)
+        return False
+    except OSError:
+        pass
+    try:
+        tag = os.open('CACHEDIR.TAG', os.O_RDONLY | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0), dir_fd=fd)
+    except OSError:
+        return False
+    try:
+        return os.read(tag, len(CACHE_TAG)) == CACHE_TAG
+    finally:
+        os.close(tag)
+
+
+# The home volume is millions of directories: never walk into dependency trees, VCS data or tool homes, and stop at a
+# depth where build outputs of a worktree (…/<worktrees>/<name>/<crate>/target) are still reached.
+HOME_PRUNE = frozenset(['node_modules', '.git', '.cargo', '.rustup', '.npm', '.cache', '.local', '.claude', '.codex',
+                        '.lz', '.tmp', '.pnpm-store', 'site-packages'])
+HOME_DEPTH = 8
+HOME_BUDGET = 1200              # s: even pruned, the home volume is a long walk (measured: minutes at nice 19)
+HOME_EVERY = 20 * 3600          # the hourly reaper walks it once a day
+
+
+def find_caches(root_fd, dev, deadline=None, clock=time.monotonic, prune=frozenset(), max_depth=MAX_DEPTH):
+    """Relative paths of the self-declared cache directories below the root. Directory fds only, no symlink is
+    followed, the device is never left, a cache is never entered, sacred top-level names are never opened."""
+    found = []
+
+    def below(fd, rel, depth):
+        if deadline is not None and clock() > deadline:
+            raise _Cut()
+        if rel and _is_cache(fd):
+            found.append(rel)
+            return
+        if depth >= max_depth:
+            return
+        for name, is_dir in _names(fd):
+            if not is_dir or name in prune or (not rel and _sacred(name)):
+                continue
+            try:
+                child = _open_dir(name, fd)
+            except OSError:
+                continue
+            try:
+                if os.fstat(child).st_dev == dev:
+                    below(child, f'{rel}/{name}' if rel else name, depth + 1)
+            finally:
+                os.close(child)
+
+    try:
+        below(root_fd, '', 0)
+    except _Cut:
+        pass                                          # what was found so far is still true
+    return found
+
+
+def judge_cache(env, root_fd, rel, dev, inodes, idle=CACHE_IDLE):
+    """-> (record, reason to KEEP or None). Same evidence as a unit: open files / cwds by inode, owner, specials, age."""
+    rec = scan_unit(root_fd, rel, dev, inodes)
+    if rec.get('error') or rec.get('partial'):
+        return rec, rec.get('error') or 'could not be walked completely'
+    if rec.get('live'):
+        return rec, f"in use: {rec['live']}"
+    if rec['special']:
+        return rec, 'holds a socket, fifo or device'
+    if set(rec['uids']) - {env.uid}:
+        return rec, 'not owned by the container user alone'
+    if env.now() - rec['newest'] < idle:
+        return rec, f"written {_ago(env.now() - rec['newest'])} ago"
+    return rec, None
+
+
+def _delete_cache(root_fd, rel, dev):
+    # A cache sits at any depth (…/<session>/scratchpad/target), so _safe_name's unit shape does not apply; its other
+    # rules do: no empty / '.' / '..' component, printable, nothing under a sacred top-level name, never the root.
+    parts = rel.split('/')
+    if not rel or any(part in ('', '.', '..') for part in parts) or not rel.isprintable() or _sacred(parts[0]):
+        raise L.LanesError(f'refusing to delete {rel!r}')
+    parent = _open_parent(root_fd, rel)
+    try:
+        leaf_fd = _open_dir(rel.split('/')[-1], parent)
+        try:
+            if not _is_cache(leaf_fd):                # the tag went away since it was judged: not a cache any more
+                raise L.LanesError('no valid CACHEDIR.TAG any more')
+        finally:
+            os.close(leaf_fd)
+        _remove(parent, rel.split('/')[-1], dev, 1)
+    finally:
+        os.close(parent)
+
+
+def sweep_caches(env, container, pid, root, root_fd, dev, delete, deadline, idle=CACHE_IDLE, prune=frozenset(),
+                 max_depth=MAX_DEPTH):
+    """List (and with delete=True remove) idle build caches. Every cache is judged with references taken just before."""
+    done = {'deleted': 0, 'bytes': 0, 'kept': 0, 'failed': 0}
+    refs, taken = None, 0.0
+    for rel in find_caches(root_fd, dev, deadline, env.clock, prune, max_depth):
+        if deadline is not None and env.clock() > deadline:
+            print('  budget used up: the remaining caches wait for the next run')
+            break
+        if refs is None or env.clock() - taken > REFS_MAX_AGE:
+            refs, taken = live_refs(env, G.cgroup_pids(env, pid), root.view, dev), env.clock()
+        rec, keep = judge_cache(env, root_fd, rel, dev, refs['inodes'], idle)
+        if keep:
+            done['kept'] += 1
+            print(f"  KEEP   {_size(rec.get('bytes', 0)):>9}  {root.view}/{rel}  ({keep})")
+            continue
+        if delete:
+            try:
+                _delete_cache(root_fd, rel, dev)
+            except (L.LanesError, OSError) as error:
+                done['failed'] += 1
+                _log(env, container, root, 'FAILED-cache', rel, rec, str(error))
+                print(f'  FAILED {root.view}/{rel}: {error}')
+                continue
+            _log(env, container, root, 'deleted-cache', rel, rec, f'idle build cache (CACHEDIR.TAG), {_ago(env.now() - rec["newest"])}')
+        done['deleted'] += 1
+        done['bytes'] += rec['bytes']
+        print(f"  {'DELETE' if delete else 'IDLE  '} {_size(rec['bytes']):>9}  {root.view}/{rel}  (idle {_ago(env.now() - rec['newest'])})")
+    return done
+
+
+def _home_root(env, container):
+    home = _home(env, container)
+    return Root('home', home, L.CONTAINER_HOME) if home else None
+
+
+def cmd_caches(env, container, opts):
+    """`lanes tmp caches [--home] [--approve]`: idle, unreferenced, self-declared build caches in the container's /tmp,
+    or with --home on its home volume (cargo `target` dirs of idle worktrees: 938 GiB on 2026-09-20), idle > 3 days."""
+    pid = G.container_pid(env, container)
+    G.cgroup_dir(env, pid)
+    if opts.get('home'):
+        root, idle, prune, depth = _home_root(env, container), REAP_IDLE, HOME_PRUNE, HOME_DEPTH
+        if root is None:
+            raise L.LanesError(f'{container}: home volume unknown — run `lanes sync`')
+    else:
+        root, idle, prune, depth = Root('tmp', f'{env.proc}/{pid}/root/tmp', '/tmp'), CACHE_IDLE, frozenset(), MAX_DEPTH
+    root_fd = _open_dir(root.host)
+    try:
+        dev = os.fstat(root_fd).st_dev
+        budget = max(opts['budget'], HOME_BUDGET) if opts.get('home') else opts['budget']
+        done = sweep_caches(env, container, pid, root, root_fd, dev, opts['approve'], env.clock() + budget,
+                            idle, prune, depth)
+    finally:
+        os.close(root_fd)
+    verb = 'deleted' if opts['approve'] else 'idle, deletable with --approve:'
+    print(f"== {container} {root.view}: {verb} {done['deleted']} caches, {_size(done['bytes'])}; kept {done['kept']}")
+    return 1 if done['failed'] else 0
+
+
+def cmd_reap(env, container, opts):
+    pid = G.container_pid(env, container)
+    G.cgroup_dir(env, pid)
+    armed = (env.state / 'flags' / 'tmpreap.armed').exists()
+    home = _home(env, container)
+    deadline = env.clock() + opts['budget']
+    roots = [Root('tmp', f'{env.proc}/{pid}/root/tmp', '/tmp')]
+    if home:   # the disk temp dir container/env.sh points TMPDIR at: it has no reboot to empty it
+        roots.append(Root('home-tmp', os.path.join(home, '.tmp'), L.CONTAINER_HOME + '/.tmp'))
+    failed = 0
+    for root in roots:
+        try:
+            root_fd = _open_dir(root.host)
+        except FileNotFoundError:
+            continue
+        try:
+            dev = os.fstat(root_fd).st_dev
+            live = live_refs(env, G.cgroup_pids(env, pid), root.view, dev)
+            manifest = scan(env, pid, root, root_fd, dev, _state_file(env, container, f'reap-{root.key}.json'),
+                            deadline, live['inodes'])
+            stale = [unit for unit, _rec, verdict, _reason in _judge(env, manifest, live, home, REAP_IDLE)
+                     if verdict == STALE]
+            print(f"== {container} {root.view}: {len(manifest['units'])} units scanned, {manifest['left']} left,"
+                  f" {len(stale)} idle > {REAP_IDLE // 86400} d · {_refs_note(live)}"
+                  + ('' if armed else ' — DRY-RUN (touch flags/tmpreap.armed to arm)'))
+            done = _sweep(env, container, pid, root, root_fd, dev, stale, REAP_IDLE, home, armed, deadline)
+            failed += done['failed']
+            print(f"   {'deleted' if armed else 'would delete'} {done['deleted']} units, {_size(done['bytes'])}")
+            cached = sweep_caches(env, container, pid, root, root_fd, dev, armed, deadline)
+            failed += cached['failed']
+            print(f"   {'deleted' if armed else 'would delete'} {cached['deleted']} idle build caches, {_size(cached['bytes'])}")
+        finally:
+            os.close(root_fd)
+    disk = _home_root(env, container)
+    stamp = _state_file(env, container, 'home-sweep')
+    try:
+        due = opts['fresh'] or env.now() - os.stat(stamp).st_mtime > HOME_EVERY
+    except OSError:
+        due = True
+    if disk and due:   # the DISK fills the same way the RAM did: every idle worktree keeps gigabytes of cargo `target`
+        try:
+            root_fd = _open_dir(disk.host)
+        except OSError:
+            root_fd = None
+        if root_fd is not None:
+            try:
+                cached = sweep_caches(env, container, pid, disk, root_fd, os.fstat(root_fd).st_dev, armed,
+                                      env.clock() + max(opts['budget'], HOME_BUDGET), REAP_IDLE, HOME_PRUNE, HOME_DEPTH)
+                L.atomic_write(stamp, f'{env.now()}\n')
+                failed += cached['failed']
+                print(f"== {container} {disk.view}: {'deleted' if armed else 'would delete'} {cached['deleted']} build caches"
+                      f" idle > {REAP_IDLE // 86400} d, {_size(cached['bytes'])}")
+            finally:
+                os.close(root_fd)
+    return 1 if failed else 0
+
+
+def main(args, env):
+    usage = 'usage: lanes tmp scan|plan|apply|reap|caches [container…] [--budget S] [--fresh] [--all] [--home] [--approve]'
+    opts = {'budget': BUDGET, 'fresh': False, 'all': False, 'approve': False, 'home': False}
+    words, rest = [], list(args)
+    while rest:
+        arg = rest.pop(0)
+        if arg in ('--fresh', '--all', '--approve', '--home'):
+            opts[arg[2:]] = True
+        elif arg == '--budget' or arg.startswith('--budget='):
+            value = arg.partition('=')[2] or (rest.pop(0) if rest else '')
+            if not value.isdigit():
+                raise L.LanesError(usage)
+            opts['budget'] = int(value)
+        elif arg.startswith('-'):
+            raise L.LanesError(usage)
+        else:
+            words.append(arg)
+    if not words or words[0] not in ('scan', 'plan', 'apply', 'reap', 'caches'):
+        raise L.LanesError(usage)
+    code = 0
+    for container in words[1:] or G.container_names(env):
+        try:
+            if words[0] == 'apply':
+                code |= cmd_apply(env, container, opts)
+            elif words[0] == 'reap':
+                code |= cmd_reap(env, container, opts)
+            elif words[0] == 'caches':
+                code |= cmd_caches(env, container, opts)
+            else:
+                code |= cmd_plan(env, container, opts, write=words[0] == 'plan')
+        except (L.LanesError, OSError) as error:
+            # One container that is down (or a /tmp we may not open) must not hide the others.
+            print(f'lanes tmp {words[0]}: {container}: {error}')
+            code = 1
+    return code
+
+
+def run(args):
+    try:
+        os.nice(19)
+    except OSError:
+        pass
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(143))   # so that the manifest's `finally` still saves
+    return main(args, G.Env())
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(run(sys.argv[1:]))
+    except L.LanesError as error:
+        sys.exit(f'lanes tmp: {error}')