@vibelord/lanes 1.0.0

package/payload/lanes/libexec/cursor_commit.py

@@ -0,0 +1,159 @@
+"""lanes cursor-commit — commit the `lanes cursor-sync` normalization of `.vscode/terminals.json` on top of each
+repository's REMOTE branch tip and push it, without touching any working tree or index.
+
+Why not `git commit && git push` in the repo roots: the roots are long-lived, dirty checkouts (hundreds of modified
+files) that sit far behind their remotes, so a normal push is rejected and a pull is out of the question. Instead,
+inside the container, per repository:  fetch the target branch -> build the new tree from the remote tip with ONE
+path replaced (temporary index, `git update-index --cacheinfo`, `git write-tree`) -> `git commit-tree` -> push that
+exact commit to the branch (a fast-forward by construction; a concurrent push simply makes it fail, never force).
+
+Content rule: if the remote's blob equals the root's HEAD blob, the root's current (normalized) file is committed;
+otherwise the REMOTE's version is normalized by terminal name, so upstream edits are never overwritten by a stale root.
+
+Dry-run by default; `--push` performs the pushes. A branch that refuses direct pushes (repository rules) gets the
+commit on a `lanes/terminals-lane-open` branch and a pull request against the target branch instead.
+"""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import cursor_sync
+import lanes_lib as L
+
+MESSAGE = """chore(terminals): open lanes through the uniform `lane open` entry point
+
+Each terminal's command becomes `exec /home/coder/.lz/bin/lane open <lane-id>`: attach to the lane; if it does
+not exist, run its recorded create recipe; never nest inside tmux; holder-agnostic. The original commands and the
+exact tmux bindings are kept in a top-level `lanes` block. Names, icons, colors, order and the `throttle` block
+are unchanged.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+"""
+FILE = '.vscode/terminals.json'
+PUSH = '''
+slug=$(git remote get-url origin | sed -E 's#(git@github.com:|https://([^@]*@)?github.com/)##; s#\\.git$##')
+hooks=$(git config core.hooksPath || true); hooks=${hooks:-$(cd "$(git rev-parse --git-path hooks)" && pwd)}
+push_dir=$PWD
+if [ -x "$hooks/pre-push" ]; then
+  # The repository gates pushes. Its gate inspects the CHECKOUT it runs in, and the root checkout is a stale, dirty
+  # tree: push from a clean temporary worktree of exactly this commit, so the gate checks what is being pushed.
+  push_dir=/home/coder/.lz/commit-staging/wt-BOARD
+  git worktree remove --force "$push_dir" >/dev/null 2>&1 || rm -rf "$push_dir"; git worktree prune
+  git worktree add -q --detach "$push_dir" $commit
+  echo "pre-push gate present: pushing from a clean worktree of the commit"
+  # In a linked worktree `.git` is a file, so Go's VCS stamping walks up to the next `.git` DIRECTORY (here a broken
+  # /home/coder/.git) and every `go list` dies with "error obtaining VCS status". Stamping is irrelevant to a gate run.
+  if command -v go >/dev/null 2>&1; then GOFLAGS="$(go env GOFLAGS) -buildvcs=false"; export GOFLAGS; fi
+fi
+do_push() { (cd "$push_dir" && timeout -k 10 3300 git push "$@" 2>&1); }
+open_pr() {
+  if out=$(do_push -f origin $commit:refs/heads/lanes/terminals-lane-open); then
+    gh pr create --repo "$slug" --base BRANCH --head lanes/terminals-lane-open \
+      --title "chore(terminals): open lanes through the uniform lane open entry point" \
+      --body-file /home/coder/.lz/commit-staging/BOARD.pr 2>&1 </dev/null | tail -1
+  else echo "PUSH FAILED (rc=$?)"; echo "$out" | tail -15; fi
+}
+# (gh prints the error body on stdout when the rules API is unavailable for the repository: trust the exit status)
+needs_pr=$(gh api "repos/$slug/rules/branches/BRANCH" --jq '[.[].type]|index("pull_request")' 2>/dev/null </dev/null) || needs_pr=
+case "$needs_pr" in
+  ''|null)
+    if out=$(do_push origin $commit:refs/heads/BRANCH); then echo "PUSHED to BRANCH"
+    elif echo "$out" | grep -q -i -E "rule violations|protected branch|GH006|GH013"; then echo "$out" | tail -2; open_pr
+    else echo "PUSH FAILED"; echo "$out" | tail -15; fi ;;
+  *) echo "BRANCH requires pull requests (repository rules)"; open_pr ;;
+esac
+[ "$push_dir" = "$PWD" ] || { git worktree remove --force "$push_dir" >/dev/null 2>&1; git worktree prune; }
+'''
+def site():
+    """SITE data: which repository/branch each board's registry is committed to, and the commit author.
+    <workspaces dir>/commit-targets.json = {"author": {"name", "email"}, "targets": {board: {"container", "folder",
+    "branch", "options": ["remote-only"]}}, "skip": {board: reason}}.  `remote-only`: never publish lanes that exist
+    only in the root checkout (normalize the committed version instead)."""
+    path = L.workspaces_dir() / 'commit-targets.json'
+    if not path.exists():
+        raise L.LanesError(f'{path} not found: list the boards to commit there (see workspaces.example/)')
+    return L.read_site_json(path)
+
+
+def in_container(container, script, check=True, timeout=600):
+    result = subprocess.run(['docker', 'exec', '-i', '-u', 'coder', container, 'bash', '-ls'], input=script,
+                            capture_output=True, text=True, timeout=timeout)
+    if check and result.returncode:
+        raise L.LanesError(f'{container}: {result.stderr.strip()[-400:]}')
+    return result
+
+
+def run(args):
+    push = '--push' in args
+    only = [a for a in args if not a.startswith('--')]
+    registry = L.load_registry()
+    data = site()
+    author = (data['author']['name'], data['author']['email'])
+    for board, target in data['targets'].items():
+        if only and board not in only:
+            continue
+        container, folder, branch, options = target['container'], target['folder'], target['branch'], target.get('options', [])
+        workspace = next(w for w in registry['workspaces'] if w['id'] == board)
+        home = Path(registry['containers'][container]['home'])
+        root_file = home / folder[len('/home/coder/'):] / FILE
+        facts = in_container(container, f'''
+cd {folder} && git fetch -q origin {branch} || exit 9
+echo "REMOTE $(git rev-parse -q --verify origin/{branch}:{FILE} || echo absent)"
+echo "HEAD $(git rev-parse -q --verify HEAD:{FILE} || echo absent)"
+echo "TIP $(git rev-parse origin/{branch})"
+''').stdout
+        info = dict(line.split(' ', 1) for line in facts.strip().splitlines())
+        remote_text = '' if info['REMOTE'] == 'absent' else in_container(container, f'cd {folder} && git show origin/{branch}:{FILE}').stdout
+        if (info['REMOTE'] == info['HEAD'] and 'remote-only' not in options) or info['REMOTE'] == 'absent':
+            desired, how = root_file.read_text(), 'root file (remote blob == root HEAD blob)' if info['REMOTE'] != 'absent' else 'root file (new on remote)'
+        else:
+            lanes = {(lane.get('registry_name') or lane['name']): lane for lane in workspace['lanes']}
+            desired, how = cursor_sync.normalized_text(remote_text, lanes), "remote version normalized (remote differs from the stale root)"
+        wanted = [t.get('name') for t in json.loads(desired).get('terminals', [])]
+        had = [t.get('name') for t in json.loads(remote_text).get('terminals', [])] if remote_text else []
+        added = [n for n in wanted if n not in had]
+        message = MESSAGE
+        if remote_text and 'remote-only' not in options and (added or info['REMOTE'] == info['HEAD']):
+            note = ('This also records the board as it runs today' +
+                    (': lanes added locally since the last commit: ' + ', '.join(added) + '.' if added else
+                     ' (bindings edited locally since the last commit).'))
+            if added or desired.count('"command"') and json.loads(remote_text) != json.loads(root_file.read_text()):
+                message = MESSAGE.replace('\nCo-Authored-By', note + '\n\nCo-Authored-By')
+        elif not remote_text:
+            message = MESSAGE.replace('\nCo-Authored-By', 'The file was not tracked before: this adds the board registry.\n\nCo-Authored-By')
+        staging = home / '.lz' / 'commit-staging'
+        staging.mkdir(parents=True, exist_ok=True)
+        (staging / f'{board}.json').write_text(desired)
+        (staging / f'{board}.msg').write_text(message)
+        (staging / f'{board}.pr').write_text(
+            'Cursor / VS Code terminals now reach their lane through one uniform, attach-first entry point.\n\n' +
+            message.split('\n', 2)[2].replace('Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>\n', '') +
+            '\nOne file changed: `.vscode/terminals.json`. No code, build or UI changes.\n\n'
+            '🤖 Generated with [Claude Code](https://claude.com/claude-code)\n')
+        script = f'''
+set -e
+cd {folder}
+export GIT_INDEX_FILE=/home/coder/.lz/commit-staging/{board}.index
+rm -f "$GIT_INDEX_FILE"
+git read-tree origin/{branch}
+blob=$(git hash-object -w /home/coder/.lz/commit-staging/{board}.json)
+git update-index --add --cacheinfo 100644,$blob,{FILE}
+tree=$(git write-tree)
+rm -f "$GIT_INDEX_FILE"
+unset GIT_INDEX_FILE   # must not leak into `git worktree add` / the pre-push gate (a worktree without its own index looks all-untracked)
+if [ "$tree" = "$(git rev-parse origin/{branch}^{{tree}})" ]; then echo "NOCHANGE"; exit 0; fi
+commit=$(GIT_AUTHOR_NAME="{author[0]}" GIT_AUTHOR_EMAIL="{author[1]}" GIT_COMMITTER_NAME="{author[0]}" GIT_COMMITTER_EMAIL="{author[1]}" \\
+    git commit-tree $tree -p origin/{branch} -F /home/coder/.lz/commit-staging/{board}.msg)
+echo "COMMIT $commit"
+git diff --stat origin/{branch} $commit | tail -2
+{PUSH.replace('BRANCH', branch).replace('BOARD', board) if push else 'echo "DRY-RUN: not pushed"'}
+'''
+        try:
+            # a repository's pre-push gate (lint + tests) may run for a long while; the in-container `timeout` ends first
+            result = in_container(container, script, check=False, timeout=3600)
+            out = (result.stdout + result.stderr).strip().replace('\n', '\n      ')
+        except subprocess.TimeoutExpired:
+            out = 'TIMED OUT after 3600 s — not pushed'
+        print(f'== {board} -> {branch}  [{how}]\n      {out}', flush=True)
+    return 0

package/payload/lanes/libexec/cursor_sync.py

@@ -0,0 +1,166 @@
+"""lanes cursor-sync — make Cursor / VS Code (Terminals Manager) open exactly the lanes of the lanes view.
+
+The repository's `.vscode/terminals.json` stays the source of truth for WHICH lanes exist and how they look
+(name, icon, color, description, order). This tool only normalizes HOW a terminal reaches its lane:
+
+  * every terminal's `command` becomes the uniform, holder-agnostic entry point
+        exec /home/coder/.lz/bin/lane open <lane-id>
+    (attach; if the lane does not exist, run its recorded create recipe; never nest; ignore-size while the lanes
+    view shows the lane);
+  * the ORIGINAL command and the exact binding are preserved next to it in a top-level `lanes` block, which the
+    extension and Throttle ignore:  lanes.terminals[<name>] = {id, holder, tmux{socketName,sessionName}, create}.
+
+Text is edited minimally (command strings replaced in place, the `lanes` block inserted before the final brace) so
+git diffs stay small. Dry-run by default: prints a unified diff. `--write` applies (with a timestamped backup).
+Boards whose registry lives outside a repository are additionally PROJECTED into the file Cursor
+reads for that folder, named by `"cursor": "<path>"` on the repository entry of the workspace manifest.
+"""
+import difflib
+import json
+import re
+import time
+from pathlib import Path
+
+import lanes_lib as L
+
+ENTRY = 'exec /home/coder/.lz/bin/lane open '
+
+
+def _indent_of(text):
+    match = re.search(r'\n([ \t]+)"', text)
+    return match.group(1) if match else '  '
+
+
+def normalized_text(text, lanes_by_name):
+    """Return the file text with uniform commands + the `lanes` block. Minimal textual edits when possible."""
+    data = json.loads(text)
+    block = {'version': 1, 'terminals': {}}
+    commands = {}
+    for term in data.get('terminals', []):
+        lane = lanes_by_name.get(term.get('name'))
+        if not lane:
+            continue
+        previous = ((data.get('lanes') or {}).get('terminals') or {}).get(term['name']) or {}
+        create = previous.get('create') if L.LANE_OPEN in (term.get('command') or '') else term.get('command')
+        entry = {'id': lane['id'], 'holder': lane['holder']}
+        if lane.get('tmux'):
+            entry['tmux'] = {'socketName': lane['tmux']['socket'], 'sessionName': lane['tmux']['session']}
+        if create:
+            entry['create'] = create
+        block['terminals'][term['name']] = entry
+        commands[term['name']] = ENTRY + lane['id']
+    # Nothing to do: leave the file byte-identical (never reformat somebody else's JSON).
+    if (data.get('lanes') == block and
+            all(term.get('command') == commands.get(term.get('name'), term.get('command')) for term in data.get('terminals', []))):
+        return text
+    # Minimal textual edits: swap command string literals in place; append (or replace) the trailing `lanes` block.
+    out, minimal = text, True
+    for term in data.get('terminals', []):
+        target = commands.get(term.get('name'))
+        current = term.get('command')
+        if target is None or current == target:
+            continue
+        literal = '"command": ' + json.dumps(current, ensure_ascii=False)
+        escaped = '"command": ' + json.dumps(current)            # the file may use \uXXXX escapes
+        found = literal if out.count(literal) == 1 else escaped if out.count(escaped) == 1 else None
+        if current is None or found is None:
+            minimal = False
+            break
+        out = out.replace(found, '"command": ' + json.dumps(target, ensure_ascii=False))
+    if minimal and 'lanes' in data:
+        # Our block is the last key we appended: cut it off textually, otherwise fall back to re-serializing.
+        start = out.rfind('"lanes":')
+        head = out[:start].rstrip()
+        if start > 0 and head.endswith(',') and list(data.keys())[-1] == 'lanes':
+            out = head[:-1].rstrip() + '\n}' + ('\n' if text.endswith('\n') else '')
+            try:
+                json.loads(out)
+            except ValueError:
+                minimal = False
+        else:
+            minimal = False
+    if minimal:
+        indent = _indent_of(text)
+        rendered = json.dumps(block, ensure_ascii=False, indent=len(indent) if indent.strip() == '' and indent else 2)
+        rendered = ('\n' + indent).join(rendered.splitlines())
+        end = out.rstrip().rfind('}')
+        body = out[:end].rstrip()
+        out = body + (',' if not body.endswith('{') else '') + '\n' + indent + '"lanes": ' + rendered + '\n}' + \
+            ('\n' if text.endswith('\n') else '')
+        if json.loads(out).get('lanes') == block:
+            return out
+    for term in data.get('terminals', []):
+        if term.get('name') in commands:
+            term['command'] = commands[term['name']]
+    data['lanes'] = block
+    return json.dumps(data, ensure_ascii=False, indent=2) + ('\n' if text.endswith('\n') else '')
+
+
+def projected_text(source_text, source_path):
+    """A Cursor-facing copy of an out-of-repo board registry: the same document (terminals, uniform commands, the
+    throttle and lanes binding blocks other tools may read) plus a note saying where the original lives."""
+    data = json.loads(source_text)
+    note = {'//': f'Generated by `lanes cursor-sync` from {source_path}. Edit that registry, not this file.'}
+    return json.dumps({**note, **data}, ensure_ascii=False, indent=2) + '\n'
+
+
+def plan(registry, only=()):
+    """Yield (workspace id, host path, container path, old text, new text, note)."""
+    catalog = L.read_site_json(L.workspaces_dir() / 'catalog.json')['workspaces']
+    containers = registry['containers']
+    for item in catalog:
+        if only and item['id'] not in only:
+            continue
+        workspace = next((w for w in registry['workspaces'] if w['id'] == item['id']), None)
+        manifest = L.read_site_json(L.workspaces_dir() / item['manifest'])
+        if not workspace or workspace.get('errors'):
+            yield item['id'], None, None, '', '', 'skipped: registry errors — fix them first'
+            continue
+        for repo in manifest.get('repositories') or []:
+            info = containers.get(repo['host']) or {}
+            lanes = {(lane.get('registry_name') or lane['name']): lane for lane in workspace['lanes'] if lane.get('repo') == repo['id']}
+            prefix = repo.get('prefix') or ''
+            lanes = {name[len(prefix):] if prefix and name.startswith(prefix) else name: lane for name, lane in lanes.items()}
+            host_file = L.host_path(info, repo['registry'])
+            old = host_file.read_text()
+            new = normalized_text(old, lanes)
+            yield item['id'], host_file, repo['registry'], old, new, 'registry'
+            if repo.get('cursor'):
+                target = L.host_path(info, repo['cursor'])
+                current = target.read_text() if target.exists() else ''
+                yield item['id'], target, repo['cursor'], current, projected_text(new, repo['registry']), 'projection for Cursor (git-tracked file)'
+
+
+def run(args):
+    write = '--write' in args
+    only = [a for a in args if not a.startswith('--')]
+    registry = L.load_registry()
+    changed = 0
+    for workspace, host_file, container_path, old, new, note in plan(registry, only):
+        if host_file is None:
+            print(f'== {workspace}: {note}')
+            continue
+        if old == new:
+            print(f'== {workspace}: {container_path} — already normalized ({note})')
+            continue
+        changed += 1
+        diff = list(difflib.unified_diff(old.splitlines(), new.splitlines(), 'a' + container_path, 'b' + container_path, lineterm='', n=1))
+        adds = sum(1 for line in diff if line.startswith('+') and not line.startswith('+++'))
+        dels = sum(1 for line in diff if line.startswith('-') and not line.startswith('---'))
+        print(f'== {workspace}: {container_path} — {note}: +{adds} -{dels}')
+        if '--diff' in args or not write:
+            limit = None if '--diff' in args else 14
+            for line in diff[:limit]:
+                print('   ' + line[:200])
+            if limit and len(diff) > limit:
+                print(f'   … {len(diff) - limit} more diff lines (use --diff)')
+        if write:
+            backup_dir = L.STATE / 'cursor-sync-backups' / time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())
+            backup_dir.mkdir(parents=True, exist_ok=True)
+            (backup_dir / container_path.strip('/').replace('/', '__')).write_text(old)
+            mode = host_file.stat().st_mode & 0o777 if host_file.exists() else 0o644
+            L.atomic_write(host_file, new, mode=mode)
+            print(f'   written (backup in {backup_dir})')
+    if not write and changed:
+        print(f'\n{changed} file(s) would change. Apply with:  lanes cursor-sync <workspace> --write')
+    return 0

package/payload/lanes/libexec/guard.py

@@ -0,0 +1,231 @@
+"""lanes guard — make the next in-container out-of-memory kill take a BUILD, never a lane.
+
+A container that hits its memory limit gets the kernel's OOM killer, which picks the task with the highest badness
+inside that cgroup: usually the biggest one, and the biggest one is usually an agent. This pass walks the container
+cgroups' pids and RAISES oom_score_adj to 800 on compilers, linkers and test runners — matched by EXACT comm, from an
+allow-list — so that one of them is the victim instead. A build can be re-run; a lane cannot.
+
+  * Plain /proc reads and writes. No subprocess, no docker, no signal. Raising one's own uid's oom_score_adj needs
+    no privilege (lowering it would: that half is sudo/host-guard.sh).
+  * It only ever RAISES, and only on the BUILD list. Everything else is left alone; PROTECT (and the container's
+    init pid) is spelled out anyway, so that a comm added to BUILD by mistake can still never hit a lane holder.
+  * Children inherit the value at fork: raising `cargo` once covers the rustc processes it starts afterwards.
+
+One pass per invocation (the 60 s timer is systemd's job; --once is accepted and means exactly that).
+--dry-run prints what it would do. Optional arguments: container names (default: every recorded container).
+
+This module is also where tmpscan.py gets the container's pids from (Env, container_pid, cgroup_pids).
+"""
+import os
+import signal
+import re
+import sys
+import time
+from pathlib import Path
+
+import lanes_lib as L
+
+OOM_ADJ = 800
+# comm is what the kernel reports (max 15 bytes): the binary's basename, or the script's for a #! script — so
+# `pytest` is the pytest entry point, while `python3 -m pytest` is `python3` and stays protected.
+BUILD = frozenset('cargo rustc cc1 cc1plus ld ld.lld lld mold clang clang++ gcc g++ zig bazel java golangci-lint '
+                  'compile link asm cgo vet rust-analyzer esbuild pytest py.test'.split())
+PROTECT = frozenset(['tmux: server', 'tmux', 'claude', 'codex', 'node', 'zellij', 'bash', 'zsh', 'sh', 'fish'])
+# A docker container's cgroup as the HOST spells it: …/docker-<id>.scope (systemd driver) or /docker/<id> (cgroupfs).
+# Not the substring 'docker': /system.slice/docker.service is the daemon. What follows the container's own group (a
+# container that runs systemd keeps its init in …scope/init.scope) is cut off: the walk must cover ALL of it.
+DOCKER_CGROUP = re.compile(r'^((?:/[^/]+)*?/docker-[0-9a-f]+\.scope|/docker/[0-9a-f]+)(?:/|$)')
+
+
+def protected(comm):
+    return comm in PROTECT or comm.startswith('python')
+
+
+class Env:
+    """Every handle on the outside world in one place, so the unit tests can aim at a synthetic tree.
+    LANES_STATE is read here at call time (L.STATE is frozen at import, too early for a test process)."""
+
+    def __init__(self, proc=None, cgroup=None, state=None, now=None, clock=None, uid=None):
+        self.proc = str(proc or os.environ.get('LANES_PROC_ROOT') or '/proc')
+        self.cgroup = str(cgroup or os.environ.get('LANES_CGROUP_ROOT') or '/sys/fs/cgroup')
+        self.state = Path(state or os.environ.get('LANES_STATE') or L.STATE)
+        self.now = now or time.time             # wall clock: ages of files
+        self.clock = clock or time.monotonic    # budgets
+        self.uid = L.CONTAINER_UID if uid is None else uid   # the container user: the only owner tmpscan removes from
+
+
+def container_names(env):
+    recorded = L.read_json(env.state / 'containers.json', {}) or {}
+    return sorted(recorded) or sorted(path.stem for path in (env.state / 'containers').glob('*.pid'))
+
+
+def container_pid(env, name):
+    """The init pid statusd/sync recorded for the container (never docker inspect: this runs on a thrashing host)."""
+    if not L.IDENT.match(name):
+        raise L.LanesError(f'Invalid container name: {name}')
+    try:
+        pid = int((env.state / 'containers' / f'{name}.pid').read_text().split()[0])
+    except (OSError, ValueError, IndexError):
+        raise L.LanesError(f'{name}: no init pid recorded — run `lanes sync`')
+    if pid <= 1:   # 0 = not running; 1 would be the HOST's init
+        raise L.LanesError(f'{name}: container is not running')
+    return pid
+
+
+def _ns_init(env, pid):
+    """Is `pid` pid 1 of a pid namespace of its own? NSpid spells a pid in every namespace it is seen from, outermost
+    first: a container's init reads 'NSpid: 4242 1', a host process 'NSpid: 4242', a container's child '… 4250 17'."""
+    try:
+        for line in Path(env.proc, str(pid), 'status').read_text().splitlines():
+            if line.startswith('NSpid:'):
+                seen = line.split()[1:]
+                return len(seen) >= 2 and seen[-1] == '1'
+    except OSError:
+        pass
+    return False
+
+
+def cgroup_dir(env, pid):
+    """Host directory of the container's cgroup-v2 group — and the proof that the RECORDED pid still is a docker
+    container's init. The pid file outlives the container, and while docker does not answer it is kept for as long
+    as /proc/<pid> exists: a recycled pid must never make us walk (or write to) the host's tasks, or resolve
+    /proc/<pid>/root/tmp in the host's mount namespace. The same two tests as ns_init in sudo/host-guard.sh."""
+    try:
+        text = Path(env.proc, str(pid), 'cgroup').read_text()
+    except OSError as error:
+        raise L.LanesError(f'pid {pid}: cannot read its cgroup ({error.strerror})')
+    for line in text.splitlines():
+        if line.startswith('0::'):
+            match = DOCKER_CGROUP.match(line[3:].strip())
+            if not match or '..' in match.group(1).split('/'):
+                break
+            if not _ns_init(env, pid):
+                raise L.LanesError(f'pid {pid} is not the init of a container (recycled pid?): refusing — run `lanes sync`')
+            return os.path.join(env.cgroup, *match.group(1).strip('/').split('/'))
+    raise L.LanesError(f'pid {pid} is not in a docker cgroup (v2): refusing')
+
+
+def cgroup_pids(env, pid):
+    """Every process of the container: cgroup.procs of its cgroup and of all child groups (HOST pids)."""
+    pids = set()
+    for directory, _dirs, files in os.walk(cgroup_dir(env, pid)):
+        if 'cgroup.procs' in files:
+            try:
+                pids.update(int(token) for token in Path(directory, 'cgroup.procs').read_text().split())
+            except (OSError, ValueError):
+                pass   # a child group that went away mid-walk
+    return sorted(pids)
+
+
+def tmux_servers(env, pid):
+    """{socket name: host pid} of the tmux SERVER processes of the container (comm 'tmux: server', name from -L)."""
+    found = {}
+    for process in cgroup_pids(env, pid):
+        try:   # a busy container starts and ends processes all the time: one that is gone by now is not a server
+            if _read(env, process, 'comm') != 'tmux: server':
+                continue
+            words = (_read(env, process, 'cmdline') or '').split('\0')
+        except OSError:
+            continue
+        for index, word in enumerate(words):
+            if word == '-L' and index + 1 < len(words) and L.IDENT.match(words[index + 1]):
+                found[words[index + 1]] = process
+                break
+        else:
+            if '-S' not in words:
+                found.setdefault('default', process)      # a plain `tmux`: the server of the socket named default
+    return found
+
+
+def sockets(env, names, repair=False, out=print, settle=2.0):
+    """`lanes sockets [check|repair]`: tmux servers whose socket FILE is gone (someone emptied the container's /tmp:
+    2026-09-20 every lane was alive and unreachable). repair = tmux's own remedy: recreate the directory, then
+    SIGUSR1 — "recreate the server socket", tmux(1) — to exactly the servers whose socket is missing. Nothing is
+    restarted; panes and agents do not notice. Returns the number of sockets still missing."""
+    missing_total = 0
+    for name in names:
+        try:
+            pid = container_pid(env, name)
+            cgroup_dir(env, pid)
+        except L.LanesError as error:
+            out(f'sockets: {name}: {error}')
+            continue
+        directory = f'{env.proc}/{pid}/root/tmp/tmux-{env.uid}'
+        servers = tmux_servers(env, pid)
+        missing = {sock: process for sock, process in servers.items() if not os.path.exists(f'{directory}/{sock}')}
+        out(f'sockets: {name}: {len(servers)} tmux servers, {len(missing)} without a socket file'
+            + (': ' + ' '.join(sorted(missing)) if missing else ''))
+        if missing and repair:
+            if not os.path.isdir(directory):
+                os.mkdir(directory, 0o700)
+                os.chmod(directory, 0o700)
+                out(f'sockets: {name}: recreated {directory}')
+            for sock, process in sorted(missing.items()):
+                try:
+                    if _read(env, process, 'comm') == 'tmux: server':   # still that process, still a tmux server
+                        os.kill(process, signal.SIGUSR1)
+                except OSError:
+                    pass                                                # it ended meanwhile: nothing to repair
+            time.sleep(settle)
+            missing = {sock: process for sock, process in missing.items() if not os.path.exists(f'{directory}/{sock}')}
+            out(f'sockets: {name}: after repair {len(missing)} still missing' + (': ' + ' '.join(sorted(missing)) if missing else ''))
+        missing_total += len(missing)
+    return missing_total
+
+
+def _read(env, pid, name):
+    return Path(env.proc, str(pid), name).read_text().rstrip('\n')
+
+
+def guard(env, names, dry_run=False, out=print):
+    seen = {'build': 0, 'raised': 0, 'protected': 0, 'errors': 0}
+    for name in names:
+        try:
+            init = container_pid(env, name)
+            pids = cgroup_pids(env, init)
+        except L.LanesError as error:
+            out(f'guard: {error}')
+            seen['errors'] += 1
+            continue
+        for pid in pids:
+            try:
+                comm = _read(env, pid, 'comm')
+                if pid == init or protected(comm):
+                    seen['protected'] += 1
+                    continue
+                if comm not in BUILD:
+                    continue
+                seen['build'] += 1
+                current = int(_read(env, pid, 'oom_score_adj'))
+                if current >= OOM_ADJ:
+                    continue
+                if not dry_run:
+                    Path(env.proc, str(pid), 'oom_score_adj').write_text(f'{OOM_ADJ}\n')
+                seen['raised'] += 1
+                out(f"guard: {name}: {'would raise' if dry_run else 'raised'} {pid} {comm} {current} -> {OOM_ADJ}")
+            except FileNotFoundError:
+                pass   # it exited: builds are short-lived
+            except (OSError, ValueError) as error:
+                seen['errors'] += 1
+                out(f'guard: {name}: pid {pid}: {error}')
+    out('guard: ' + ' '.join(f'{key}={value}' for key, value in seen.items()) + (' (dry-run)' if dry_run else ''))
+    return seen
+
+
+def run(args):
+    unknown = [arg for arg in args if arg.startswith('--') and arg not in ('--dry-run', '--once')]
+    if unknown:
+        raise L.LanesError('usage: lanes guard [--once] [--dry-run] [container…]')
+    env = Env()
+    names = [arg for arg in args if not arg.startswith('--')] or container_names(env)
+    # Exit 0 even with errors (they are printed and counted): a stopped container must not turn the every-minute
+    # timer unit into a permanently failed one.
+    guard(env, names, dry_run='--dry-run' in args)
+    return 0
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(run(sys.argv[1:]))
+    except L.LanesError as error:
+        sys.exit(f'lanes guard: {error}')