@vibelord/lanes 1.0.0

package/payload/lanes/bin/lanes

@@ -0,0 +1,1035 @@
+#!/usr/bin/env python3
+"""lanes — host-level workspace server CLI. Python 3 stdlib only.
+
+  lanes sync                     rebuild registry.json from the repos' terminal registries (read-only)
+  lanes ls [--json] [workspace]  list lanes with live status
+  lanes resolve <lane-id>        exact target of one lane as JSON (contract for the web harness)
+  lanes status                   one-line-per-workspace health summary
+  lanes attach <device> [--client ID] [--mobile] [--viewports N]
+                                 attach this terminal to the device's view session (creates it if needed)
+  lanes prepare <device> [--mobile]  create a device view without attaching a terminal (eg. Safari on a phone)
+  lanes open <lane-id>           attach this terminal straight to one lane (no multiplexer in between)
+  lanes layout <device> [--mobile]   print the generated zellij layout
+  lanes rebuild <device>         recreate a device's view session (agents are never touched)
+  lanes upgrade-session [device…]  add tabs a newer layout has (e.g. Throttle) to LIVE sessions, without a rebuild
+  lanes ensure                   recreate any known device session that is missing (never when zellij did not answer:
+                                 an unknown session list is not an empty one)
+  lanes reattach                 make every view re-attach its lane (after changing flags); agents untouched
+  lanes upload <ws> | --active <device> [--paste]
+                                 read a tar stream on stdin into that board's uploads/ folder (the same folder Cursor
+                                 users drop files into); prints the in-container paths. --paste also types the path(s)
+                                 into the lane that device is looking at. `lanes workspaces` lists board ids.
+  lanes cursor-sync [ws…] [--write] [--diff]
+                                 make Cursor/VS Code terminals open exactly the board's lanes through `lane open`
+                                 (dry-run by default: prints the git-style diff; --write applies with a backup)
+  lanes cursor-commit [ws…] [--push]
+                                 commit the normalized terminals.json on top of each repo's REMOTE branch tip and push it,
+                                 with git plumbing only (no working tree or index is touched). Dry-run without --push.
+  lanes hello [device]           what the client installer calls to prove the path, the key and the server version
+  lanes client-config            site facts for clients (KEY=VALUE from ~/.config/lanes/site.conf on the server)
+  lanes install-container <name> install the `lane` contract + pinned zmx into a container's home volume (additive)
+  lanes invariant save|check     snapshot / verify every live pane's pid and window size
+  lanes verify-legacy            compare the registry with the old in-container coder-launch layouts
+  lanes gc                       truncate oversized zmx logs, drop stale dynamic resolve files
+  lanes sockets [check|repair]   lanes that run but cannot be reached: tmux servers whose socket file was deleted
+                                 (someone emptied the container's /tmp); repair = tmux's SIGUSR1, nothing restarts
+  lanes pressure                 host memory / io pressure, swap, per-container memory and /tmp use — plain files and
+                                 statvfs only (no docker exec, no du): safe on a thrashing host. Exit 1 unless the level is ok
+  lanes tmp scan|plan|apply|reap|caches [--home] what fills the containers' RAM-backed /tmp, and removing the dead part (libexec/tmpscan.py;
+                                 `reap` is what lanes-tmpreap.timer runs hourly once YOU enable it — the install does not;
+                                 dry-run until ~/.local/state/lanes/flags/tmpreap.armed exists)
+  lanes guard [--dry-run] [container…]
+                                 one pass, by hand, that makes the next in-container out-of-memory kill take a build, never
+                                 a lane: raises oom_score_adj of compilers / test runners by exact name (libexec/guard.py).
+                                 No timer runs it: look at --dry-run first. The recurring half is sudo/host-guard.sh
+  lanes doctor                   full health check (every external call is bounded; includes the pressure summary)
+"""
+import json
+import os
+import re
+import shutil
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'libexec'))
+import lanes_lib as L  # noqa: E402
+
+SLOTS = ['main', 'b', 'c']
+ZELLIJ_VERSION = '0.45.1'
+ZELLIJ = L.SHARE / 'bin' / f'zellij-{ZELLIJ_VERSION}'
+ZELLIJ_BASE = [str(ZELLIJ), '--config-dir', str(L.REPO / 'zellij'), '--config', str(L.REPO / 'zellij/config.kdl')]
+PROC = Path(os.environ.get('LANES_PROC_ROOT') or '/proc')   # injectable for the unit tests
+
+
+def clean_env(extra=None):
+    """Environment for the view server: nothing from the ssh session leaks into panes."""
+    env = {'HOME': str(Path.home()), 'USER': os.environ.get('USER', 'dev'), 'SHELL': '/bin/bash',
+           'PATH': f"{L.SHARE / 'bin'}:{L.REPO / 'bin'}:/usr/local/bin:/usr/bin:/bin",
+           'LANG': 'C.UTF-8', 'LANES_STATE': str(L.STATE), 'LANES_SHARE': str(L.SHARE), 'LANES_ZELLIJ': str(ZELLIJ)}
+    for key in ('LANES_WORKSPACES', 'XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS', 'ZELLIJ_SOCKET_DIR'):  # last one: test isolation
+        if os.environ.get(key):
+            env[key] = os.environ[key]
+    if 'XDG_RUNTIME_DIR' not in env and Path(f'/run/user/{os.getuid()}').is_dir():
+        env['XDG_RUNTIME_DIR'] = f'/run/user/{os.getuid()}'
+    env.update(extra or {})
+    return env
+
+
+def q(text):
+    return json.dumps(text, ensure_ascii=False)
+
+
+# ------------------------------------------------------------------- registry
+
+def cmd_sync(_args):
+    previous = L.read_json(L.STATE / 'registry.json')
+    registry = L.build_registry(previous)
+    L.atomic_write(L.STATE / 'registry.json', json.dumps(registry, indent=1, ensure_ascii=False) + '\n')
+    L.write_resolve_files(registry)
+    L.export_container_registries(registry)
+    for workspace in registry['workspaces']:
+        focus = next((lane for lane in workspace['lanes'] if lane.get('focus')), None)
+        candidates = workspace['lanes'] or workspace['extras']
+        first = focus or (candidates[0] if candidates else None)
+        L.atomic_write(L.STATE / 'defaults' / workspace['id'], (first['id'] if first else '!empty') + '\n')
+    total = sum(len(w['lanes']) for w in registry['workspaces'])
+    failed = [w for w in registry['workspaces'] if w['errors']]
+    for workspace in registry['workspaces']:
+        mark = '!' if workspace['errors'] else ' '
+        print(f"{mark} {workspace['id']:<18} {len(workspace['lanes']):>3} lanes  {workspace['container']}")
+        for error in workspace['errors']:
+            print(f'    ⚠ {error}' + ('  (kept previous lanes)' if workspace.get('stale') else ''))
+    print(f"{total} lanes in {len(registry['workspaces'])} workspaces" + (f'; {len(failed)} with errors' if failed else ''))
+    return 1 if failed else 0
+
+
+def cmd_ls(args):
+    registry = L.load_registry()
+    status = (L.read_json(L.STATE / 'status.json') or {}).get('lanes', {})
+    wanted = [a for a in args if not a.startswith('-')]
+    rows = []
+    for workspace in registry['workspaces']:
+        if wanted and workspace['id'] not in wanted:
+            continue
+        for lane in workspace['lanes']:
+            rows.append(dict(lane, workspace=workspace['id'], status=status.get(lane['id'], {'state': 'unknown'})))
+    if '--json' in args:
+        print(json.dumps(rows, indent=1, ensure_ascii=False))
+        return 0
+    for row in rows:
+        target = (f"{row['tmux']['socket']} / {row['tmux']['session']}" if row['holder'] == 'tmux'
+                  else row.get('zmx', {}).get('name', ''))
+        state = row['status'].get('state', 'unknown') + ('?' if row['status'].get('stale') else '')   # ? = last known
+        print(f"{state:<8} {row['id']:<44} {row['holder']:<5} {target}")
+    return 0
+
+
+def cmd_resolve(args):
+    registry = L.load_registry()
+    workspace, lane = L.find_lane(registry, args[0])
+    info = (L.read_json(L.STATE / 'containers.json') or {}).get(lane['container'], {})
+    out = dict(lane, workspace=workspace['id'])
+    if lane['holder'] == 'tmux' and info.get('pid'):
+        out['socket_path'] = L.tmux_socket(info, lane['tmux']['socket'])
+        out['attach'] = [str(L.REPO / 'holders/tmux.sh'), lane['container'], lane['tmux']['socket'], lane['tmux']['session']]
+    print(json.dumps(out, indent=1, ensure_ascii=False))
+    return 0
+
+
+def cmd_status(_args):
+    registry = L.load_registry()
+    status = L.read_json(L.STATE / 'status.json') or {}
+    age = time.time() - status.get('updated_at', 0)
+    print(f"status.json age: {age:.0f}s" + ('  ⚠ statusd not running?' if age > 30 else ''))
+    for workspace in registry['workspaces']:
+        counts = {}
+        for lane in workspace['lanes']:
+            state = status.get('lanes', {}).get(lane['id'], {}).get('state', 'unknown')
+            counts[state] = counts.get(state, 0) + 1
+        summary = '  '.join(f'{k}={v}' for k, v in sorted(counts.items()))
+        print(f"  {workspace['id']:<18} {len(workspace['lanes']):>3}  {summary}")
+    return 0
+
+
+# --------------------------------------------------------------------- views
+
+def layout_kdl(device, mobile=False, viewports=1):
+    registry = L.load_registry()
+    sidebar, view = str(L.REPO / 'libexec/sidebar'), str(L.REPO / 'libexec/view.sh')
+    lines = ['// Generated by `lanes layout`. Lanes are NOT part of this layout: adding, removing or',
+             '// reordering lanes only changes registry.json, so this layout never needs live surgery.',
+             'layout {',
+             '    default_tab_template {',
+             '        children',
+             '        pane size=1 borderless=true {',
+             '            plugin location="zellij:compact-bar"',
+             '        }',
+             '    }']
+    for index, workspace in enumerate(registry['workspaces']):
+        focus = ' focus=true' if index == 0 else ''
+        if mobile:
+            lines += [f'    tab name={q(workspace["title"] + " ☰")}{focus} {{',
+                      f'        pane borderless=true name="Lanes" command={q(sidebar)} {{',
+                      f'            args {q(device)} {q(workspace["id"])}',
+                      '        }', '    }',
+                      f'    tab name={q(workspace["title"])} {{',
+                      f'        pane borderless=true name={q(workspace["title"])} command={q(view)} {{',
+                      f'            args {q(device)} {q(workspace["id"])} "main" "--mobile"',
+                      '        }', '    }']
+            continue
+        lines += [f'    tab name={q(workspace["title"])}{focus} {{',
+                  '        pane split_direction="vertical" {',
+                  f'            pane size=36 borderless=true name="Lanes" command={q(sidebar)} {{',
+                  f'                args {q(device)} {q(workspace["id"])} "main" {q(str(viewports))}',
+                  '            }']
+        # Wide devices: several viewports side by side, each with its own target (slots main, b, c).
+        for index, slot in enumerate(SLOTS[:viewports]):
+            title = workspace['title'] if index == 0 else f"{workspace['title']} ·{index + 1}"
+            pane_focus = ' focus=true' if index == 0 else ''
+            lines += [f'            pane borderless={"true" if viewports == 1 else "false"}{pane_focus} name={q(title)} command={q(view)} {{',
+                      f'                args {q(device)} {q(workspace["id"])} {q(slot)}',
+                      '            }']
+        lines += ['        }', '    }']
+    for tool in registry.get('tools', []):
+        lines += tool_tab_kdl(device, tool, mobile=mobile)
+    lines += ['    tab name="Host" {', '        pane command="/bin/bash" {', '            args "-l"', '        }', '    }', '}']
+    return '\n'.join(lines) + '\n'
+
+
+def tool_tab_kdl(device, tool, indent='    ', mobile=False):
+    """One full-size tab for a shared tool (the Throttle monitor). It is a view with a fixed target, so it starts
+    only when the tab is first shown and restarts by itself if the tool exits."""
+    view = str(L.REPO / 'libexec/view.sh')
+    extra = ' "main" "--mobile"' if mobile else ''
+    return [f'{indent}tab name={q(tool["tab"])} {{',
+            f'{indent}    pane borderless=true name={q(tool["name"])} command={q(view)} {{',
+            f'{indent}        args {q(device)} {q(tool["view"])}{extra}',
+            f'{indent}    }}', f'{indent}}}']
+
+
+def zellij(args, timeout):
+    """One bounded zellij CLI call -> (rc, stdout, stderr); rc None = no answer in time. L.run_bounded, not
+    subprocess.run(timeout=): that one waits without a bound for the killed child, which never returns if the
+    child sits in D state on a thrashing host."""
+    return L.run_bounded(ZELLIJ_BASE + args, timeout, env=clean_env())
+
+
+def live_sessions():
+    """Names of the live view sessions. Raises when zellij did not ANSWER (timeout, error): an unknown list is
+    not an empty one, and no caller may create or rebuild a session from it."""
+    rc, out, err = zellij(['list-sessions', '--no-formatting'], 20)
+    if rc == 1 and 'no active zellij sessions' in (out + err).lower():
+        return set()   # zellij's way of saying "none" is exit 1 plus this sentence: a positive answer
+    if rc != 0:
+        reason = 'no answer in 20 s' if rc is None else (err.strip() or out.strip() or f'exit {rc}')
+        raise L.LanesError(f'cannot list the view sessions ({reason}); is the host under pressure? — see `lanes pressure`')
+    names = set()
+    for line in out.splitlines():
+        if line.strip() and '(EXITED' not in line:
+            names.add(line.split()[0])
+    return names
+
+
+def device_name(value):
+    if not L.IDENT.match(value or '') or len(value) > 32:
+        raise L.LanesError('Invalid device name')
+    return value
+
+
+def create_session(device, mobile, viewports=1):
+    # A headless session has a made-up size (50x50): its views must idle until a real client arrives.
+    try:
+        (L.STATE / 'clients' / f'{device}.ready').unlink()
+    except OSError:
+        pass
+    for shown in (L.STATE / 'views' / device).glob('*.shown'):
+        shown.unlink(missing_ok=True)
+    layout_file = L.STATE / 'layouts' / f'{device}.kdl'
+    L.atomic_write(layout_file, layout_kdl(device, mobile, viewports))
+    meta_file = L.STATE / 'devices' / f'{device}.json'
+    meta = {'version': 1, 'mobile': mobile, 'viewports': viewports, 'created_at': time.time()}
+    base = (L.read_json(meta_file) or {}).get('base')
+    if base:   # learnt at attach (see base_device); `ensure` and `rebuild` must not forget it
+        meta['base'] = base
+    L.atomic_write(meta_file, json.dumps(meta) + '\n')
+    command = ZELLIJ_BASE + ['--layout', str(layout_file), 'attach', '--create-background', device]
+    if shutil.which('systemd-run'):
+        # Own cgroup scope: a zellij leak can never pressure the host or any lane. It lives in lanes.slice, whose
+        # CPUWeight (systemd/lanes.slice) keeps the views scheduled on a thrashing host; the weight is set on the
+        # slice only, never per scope.
+        command = ['systemd-run', '--user', '--scope', '--quiet', '--collect', '--slice=lanes.slice',
+                   f'--unit=lanes-session-{device}-{int(time.time())}',
+                   '-p', 'MemoryLow=512M', '-p', 'MemoryHigh=2G', '-p', 'MemoryMax=4G', '--'] + command
+    rc, out, err = L.run_bounded(command, 60, env=clean_env())   # stdin is /dev/null, never the caller's tty
+    if rc != 0:
+        raise L.LanesError(f'Could not create session {device}: '
+                           + ('no answer in 60 s' if rc is None else err.strip() or out.strip() or f'exit {rc}'))
+
+
+def base_device(device, default):
+    """The machine a view belongs to: `mac-2` / `mac-w2`, opened by the client whose default device is `mac`, share
+    mac's upload helper (one helper service per machine); every other device is its own base."""
+    return default if default and device.startswith(default + '-') else device
+
+
+def viewports_arg(args, default=1):
+    if '--viewports' in args:
+        try:
+            return max(1, min(len(SLOTS), int(args[args.index('--viewports') + 1])))
+        except (ValueError, IndexError):
+            raise L.LanesError('--viewports takes 1, 2 or 3')
+    return default
+
+
+def cmd_layout(args):
+    print(layout_kdl(device_name(args[0]), '--mobile' in args, viewports_arg(args)), end='')
+    return 0
+
+
+def cmd_attach(args):
+    device = device_name(args[0])
+    # Old muscle memory: `coder-launch worlds`. A workspace id is not a device: open the caller's normal
+    # device session and bring that workspace's tab to the front.
+    tab = None
+    default = args[args.index('--default-device') + 1] if '--default-device' in args[:-1] else None
+    try:
+        workspace = next((w for w in L.load_registry()['workspaces'] if w['id'] == device), None)
+    except L.LanesError:
+        workspace = None
+    if workspace:
+        if not default:
+            print(f"lanes: '{device}' is a workspace, not a device. Attach your device session and use Ctrl-Alt-←/→.", file=sys.stderr)
+            return 64
+        tab, device = workspace['title'], device_name(default)
+    client = args[args.index('--client') + 1] if '--client' in args else 'default'
+    if not re.match(r'^[A-Za-z0-9_.-]{1,48}$', client):
+        raise L.LanesError('Invalid client id')
+    if not ZELLIJ.exists():
+        raise L.LanesError(f'{ZELLIJ} is not installed: run install/host-install.sh')
+    if not (L.STATE / 'registry.json').exists():
+        cmd_sync([])
+    try:
+        missing = device not in live_sessions()
+    except L.LanesError as error:
+        # Unknown is not missing: create nothing and just try to attach. If the session really is gone, zellij says
+        # so itself (nothing is resurrected: session_serialization is off) and lanes-launch retries.
+        print(f'lanes: {error}', file=sys.stderr)
+        missing = False
+    if missing:
+        create_session(device, '--mobile' in args, viewports_arg(args))
+    # Record the base, also for sessions that existed before it was known. A client that names no default device
+    # teaches nothing: what is recorded stays. Readers treat a missing "base" as the device itself. (`default` is
+    # unvalidated client text, but only ever stored when it is a prefix of the validated device name.)
+    meta_file = L.STATE / 'devices' / f'{device}.json'
+    meta = L.read_json(meta_file) or {}
+    if default and meta and meta.get('base') != base_device(device, default):
+        L.atomic_write(meta_file, json.dumps(dict(meta, base=base_device(device, default))) + '\n')
+    # Views idle until a real client (with a real size) has attached once. We exec into the zellij
+    # client below, so a detached helper raises the flag shortly after the client has sized the session.
+    ready = L.STATE / 'clients' / f'{device}.ready'
+    if not ready.exists() and os.fork() == 0:
+        os.setsid()
+        devnull = os.open(os.devnull, os.O_RDWR)
+        for fd in (0, 1, 2):
+            os.dup2(devnull, fd)
+        time.sleep(1.5)
+        L.atomic_write(ready, f'{time.time()}\n')
+        os._exit(0)
+    # Reap our own stale predecessor (same device + client id) instead of waiting for sshd timeouts.
+    pid_file = L.STATE / 'clients' / f'{device}.{client}.pid'
+    try:
+        old = int(pid_file.read_text().strip())
+        cmdline = Path(f'/proc/{old}/cmdline').read_bytes()
+        if old != os.getpid() and b'zellij' in cmdline and b'attach' in cmdline:
+            os.kill(old, 15)
+    except (OSError, ValueError):
+        pass
+    L.atomic_write(pid_file, f'{os.getpid()}\n')
+    if tab and os.fork() == 0:  # after the client is attached, show the requested workspace
+        os.setsid()
+        devnull = os.open(os.devnull, os.O_RDWR)
+        for fd in (0, 1, 2):
+            os.dup2(devnull, fd)
+        time.sleep(1.2)
+        zellij(['-s', device, 'action', 'go-to-tab-name', tab], 15)
+        os._exit(0)
+    env = clean_env({'TERM': os.environ.get('TERM', 'xterm-256color'),
+                     'COLORTERM': os.environ.get('COLORTERM', 'truecolor')})
+    if L.run_bounded(['infocmp', env['TERM']], 5)[0] != 0:   # unknown here — or no answer: the safe default
+        env['TERM'] = 'xterm-256color'
+    os.execve(str(ZELLIJ), ZELLIJ_BASE + ['attach', device], env)
+
+
+def cmd_open(args):
+    lane_id = args[0]
+    if not re.match(r'^[A-Za-z0-9_.-]+$', lane_id):
+        raise L.LanesError('Invalid lane id')
+    resolve = L.STATE / 'resolve' / lane_id
+    if not resolve.exists():
+        resolve = L.STATE / 'resolve.dynamic' / lane_id
+    if not resolve.exists():
+        raise L.LanesError(f'Unknown lane: {lane_id}')
+    holder, a, b, c = resolve.read_text().split('\n')[:4]
+    if holder not in ('tmux', 'zmx', 'exec'):
+        raise L.LanesError(f'Unknown holder: {holder}')
+    env = clean_env({'TERM': 'xterm-256color', 'LANES_WS': lane_id.split('--')[0]})
+    os.execve(str(L.REPO / 'holders' / f'{holder}.sh'), [f'{holder}.sh', a, b, c], env)
+
+
+ENV_HOOK = '[ -r "$HOME/.lz/env.sh" ] && . "$HOME/.lz/env.sh"  # lanes-env: temp files off the RAM-backed /tmp'
+
+
+def hook_env(home):
+    """Make env.sh take effect for NEW shells: the disk temp dir it points at, and ONE marker-guarded line appended to
+    the login files bash/zsh really read. Append only, idempotent, never rewrites a dotfile; remove the line to undo."""
+    tmp = home / '.tmp'
+    if not tmp.exists():
+        tmp.mkdir(mode=0o700)
+        tmp.chmod(0o700)
+    login = home / '.bash_profile' if (home / '.bash_profile').exists() else home / '.profile'
+    targets = [login, home / '.bashrc'] + ([home / '.zshrc'] if (home / '.zshrc').exists() else [])
+    for path in targets:
+        text = path.read_text(errors='replace') if path.exists() else ''
+        if 'lanes-env' in text:
+            continue
+        with open(path, 'a') as handle:
+            handle.write(('' if text.endswith('\n') or not text else '\n') + ENV_HOOK + '\n')
+
+
+def cmd_install_container(args):
+    container = args[0]
+    info = L.container_info(container)
+    if not info.get('home'):
+        raise L.LanesError(f'{container}: home volume not found')
+    root = Path(info['home']) / '.lz'
+    for sub in ('bin', 's', 'meta', 'state'):
+        (root / sub).mkdir(parents=True, exist_ok=True)
+    for source in (L.REPO / 'container/lane', L.REPO / 'container/lane-run'):
+        shutil.copy2(source, root / 'bin' / source.name)
+    env_file = L.REPO / 'container/env.sh'   # TMPDIR off the RAM-backed /tmp; only NEW shells and agents read it
+    if env_file.exists():
+        shutil.copy2(env_file, root / 'env.sh')
+        hook_env(Path(info['home']))
+    for binary in sorted((L.SHARE / 'bin').glob('zmx-*')):
+        target = root / 'bin' / binary.name
+        if not target.exists():  # a running lane's daemon keeps executing its own version: never overwrite
+            shutil.copy2(binary, target)
+    link = Path.home() / '.lz' / container
+    link.parent.mkdir(parents=True, exist_ok=True)
+    if link.is_symlink() or link.exists():
+        link.unlink()
+    link.symlink_to(root)
+    print(f'installed {root}/bin/{{lane,lane-run,zmx-*}}' + (f' and {root}/env.sh' if env_file.exists() else '')
+          + f'; host link {link} -> {root}')
+    return 0
+
+
+def cmd_rebuild(args):
+    device = device_name(args[0])
+    meta = L.read_json(L.STATE / 'devices' / f'{device}.json') or {}
+    if device in live_sessions():
+        # Attached clients see an ordinary exit (0) when their session is killed: leave a stamp so that
+        # lanes-launch (`lanes rebuilt <device>`) reconnects instead of closing the window.
+        L.atomic_write(L.STATE / 'clients' / f'{device}.rebuilt', f'{time.time()}\n')
+        if zellij(['kill-session', device], 30)[0] is None:
+            raise L.LanesError(f'zellij did not answer in 30 s: {device} was NOT rebuilt (no lane was touched)')
+        zellij(['delete-session', '--force', device], 30)
+    create_session(device, bool(meta.get('mobile')) or '--mobile' in args, viewports_arg(args, int(meta.get('viewports') or 1)))
+    print(f'rebuilt view session {device}; no lane was touched')
+    return 0
+
+
+def cmd_upgrade_session(args):
+    registry = L.load_registry()
+    live = live_sessions()
+    devices = [device_name(a) for a in args] or [p.stem for p in sorted((L.STATE / 'devices').glob('*.json'))]
+    for device in devices:
+        if device not in live:
+            print(f'{device}: not running (it gets the current layout when it is next created)')
+            continue
+        rc, out, _err = zellij(['-s', device, 'action', 'list-tabs', '-j'], 20)
+        if rc != 0:   # unknown tabs are not missing tabs: add nothing
+            print(f'{device}: zellij did not answer; left alone')
+            continue
+        tabs = json.loads(out or '[]')
+        names = {tab.get('name') for tab in tabs}
+        for tool in registry.get('tools', []):
+            if tool['tab'] in names:
+                print(f"{device}: tab '{tool['tab']}' already present")
+                continue
+            layout = '\n'.join(['layout {', '    default_tab_template {', '        children',
+                                '        pane size=1 borderless=true {', '            plugin location="zellij:compact-bar"',
+                                '        }', '    }'] + tool_tab_kdl(device, tool) + ['}'])
+            active = next((tab for tab in tabs if tab.get('active')), None)
+            zellij(['-s', device, 'action', 'new-tab', '--name', tool['tab'], '--layout-string', layout], 30)
+            if active:  # new-tab takes the focus: hand it back to where the user was
+                zellij(['-s', device, 'action', 'go-to-tab-name', active['name']], 15)
+            print(f"{device}: added tab '{tool['tab']}'")
+    return 0
+
+
+def cmd_reattach(_args):
+    count = 0
+    for pid_file in (L.STATE / 'views').glob('*/*.pid'):
+        try:
+            pid = int(pid_file.read_text().strip())
+            if b'view.sh' in Path(f'/proc/{pid}/cmdline').read_bytes():
+                os.kill(pid, 10)  # SIGUSR1
+                count += 1
+        except (OSError, ValueError):
+            pass
+    print(f're-attached {count} views')
+    return 0
+
+
+def cmd_ensure(_args):
+    # live_sessions() raises when zellij did not answer: then this run ends here and recreates nothing (the timer
+    # tries again in a minute). "Missing" is only ever concluded from a list zellij actually gave.
+    live = live_sessions()
+    for meta_file in sorted((L.STATE / 'devices').glob('*.json')):
+        device = meta_file.stem
+        if device not in live:
+            meta = L.read_json(meta_file) or {}
+            create_session(device, bool(meta.get('mobile')), int(meta.get('viewports') or 1))
+            print(f'recreated view session {device}')
+    return 0
+
+
+def cmd_prepare(args):
+    device = device_name(args[0])
+    if device not in live_sessions():
+        create_session(device, '--mobile' in args, viewports_arg(args))
+    elif '--mobile' in args and not (L.read_json(L.STATE / 'devices' / f'{device}.json') or {}).get('mobile'):
+        raise L.LanesError(f'{device} already has a desktop layout; choose another device name')
+    print(f'ready: {device}')
+    return 0
+
+
+# ------------------------------------------------------------------ safety
+
+PANE_FORMAT = '#{session_name}\t#{window_index}.#{pane_index}\t#{pane_pid}\t#{window_width}x#{window_height}'
+
+
+def all_panes():
+    """Every pane on every LIVE tmux server that the registry references (ps-discovered, read-only).
+    Ephemeral test-harness sockets come and go on their own and are not lanes.
+    Raises when ps or a live server did not ANSWER: a partial list would be saved as a weaker invariant, or
+    compared as panes that are "gone" — on a busy host both are wrong."""
+    sys.path.insert(0, str(L.REPO / 'libexec'))
+    import statusd
+    unknown = 'the panes are UNKNOWN, not gone — nothing saved or compared; try again'
+    live = statusd.live_tmux_sockets()
+    if live is None:
+        raise L.LanesError(f'ps did not answer: {unknown}')
+    containers = L.read_json(L.STATE / 'containers.json') or {}
+    referenced = {}
+    for workspace in L.load_registry()['workspaces']:
+        for lane in workspace['lanes']:
+            if lane['holder'] == 'tmux':
+                referenced.setdefault(lane['container'], set()).add(lane['tmux']['socket'])
+    panes = {}
+    for container, info in containers.items():
+        if not info.get('pid'):
+            continue
+        for socket in sorted(live & referenced.get(container, set())):
+            outcome, output = L.tmux_probe(info, socket, ['list-panes', '-a', '-F', PANE_FORMAT])
+            if outcome in ('timeout', 'error'):
+                raise L.LanesError(f'{container}/{socket}: tmux did not answer ({outcome}): {unknown}')
+            for row in (output if outcome == 'ok' else '').splitlines():
+                session, pane, pid, size = row.split('\t')
+                panes[f'{container}/{socket}/{session}/{pane}'] = {'pid': pid, 'size': size}
+    return panes
+
+
+def cmd_invariant(args):
+    path = L.STATE / 'invariant.json'
+    current = all_panes()
+    if args and args[0] == 'save':
+        L.atomic_write(path, json.dumps({'saved_at': time.time(), 'panes': current}, indent=1) + '\n')
+        print(f'saved {len(current)} panes')
+        return 0
+    saved = (L.read_json(path) or {}).get('panes')
+    if saved is None:
+        raise L.LanesError('No saved invariant: run `lanes invariant save` first')
+    gone = [k for k in saved if k not in current]
+    changed_pid = [k for k in saved if k in current and saved[k]['pid'] != current[k]['pid']]
+    resized = [k for k in saved if k in current and saved[k]['size'] != current[k]['size']]
+    new = [k for k in current if k not in saved]
+    print(f'panes: saved={len(saved)} now={len(current)} gone={len(gone)} pid-changed={len(changed_pid)} '
+          f'resized={len(resized)} new={len(new)}')
+    for label, keys in (('GONE', gone), ('PID', changed_pid), ('RESIZED', resized)):
+        for key in keys[:20]:
+            print(f'  {label:<8} {key}  {saved[key]} -> {current.get(key)}')
+    # Sizes are part of the invariant only while the old viewers own them (coexistence mode).
+    sizes_matter = (L.STATE / 'flags/coexist').exists()
+    return 1 if (gone or changed_pid or (resized and sizes_matter)) else 0
+
+
+def cmd_verify_legacy(_args):
+    registry = L.load_registry()
+    containers = registry['containers']
+    bad = 0
+    for workspace in registry['workspaces']:
+        info = containers.get(workspace['container']) or {}
+        layout = Path(info.get('home', '')) / '.config/coder-launch/layouts' / f"{workspace['id']}.kdl"
+        try:
+            text = layout.read_text()
+        except OSError:
+            print(f"? {workspace['id']:<18} no deployed legacy layout")
+            continue
+        deployed = {}
+        for match in re.finditer(r'tab name=("(?:[^"\\]|\\.)*")[^\n]*\{\s*pane [^\n]*coder-launch/connect"\s*\{\s*args ("(?:[^"\\]|\\.)*") ("(?:[^"\\]|\\.)*")', text):
+            name, socket, session = (json.loads(g) for g in match.groups())
+            deployed[name] = (socket, session)
+        ours = {lane['name']: (lane['tmux']['socket'], lane['tmux']['session'])
+                for lane in workspace['lanes'] if lane['holder'] == 'tmux'}
+        diffs = [n for n in sorted(set(ours) | set(deployed)) if ours.get(n) != deployed.get(n)]
+        bad += len(diffs)
+        print(f"{'✓' if not diffs else '✗'} {workspace['id']:<18} registry={len(ours):>3} deployed={len(deployed):>3}")
+        for name in diffs:
+            print(f'    {name!r}: registry={ours.get(name)} deployed={deployed.get(name)}')
+    return 1 if bad else 0
+
+
+def active_workspace(registry, device):
+    """The board the device's view is showing right now (its active zellij tab)."""
+    out = zellij(['-s', device, 'action', 'list-tabs', '-j'], 15)[1]
+    try:
+        active = next(t for t in json.loads(out) if t.get('active'))
+    except (ValueError, StopIteration):
+        raise L.LanesError(f'cannot tell which board {device} is showing; name one: lanes upload <workspace>')
+    title = active.get('name', '').replace(' ☰', '')
+    for workspace in registry['workspaces']:
+        if workspace['title'] == title:
+            return workspace
+    raise L.LanesError(f"the active tab '{title}' is not a board; name one: lanes upload <workspace>")
+
+
+def type_into_lane(registry, device, workspace, text):
+    """Type text into the lane shown in the device's first viewport (user-initiated input, like typing)."""
+    target = L.STATE / 'views' / device / f"{workspace['id']}.main.target"
+    lane_id = (target.read_text().split('\n')[0] if target.exists() else '') or \
+        (L.STATE / 'defaults' / workspace['id']).read_text().split('\n')[0]
+    _ws, lane = L.find_lane(registry, lane_id)
+    info = (L.read_json(L.STATE / 'containers.json') or {}).get(lane['container'], {})
+    if lane['holder'] == 'tmux':
+        ok = L.tmux_query(info, lane['tmux']['socket'], ['send-keys', '-t', f"={lane['tmux']['session']}:", '-l', '--', text])
+        return lane['name'] if ok is not None else None
+    return None
+
+
+def paste_target(spool, request, fallback):
+    """Requests of a suffixed view (mac-2) are spooled under its BASE device (mac), whose one helper serves the whole
+    machine with the unchanged line protocol; the sidecar <id>.dev names the view that asked — the device whose
+    lane gets the paste. No (or an unusable) sidecar = an older sidebar: the spool's own device, as before."""
+    try:
+        return device_name((spool / f'{request}.dev').read_text().strip())
+    except (OSError, L.LanesError):
+        return fallback
+
+
+class UploadReader:
+    """Stream bytes without buffering the upload in RAM; record activity for the sidebar's idle timeout."""
+    def __init__(self, source, progress):
+        self.source, self.progress = source, progress
+        self.received, self.updated = 0, 0
+
+    def read(self, size):
+        data = self.source.read(size)
+        self.received += len(data)
+        now = time.monotonic()
+        if self.progress and data and now - self.updated >= 1:
+            L.atomic_write(self.progress, json.dumps({'bytes': self.received}) + '\n')
+            self.updated = now
+        return data
+
+
+def cmd_upload(args):
+    import shlex
+    import tarfile
+    registry = L.load_registry()
+    device = args[args.index('--active') + 1] if '--active' in args else None
+    paste_device = args[args.index('--device') + 1] if '--device' in args else device
+    default_device = args[args.index('--default-device') + 1] if '--default-device' in args else None
+    if paste_device:
+        paste_device = resolve_device(paste_device, args)
+    request = args[args.index('--request') + 1] if '--request' in args else None
+    if request and not re.match(r'^[0-9]+-[0-9]+$', request):
+        raise L.LanesError('invalid request id')
+    spool = L.STATE / 'upload-requests' / device_name(paste_device) if (request and paste_device) else None
+    skip = {device, paste_device, request, default_device, args[args.index('--device') + 1] if '--device' in args else None}
+    names = [a for a in args if not a.startswith('--') and a not in skip]
+    if device:
+        workspace = active_workspace(registry, device_name(device))
+    elif names:
+        workspace = next((w for w in registry['workspaces'] if w['id'] == names[0]), None)
+        if not workspace:
+            raise L.LanesError(f'unknown board: {names[0]} (see `lanes workspaces`)')
+    else:
+        raise L.LanesError('usage: lanes upload <workspace> | --active <device>  [--paste]   (tar stream on stdin)')
+    folder = next((lane.get('folder') for lane in workspace['lanes'] if lane.get('folder')), None) or workspace['cwd']
+    info = registry['containers'].get(workspace['container']) or {}
+    root = L.host_path(info, folder)
+    uploads = root / 'uploads'
+    uploads.mkdir(exist_ok=True)
+    # Keep uploads out of commits without touching a tracked .gitignore: the repository-local exclude file.
+    exclude = root / '.git' / 'info' / 'exclude'
+    # check-ignore: 0 = ignored, 1 = not ignored; an error or no answer (None) is not a reason to append.
+    if (root / '.git').is_dir() and L.run_bounded(['git', '-C', str(root), 'check-ignore', '-q', 'uploads/x'], 10)[0] == 1:
+        exclude.parent.mkdir(exist_ok=True)
+        with open(exclude, 'a') as handle:
+            handle.write('\n# lanes upload: local intake folder, never committed\nuploads/\n')
+    staging = uploads / f'.incoming-{os.getpid()}'
+    staging.mkdir()
+    landed = []
+    try:
+        stream = UploadReader(sys.stdin.buffer, spool / f'{request}.progress' if spool else None)
+        with tarfile.open(fileobj=stream, mode='r|') as archive:
+            archive.extractall(staging, filter='data')  # regular files/dirs only, no absolute paths, no links out
+        for entry in sorted(staging.iterdir()):
+            final, n = uploads / entry.name, 1
+            while final.exists():  # never overwrite an earlier upload
+                final = uploads / f'{entry.stem}-{n}{entry.suffix}'
+                n += 1
+            entry.rename(final)
+            landed.append(f"{folder}/uploads/{final.name}")
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
+    if not landed:
+        # The helper reports the client-side cause (eg. macOS denied Downloads). Publishing a generic .err here
+        # races that report: the sidebar consumes it and loses the useful error before the helper can send it.
+        raise L.LanesError('nothing was uploaded (empty archive)')
+    for path in landed:
+        print(path)
+    if '--paste' in args and paste_device:
+        # The result files (.done / .err) stay in the base spool, where the asking sidebar looks for them.
+        view_device = paste_target(spool, request, paste_device) if spool else paste_device
+        shown = type_into_lane(registry, device_name(view_device), workspace, ' '.join(shlex.quote(p) for p in landed) + ' ')
+        print(f'# typed into lane: {shown}' if shown else '# could not type into the lane (not a tmux lane?)', file=sys.stderr)
+    if spool:
+        L.atomic_write(spool / f'{request}.done', '\n'.join(landed) + '\n')
+    return 0
+
+
+def resolve_device(name, args):
+    """`coder-launch worlds` style: a board id given where a device is expected means "my default device"."""
+    try:
+        boards = {w['id'] for w in L.load_registry()['workspaces']}
+    except L.LanesError:
+        boards = set()
+    if name in boards and '--default-device' in args:
+        name = args[args.index('--default-device') + 1]
+    return device_name(name)
+
+
+def cmd_upload_requests(args):
+    """Long-running: stream this device's upload requests (made by the sidebar's upload box) to the client-side
+    helper as a simple line protocol, one request at a time, at most once (atomic rename):
+        BEGIN <request-id> <board> <paste:0|1> / P <local path> ... / END"""
+    device = resolve_device(args[0], args)
+    spool = L.STATE / 'upload-requests' / device
+    spool.mkdir(parents=True, exist_ok=True)
+    deadline = time.time() + 900          # the client reconnects; keeps stale helpers from piling up
+    print('READY', flush=True)
+    last_ping = time.time()
+    while time.time() < deadline:
+        L.atomic_write(spool / 'agent.alive', f'{time.time()}\n')
+        for request in sorted(spool.glob('*.req')):
+            taken = request.with_suffix('.sent')
+            try:
+                request.rename(taken)
+            except OSError:
+                continue                   # another helper of this device took it
+            lines = taken.read_text().split('\n')
+            board, paste, paths = lines[0], lines[1], [p for p in lines[2:] if p]
+            if not L.IDENT.match(board) or not paths or any('\n' in p for p in paths):
+                L.atomic_write(taken.with_suffix('.err'), 'malformed request\n')
+                continue
+            out = [f'BEGIN {taken.stem} {board} {1 if paste == "1" else 0}'] + [f'P {p}' for p in paths] + ['END']
+            try:
+                print('\n'.join(out), flush=True)
+            except BrokenPipeError:
+                taken.rename(request)      # helper went away: leave the request for the next one
+                return 0
+        if time.time() - last_ping > 5:
+            try:
+                print('PING', flush=True)  # notice a dead client
+                last_ping = time.time()
+            except BrokenPipeError:
+                return 0
+        time.sleep(0.4)
+    return 0
+
+
+def cmd_upload_result(args):
+    """The client helper reports a request it refused (folder not allowed, file missing)."""
+    rest = list(args)
+    if '--default-device' in args:
+        index = args.index('--default-device')
+        del rest[index:index + 2]
+    device, request, message = resolve_device(args[0], args), rest[1], ' '.join(rest[2:])[:200]
+    if not re.match(r'^[0-9]+-[0-9]+$', request):
+        raise L.LanesError('invalid request id')
+    L.atomic_write(L.STATE / 'upload-requests' / device / f'{request}.err', message + '\n')
+    return 0
+
+
+def cmd_workspaces(_args):
+    for workspace in L.load_registry()['workspaces']:
+        print(workspace['id'])
+    return 0
+
+
+def cmd_rebuilt(args):
+    """Exit 0 if this device's view session was rebuilt in the last minute (the client then reconnects)."""
+    try:
+        stamp = float((L.STATE / 'clients' / f'{resolve_device(args[0], args)}.rebuilt').read_text())
+    except (OSError, ValueError):
+        return 1
+    return 0 if time.time() - stamp < 60 else 1
+
+
+def cmd_hello(args):
+    device = resolve_device(args[0], args) if args else '-'
+    version = (L.REPO / 'VERSION').read_text().strip() if (L.REPO / 'VERSION').exists() else 'dev'
+    boards = len(L.load_registry()['workspaces']) if (L.STATE / 'registry.json').exists() else 0
+    print(f'ok device={device} version={version} boards={boards}')
+    return 0
+
+
+def cmd_client_config(_args):
+    """Site facts a client may want after its first connection (e.g. the public fallback address), so that they
+    need not be written into the distributed package. KEY=VALUE lines, LANES_* keys only."""
+    path = Path.home() / '.config/lanes/site.conf'
+    for line in (path.read_text().splitlines() if path.exists() else []):
+        if re.match(r'^LANES_[A-Z_]+=[A-Za-z0-9_.:@/-]*$', line):
+            print(line)
+    return 0
+
+
+def cmd_cursor_sync(args):
+    import cursor_sync
+    return cursor_sync.run(args)
+
+
+def cmd_cursor_commit(args):
+    import cursor_commit
+    return cursor_commit.run(args)
+
+
+def cmd_gc(_args):
+    limit = 5 * 1024 * 1024
+    for link in sorted((Path.home() / '.lz').glob('*')):
+        for log in (link / 's' / 'logs').glob('*.log'):
+            try:
+                if log.stat().st_size > limit:  # zmx logging cannot be disabled and never rotates
+                    with open(log, 'r+b') as handle:
+                        handle.seek(-1024 * 1024, 2)
+                        tail = handle.read()
+                        handle.seek(0)
+                        handle.write(tail)
+                        handle.truncate()
+                    print(f'truncated {log}')
+            except OSError as error:
+                print(f'skip {log}: {error}')
+    status = L.read_json(L.STATE / 'status.json') or {}
+    known = set(status.get('lanes', {}))
+    for stale in (L.STATE / 'resolve.dynamic').glob('*'):
+        if stale.name not in known and time.time() - stale.stat().st_mtime > 3600:
+            stale.unlink()
+            print(f'removed stale {stale.name}')
+    return 0
+
+
+def cmd_tmp(args):
+    return libexec_module('tmpscan').run(args)   # verbs, options and the usage text are tmpscan's
+
+
+def cmd_guard(args):
+    return libexec_module('guard').run(args)
+
+
+def libexec_module(name):
+    try:
+        return __import__(name)
+    except ImportError as error:   # lanes-tmpreap.timer runs this every hour: one line in the journal, no traceback
+        raise L.LanesError(f'libexec/{name}.py: {error}')
+
+
+def pressure_lines(health, containers):
+    """Human lines for `lanes pressure` and the doctor. `health` is L.compute_health() (plain files, no subprocess);
+    /tmp use comes from statvfs through /proc/<init-pid>/root — an in-memory answer, never docker exec or du."""
+    def gib(value):
+        return '?' if value is None else f'{value:.1f}'
+    lines = [f"  level {health.get('level', '?')}: memory some {health.get('mem_some10', '?')}% full {health.get('mem_full10', '?')}%"
+             f" · io some {health.get('io_some10', '?')}% · cpu some {health.get('cpu_some10', '?')}% (10 s averages)"
+             f" · swap {health.get('swap_pct', '?')}% used · load {health.get('load1', '?')} on {health.get('ncpu', '?')} cpus"]
+    memory = health.get('containers') or {}
+    for name in sorted(set(memory) | set(containers)):
+        row = memory.get(name) or {}
+        pinned = None if row.get('anon_gib') is None else row['anon_gib'] + (row.get('shmem_gib') or 0)
+        line = (f"  {name}: {gib(pinned)} GiB not reclaimable (processes {gib(row.get('anon_gib'))} + RAM-backed files "
+                f"{gib(row.get('shmem_gib'))}) of a {gib(row.get('max_gib'))} GiB limit; with page cache {gib(row.get('cur_gib'))}"
+                f"; oom kills {row.get('oom_kill', '?')}")
+        try:
+            vfs = os.statvfs(PROC / str((containers.get(name) or {}).get('pid') or 0) / 'root/tmp')
+            line += f'; /tmp {gib((vfs.f_blocks - vfs.f_bfree) * vfs.f_frsize / 2 ** 30)} of {gib(vfs.f_blocks * vfs.f_frsize / 2 ** 30)} GiB'
+        except OSError:
+            line += '; /tmp not readable'
+        lines.append(line)
+    return lines
+
+
+def cmd_sockets(args):
+    """lanes sockets [check|repair]: tmux servers that run but whose socket file was deleted (emptied /tmp)."""
+    import guard
+    verb = args[0] if args else 'check'
+    if verb not in ('check', 'repair'):
+        raise L.LanesError('usage: lanes sockets [check|repair]')
+    env = guard.Env()
+    return 1 if guard.sockets(env, guard.container_names(env), repair=verb == 'repair') else 0
+
+
+def cmd_pressure(_args):
+    health = L.compute_health()
+    print('\n'.join(pressure_lines(health, L.read_json(L.STATE / 'containers.json') or {})))
+    return 0 if health.get('level') == 'ok' else 1
+
+
+def cmd_doctor(_args):
+    problems = 0
+
+    def check(ok, label, detail=''):
+        nonlocal problems
+        problems += 0 if ok else 1
+        print(f"{'✓' if ok else '✗'} {label}" + (f' — {detail}' if detail else ''))
+
+    check(ZELLIJ.exists(), f'zellij {ZELLIJ_VERSION} installed', str(ZELLIJ))
+    registry = L.read_json(L.STATE / 'registry.json')
+    check(bool(registry), 'registry present')
+    if registry:
+        errors = [(w['id'], e) for w in registry['workspaces'] for e in w['errors']]
+        check(not errors, 'registry clean', '; '.join(f'{w}: {e}' for w, e in errors))
+        # Stale registry check: any terminals.json newer than the last sync?
+        generated_at = registry.get('generated_at', 0)
+        stale_sources = []
+        for w in registry['workspaces']:
+            for lane in w.get('lanes', []):
+                src = lane.get('source')
+                if src:
+                    try:
+                        if Path(src).stat().st_mtime > generated_at:
+                            stale_sources.append(src)
+                    except OSError:
+                        pass
+        unique_stale = list(dict.fromkeys(stale_sources))
+        check(not unique_stale, 'registry up to date',
+              'run lanes sync — ' + '; '.join(unique_stale[:3]) + (' …' if len(unique_stale) > 3 else ''))
+        for name, info in (L.read_json(L.STATE / 'containers.json') or {}).items():
+            check(bool(info.get('running')), f'container {name} running', f"init pid {info.get('pid')}")
+    status = L.read_json(L.STATE / 'status.json') or {}
+    age = time.time() - status.get('updated_at', 0)
+    check(age < 30, 'statusd heartbeat', f'{age:.0f}s old')
+    states, stale = {}, 0
+    for value in status.get('lanes', {}).values():
+        states[value.get('state', 'unknown')] = states.get(value.get('state', 'unknown'), 0) + 1
+        stale += 1 if value.get('stale') else 0
+    # 'unknown' / stale = statusd could not OBSERVE the lane (its tmux server did not answer): not the same as gone.
+    check(not states.get('missing') and not states.get('unknown') and not stale, 'all registry lanes observed and present',
+          str(states) + (f'; {stale} shown with their last known state (tmux server did not answer)' if stale else ''))
+    # One bounded process-table sweep serves both checks; the cgroup of the few tmux servers is a plain file read.
+    rc, table, _err = L.run_bounded(['ps', '-eo', 'pid=,comm=,args='], 10)
+    coexist = (L.STATE / 'flags/coexist').exists()
+    if rc != 0:
+        check(False, 'process table readable', 'ps did not answer in 10 s: phantom tmux servers and coexistence mode NOT checked'
+              if rc is None else f'ps exit {rc}')
+    else:
+        phantom = []
+        for line in table.splitlines():
+            pid, _, rest = line.strip().partition(' ')
+            if rest.lstrip().startswith('tmux: server'):
+                try:
+                    if 'docker' not in (PROC / pid / 'cgroup').read_text():
+                        phantom.append(line.strip())
+                except OSError:   # gone since the sweep
+                    pass
+        check(not phantom, 'no host-side tmux servers (phantoms)', '; '.join(phantom)[:200])
+        old_viewers = 'coder-launch/connect ' in table
+        check(not coexist or old_viewers, 'coexistence mode',
+              ('ON while old coder-launch viewers exist (ignore-size)' if old_viewers else
+               'flag is SET but no old viewers exist: lanes will not resize (dotted padding). Fix: rm ~/.local/state/lanes/flags/coexist && lanes reattach')
+              if coexist else 'OFF (viewers size the lane they show)')
+    zmx_lanes = sum(len(v) for v in (status.get('zmx') or {}).values())
+    installed = [link.name for link in sorted((Path.home() / '.lz').glob('*')) if (link / 'bin/lane').exists()]
+    print(f"  lane contract installed in: {', '.join(installed) or 'no container yet'}; zmx-held lanes: {zmx_lanes}")
+    try:
+        print('  view sessions:', ', '.join(sorted(live_sessions())) or 'none')
+    except (OSError, L.LanesError) as error:
+        check(False, 'zellij reachable', str(error))
+    print('PRESSURE')
+    health = L.compute_health()
+    print('\n'.join(pressure_lines(health, L.read_json(L.STATE / 'containers.json') or {})))
+    check(health.get('level') != 'critical', 'host not under critical memory pressure',
+          'views and status may lag or time out; the lanes themselves keep running' if health.get('level') != 'ok' else '')
+    return 1 if problems else 0
+
+
+def cmd_rename(args):
+    """lanes rename <lane-id> <new-name>
+
+    Rename a lane's display name.
+    - Unregistered sessions: writes user-sessions metadata + updates resolve.dynamic.
+    - Registered lanes: writes a displayNames override to the workspace manifest and syncs the registry.
+    """
+    if len(args) < 2:
+        raise L.LanesError('usage: lanes rename <lane-id> <new-name>')
+    import session_actions as SA
+    lane_id, new_name = args[0], ' '.join(args[1:])
+    registry = L.load_registry()
+    # Locate the lane
+    workspace_obj = None
+    lane = None
+    for w in registry['workspaces']:
+        for l in w['lanes']:
+            if l['id'] == lane_id:
+                workspace_obj, lane = w, l
+                break
+        if lane:
+            break
+    # Check unregistered (dynamic)
+    if not lane:
+        status = L.read_json(L.STATE / 'status.json') or {}
+        for w_id, entries in (status.get('unregistered') or {}).items():
+            for e in entries:
+                if e['id'] == lane_id:
+                    updated = SA.rename_session(w_id, e, new_name)
+                    print(f"renamed unregistered lane {lane_id!r} → {new_name!r}")
+                    return 0
+    if not lane:
+        raise L.LanesError(f'Unknown lane: {lane_id}')
+    # Registered lane: update displayNames in manifest
+    source = lane.get('source')
+    if not source:
+        raise L.LanesError('No manifest source for this lane; set displayNames in the workspace manifest manually')
+    registry_name = lane.get('registry_name') or lane.get('name', '')
+    SA.rename_registered(source, registry_name, new_name)
+    cmd_sync([])   # rebuild registry so all consumers see the new name
+    print(f"renamed registered lane {lane_id!r} ({registry_name!r}) → {new_name!r}")
+    return 0
+
+
+COMMANDS = {'rebuilt': cmd_rebuilt, 'hello': cmd_hello, 'client-config': cmd_client_config, 'cursor-commit': cmd_cursor_commit, 'upgrade-session': cmd_upgrade_session, 'upload-requests': cmd_upload_requests, 'upload-result': cmd_upload_result, 'upload': cmd_upload, 'workspaces': cmd_workspaces, 'cursor-sync': cmd_cursor_sync, 'reattach': cmd_reattach, 'gc': cmd_gc, 'install-container': cmd_install_container, 'open': cmd_open, 'sync': cmd_sync, 'ls': cmd_ls, 'resolve': cmd_resolve, 'status': cmd_status, 'layout': cmd_layout,
+            'prepare': cmd_prepare, 'attach': cmd_attach, 'rebuild': cmd_rebuild, 'ensure': cmd_ensure, 'invariant': cmd_invariant,
+            'verify-legacy': cmd_verify_legacy, 'doctor': cmd_doctor, 'pressure': cmd_pressure, 'sockets': cmd_sockets, 'tmp': cmd_tmp,
+            'guard': cmd_guard, 'rename': cmd_rename}
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        sys.exit(__doc__)
+    try:
+        sys.exit(COMMANDS[sys.argv[1]](sys.argv[2:]) or 0)
+    except L.LanesError as error:
+        sys.exit(f'lanes: {error}')
+    except IndexError:
+        sys.exit(__doc__)