@vibelord/lanes 1.0.0

package/payload/lanes/libexec/lanes_lib.py

@@ -0,0 +1,610 @@
+"""Shared helpers for the lanes host server. Python 3 stdlib only.
+
+Safety rules encoded here (see docs/ARCHITECTURE.md):
+  * Observation and attachment never create or stop lanes. Explicit New/Close actions are separate.
+  * tmux is always invoked with -N (never start a server) and a scrubbed environment.
+  * In-container sockets are reached through /proc/<container-init-pid>/root, anchored on the
+    container's init pid (stable across tmux-server restarts), never through docker exec.
+"""
+import hashlib
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+import unicodedata
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+STATE = Path(os.environ.get('LANES_STATE', Path.home() / '.local/state/lanes'))
+SHARE = Path(os.environ.get('LANES_SHARE', Path.home() / '.local/share/lanes'))
+
+
+def workspaces_dir():
+    """SITE data — which boards exist and where their terminal registries live. Not part of the product:
+    $LANES_WORKSPACES, else ~/.config/lanes/workspaces (if it holds a catalog), else <repo>/workspaces."""
+    if os.environ.get('LANES_WORKSPACES'):
+        return Path(os.environ['LANES_WORKSPACES'])
+    site = Path.home() / '.config/lanes/workspaces'
+    return site if (site / 'catalog.json').exists() else REPO / 'workspaces'
+
+
+CONTAINER_HOME = '/home/coder'
+CONTAINER_UID = 1000
+
+LANE_OPEN = '/.lz/bin/lane open '   # the uniform Cursor-facing entry point written by `lanes cursor-sync`
+IDENT = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_.-]*$')
+TMUX_SESSION = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_. -]*$')
+SAFE_PATH = re.compile(r'^/[A-Za-z0-9_./-]+$')
+
+# The Throttle Studio Host's OWN grouped session names, mirroring `studio_host::tmux::WebSession::channel_of`
+# exactly: `view-<studio token>-<channel>` as `for_channel` mints it (the token is `[A-Za-z0-9_-]` and may
+# itself carry `-`, so the channel is the segment after the LAST `-`), or the legacy `web-<channel>`. The
+# channel is canonical decimal digits inside u32. A PREFIX test is deliberately NOT the rule: `view-notes`,
+# `viewer-1`, `web-dev` and `web-007` are operator names the Host never mints — and therefore never un-flags
+# and never sweeps (DEF-980).
+HOST_VIEW_SESSION = re.compile(r'(?:view-[A-Za-z0-9_-]+|web)-(0|[1-9][0-9]*)')
+
+
+def is_host_view(session):
+    """Whether `session` is a name the Studio Host mints for a browser attach. Pure, and the mirror of
+    `WebSession::channel_of` — the whole grammar, never the `view-`/`web-` prefix."""
+    found = HOST_VIEW_SESSION.fullmatch(session or '')
+    return bool(found) and int(found.group(1)) <= 0xFFFFFFFF
+
+
+def grouped_members(listing, session):
+    """The sessions grouped onto `session` (sharing its windows), split into the ones the Studio Host MINTS
+    and the strangers — pure, so the rule is unit-testable without a tmux server. `listing` is
+    `list-sessions -F '#{session_name}\\t#{session_group}'` output.
+
+    tmux shares a group's windows between its sessions, so killing the group LEADER only unlinks the leader's
+    winlinks: every window and every process keeps running under the grouped member (MEASURED, tmux 3.4).
+    `studio_host::lane::stop` kills the Host's own view members first and refuses `not_stoppable` for a
+    stranger for exactly this reason; the sidebar's `×` did neither, said "Closed", and left the panes
+    running under a survivor that came back as a new 👻 on the next cycle (DEF-981)."""
+    views, strangers = [], []
+    for line in (listing or '').splitlines():
+        name, _, group = line.partition('\t')
+        if not name or name == session or group != session:
+            continue
+        (views if is_host_view(name) else strangers).append(name)
+    return views, strangers
+
+
+ANSI_NAMES =['Black', 'Red', 'Green', 'Yellow', 'Blue', 'Magenta', 'Cyan', 'White']
+ANSI_SLOTS = {}
+for _i, _n in enumerate(ANSI_NAMES):
+    ANSI_SLOTS[f'terminal.ansi{_n}'] = _i
+    ANSI_SLOTS[f'terminal.ansiBright{_n}'] = _i + 8
+
+# Default-emoji-presentation glyphs only (no VS16): column widths stay stable everywhere.
+LANE_ICONS = {
+    'pulse': '💓', 'repo': '📁', 'type-hierarchy': '🌳', 'layers': '🧩', 'lightbulb': '💡',
+    'symbol-color': '🎨', 'person': '👤', 'game': '🎮', 'tools': '🔧', 'globe': '🌐',
+    'organization': '👥', 'terminal': '💻', 'watch': '⌚', 'compass': '🧭', 'book': '📖',
+    'package': '📦', 'map': '🌍', 'hubot': '🤖', 'files': '📄', 'layout': '▦',
+    'symbol-structure': '🧱', 'beaker': '🧪', 'references': '🔗', 'edit': '📝', 'sparkle': '✨',
+    'briefcase': '💼', 'comment': '💬', 'comment-discussion': '💬', 'search': '🔎',
+    'rocket': '🚀', 'database': '💾', 'shield': '🔐', 'terminal-bash': '💻', 'warning': '🚧',
+    'gear': '🔩', 'window': '🪟', 'table': '📊', 'dashboard': '📈', 'graph': '📈',
+    'device-desktop': '💻', 'server': '📡', 'git-pull-request': '🔀', 'sync': '🔄',
+    'extensions': '🧩', 'circuit-board': '🧠',
+}
+
+
+class LanesError(Exception):
+    pass
+
+
+def atomic_write(path, text, mode=0o600):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix='.' + path.name + '.', dir=str(path.parent))
+    try:
+        with os.fdopen(fd, 'w') as handle:
+            handle.write(text)
+        os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def read_json(path, default=None):
+    try:
+        return json.loads(Path(path).read_text())
+    except (OSError, ValueError):
+        return default
+
+
+def slug(text):
+    text = unicodedata.normalize('NFKD', text).encode('ascii', 'ignore').decode()
+    text = re.sub(r'[^A-Za-z0-9]+', '-', text).strip('-').lower()
+    return text or 'lane'
+
+
+# ------------------------------------------------------------ bounded spawns
+
+def run_bounded(argv, timeout, input=None, env=None):
+    """Run argv -> (rc, stdout, stderr), text mode. rc is None when the child did not finish in `timeout` seconds.
+
+    subprocess.run(timeout=) kills the child and then waits for it WITHOUT a bound. On a thrashing host that child
+    can sit in D state (uninterruptible) for minutes, or a grandchild keeps the pipes open — and the caller hangs
+    with it. Here: kill, ONE more bounded wait (2 s; it also collects what was already written), then abandon the
+    child. subprocess reaps an abandoned child on a later spawn, so no zombie is left behind.
+    A spawn that fails (no such binary, fork refused under memory pressure) is rc 127 with the reason on stderr.
+    Undecodable output bytes are replaced: a stray byte in somebody's argv (`ps`) must not raise in here."""
+    try:
+        child = subprocess.Popen(argv, stdin=subprocess.PIPE if input is not None else subprocess.DEVNULL,
+                                 stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, errors='replace', env=env)
+    except OSError as error:
+        return 127, '', str(error)
+    try:
+        out, err = child.communicate(input, timeout=timeout)
+        return child.returncode, out, err
+    except subprocess.TimeoutExpired:
+        child.kill()
+    try:
+        out, err = child.communicate(timeout=2)
+    except subprocess.TimeoutExpired:
+        out, err = '', ''
+        for stream in (child.stdin, child.stdout, child.stderr):   # abandoned: do not leak its pipes as well
+            try:
+                if stream:
+                    stream.close()
+            except OSError:
+                pass
+        child.poll()   # reaps a child that DID die (only its pipes are held open); never blocks on one that did not
+    return None, out or '', err or ''
+
+
+def proc_root():
+    """/proc, or a directory of synthetic files in the unit tests (LANES_PROC_ROOT)."""
+    return os.environ.get('LANES_PROC_ROOT') or '/proc'
+
+
+# ---------------------------------------------------------------- containers
+
+class NoSuchContainer(LanesError):
+    """docker ANSWERED that the container does not exist — an observation, unlike every other docker failure."""
+
+
+def docker_inspect(container, template):
+    rc, out, err = run_bounded(['docker', 'inspect', '-f', template, container], 20)
+    if rc is None:
+        raise LanesError(f'docker inspect {container}: no answer within 20 s')
+    if rc:
+        # "Error: No such object: <name>" (after a `docker rm`) is an answer ABOUT the container. Any other failure
+        # — daemon unreachable or busy, fork refused, permission — says nothing about it, whatever the exit code.
+        reason = err.lower()
+        gone = 'no such object' in reason or 'no such container' in reason
+        raise (NoSuchContainer if gone else LanesError)(f'docker inspect {container}: {err.strip()}')
+    return out.strip()
+
+
+def container_info(container):
+    """Init pid and host path of the container's /home/coder volume."""
+    if not IDENT.match(container):
+        raise LanesError(f'Invalid container name: {container}')
+    pid = int(docker_inspect(container, '{{.State.Pid}}') or 0)
+    home = docker_inspect(
+        container,
+        '{{range .Mounts}}{{if eq .Destination "' + CONTAINER_HOME + '"}}{{.Source}}{{end}}{{end}}')
+    return {'pid': pid, 'home': home, 'running': pid > 0}
+
+
+def refresh_containers(names):
+    previous = read_json(STATE / 'containers.json', {}) or {}
+    info = {}
+    for name in sorted(set(names)):
+        try:
+            info[name] = container_info(name)
+        except NoSuchContainer:
+            # An answer, like the pid 0 of a stopped container: NO 'error' key, so statusd publishes its lanes as
+            # 'missing' instead of keeping their last state as if docker had been silent.
+            info[name] = {'pid': 0, 'home': '', 'running': False}
+        except (LanesError, subprocess.SubprocessError, ValueError) as error:
+            # docker did not ANSWER (timeout, busy daemon): that says nothing about the container. While the init
+            # pid recorded last time is still alive, keep it — writing pid 0 here would tell every viewer and
+            # statusd "container down" because of a slow docker. A container that really went away takes its init
+            # pid with it, so this cannot keep a dead one alive.
+            old = previous.get(name) or {}
+            if old.get('pid') and os.path.exists(f"{proc_root()}/{old['pid']}"):
+                info[name] = dict(old, running=True, error=str(error))
+            else:
+                info[name] = {'pid': 0, 'home': '', 'running': False, 'error': str(error)}
+        # One tiny file per container: the POSIX-sh holders read it without python or docker.
+        atomic_write(STATE / 'containers' / f'{name}.pid', f"{info[name]['pid']}\n")
+    atomic_write(STATE / 'containers.json', json.dumps(info, indent=2) + '\n')
+    return info
+
+
+def host_path(info, container_path):
+    """Map an absolute in-container path under /home/coder to the host volume path."""
+    if not SAFE_PATH.match(container_path) or '..' in container_path.split('/'):
+        raise LanesError(f'Unsafe registry path: {container_path}')
+    if not (container_path + '/').startswith(CONTAINER_HOME + '/'):
+        raise LanesError(f'Registry outside the home volume: {container_path}')
+    if not info.get('home'):
+        raise LanesError('Container home volume unknown')
+    return Path(info['home']) / container_path[len(CONTAINER_HOME) + 1:]
+
+
+def tmux_socket(info, socket_name):
+    return f"/proc/{info['pid']}/root/tmp/tmux-{CONTAINER_UID}/{socket_name}"
+
+
+def tmux_env():
+    return {'PATH': '/usr/bin:/bin', 'TERM': 'xterm-256color', 'LANG': 'C.UTF-8', 'HOME': str(Path.home())}
+
+
+def tmux_probe(info, socket_name, args, timeout=5):
+    """tmux query against an in-container server -> (outcome, text). -N: never start a server.
+
+    'ok'       the server answered; text = its stdout
+    'noserver' it positively does not exist: no container pid, no socket file, or tmux says nobody listens there
+    'timeout'  no answer in time — on a busy host this says NOTHING about the server
+    'error'    any other failure; text = tmux's stderr
+    Only ok/noserver are observations. A caller that turns timeout/error into "gone" reports an overloaded host
+    as lost lanes."""
+    if not info.get('pid'):
+        return 'noserver', ''
+    path = tmux_socket(info, socket_name)
+    if not os.path.exists(path):
+        return 'noserver', ''
+    rc, out, err = run_bounded(['tmux', '-N', '-u', '-S', path] + args, timeout, env=tmux_env())
+    if rc is None:
+        return 'timeout', ''
+    if rc == 0:
+        return 'ok', out
+    # tmux_env() pins LANG=C.UTF-8, so these are tmux's English texts. "error connecting" also covers EACCES,
+    # EAGAIN (listen backlog full) …: only the two reasons that mean "nobody listens there" count as no server.
+    reason = err.lower()
+    if 'no server running' in reason or ('error connecting' in reason and (
+            'no such file' in reason or 'connection refused' in reason)):
+        return 'noserver', ''
+    if reason.strip() == 'no current target' and args and args[0].startswith('list-'):
+        # A LIVE server that holds ZERO sessions. MEASURED (tmux 3.4): `list-sessions` exits 0 with empty output
+        # while `list-panes -a` / `list-windows -a` / `list-clients` exit 1 with exactly this text. Under the
+        # operator's `set -g exit-empty off` that is the STEADY state of a board socket once its last lane ends,
+        # not a transient — so reading it as a failure published `unknown` for every declared lane of that socket
+        # while the Studio Host answered `absent` for the same server (`studio_host::tmux::probe_socket` has this
+        # exact arm, "which is not an error"). An empty listing IS the answer: there are no sessions (DEF-894).
+        #
+        # ONLY for a LISTING verb. tmux answers the same text to a TARGETED verb against an absent session on
+        # such a server (MEASURED, tmux 3.4: `send-keys -t '=gone:'` -> `no current target`, rc 1, where with
+        # another session present it says `can't find session: gone`), and reading that as 'ok' turned a write
+        # that reached no pane into a reported success: `lanes upload --paste` printed "# typed into lane: <name>"
+        # for text nobody received, and `has-session` through `tmux_query` answered "it exists" for a session
+        # that does not (DEF-967). A targeted verb's failure stays 'error', as it was before this arm.
+        return 'ok', ''
+    return 'error', err.strip()
+
+
+def tmux_query(info, socket_name, args, timeout=5):
+    """tmux_probe for callers that only need "text or None" (None = no usable answer, for whatever reason)."""
+    outcome, text = tmux_probe(info, socket_name, args, timeout)
+    return text if outcome == 'ok' else None
+
+
+# -------------------------------------------------------------------- health
+# Host pressure from PLAIN FILES only — no subprocess: this is read exactly when spawning is what hurts.
+
+HEALTH_LINE = ('at', 'level', 'mem_some10', 'mem_full10', 'io_some10', 'cpu_some10', 'swap_pct', 'load1', 'status_at')
+
+
+def _text(path):
+    try:
+        return Path(path).read_text()
+    except (OSError, ValueError):
+        return ''
+
+
+def _psi10(text, kind):
+    """'some avg10=12.34 avg60=… total=…' -> 12 (percent of the last 10 s that tasks were stalled)."""
+    match = re.search(r'^' + kind + r' avg10=([0-9.]+)', text, re.M)
+    try:
+        return int(round(float(match.group(1)))) if match else 0
+    except ValueError:
+        return 0
+
+
+def _container_memory(proc, cgroup_root, pid):
+    """cgroup-v2 memory of the container whose init is `pid`; the cgroup is found the way the kernel names it."""
+    match = re.search(r'^0::(/\S*)$', _text(proc / str(pid) / 'cgroup'), re.M) if pid else None
+    if not match or '..' in match.group(1).split('/'):
+        return None
+    base = cgroup_root / match.group(1).lstrip('/')
+    current = _text(base / 'memory.current').strip()
+    if not current.isdigit():
+        return None
+    limit = _text(base / 'memory.max').strip()
+
+    def counter(name, key):
+        found = re.search(r'^' + key + r' (\d+)$', _text(base / name), re.M)
+        return int(found.group(1)) if found else 0
+
+    gib = 2 ** 30
+    return {'cur_gib': round(int(current) / gib, 1), 'max_gib': round(int(limit) / gib, 1) if limit.isdigit() else None,
+            'shmem_gib': round(counter('memory.stat', 'shmem') / gib, 1),   # shmem = RAM-backed /tmp and /dev/shm
+            # anon + shmem is what cannot be given back; `file` minus shmem is page cache, which always grows to the
+            # limit on a busy container ("207.9 of 208" is normal and says nothing about pressure)
+            'anon_gib': round(counter('memory.stat', 'anon') / gib, 1),
+            'oom_kill': counter('memory.events', 'oom_kill')}
+
+
+def health_level(health):
+    if health['mem_some10'] >= 40 or health['mem_full10'] >= 15:
+        return 'critical'
+    # Load is a last resort only (4 x cores): on a host that runs ~170 agents the load average sits near 1.5 x cores
+    # all day (measured: 100-150 on 64 cpus with memory and io pressure at 0-2 %), and a permanent 'busy' would both
+    # wear the banner out and keep statusd's size reconciler switched off. Pressure (PSI) is the signal.
+    if health['mem_some10'] >= 10 or health['io_some10'] >= 25 or health['load1'] >= 4 * health['ncpu']:
+        return 'busy'
+    return 'ok'
+
+
+def compute_health(paths=None):
+    """paths (tests): 'proc' (else $LANES_PROC_ROOT, else /proc), 'cgroup' (/sys/fs/cgroup), 'containers'
+    ($STATE/containers.json: whose init pids to look up), 'ncpu'. A file that is missing reads as 0."""
+    paths = paths or {}
+    proc = Path(paths.get('proc') or proc_root())
+    pressure = {name: _text(proc / 'pressure' / name) for name in ('memory', 'io', 'cpu')}
+    meminfo = {key: int(value) for key, value in re.findall(r'^(SwapTotal|SwapFree):\s+(\d+)', _text(proc / 'meminfo'), re.M)}
+    try:
+        load1 = float(_text(proc / 'loadavg').split()[0])
+    except (IndexError, ValueError):
+        load1 = 0.0
+    swap_total = meminfo.get('SwapTotal', 0)
+    health = {'at': time.time(), 'level': 'ok',
+              'mem_some10': _psi10(pressure['memory'], 'some'), 'mem_full10': _psi10(pressure['memory'], 'full'),
+              'io_some10': _psi10(pressure['io'], 'some'), 'cpu_some10': _psi10(pressure['cpu'], 'some'),
+              'swap_pct': int(round(100 * (swap_total - meminfo.get('SwapFree', 0)) / swap_total)) if swap_total else 0,
+              'load1': load1, 'ncpu': int(paths.get('ncpu') or os.cpu_count() or 1), 'containers': {}}
+    health['level'] = health_level(health)
+    recorded = read_json(paths.get('containers') or STATE / 'containers.json', {}) or {}
+    for name, info in recorded.items():
+        memory = _container_memory(proc, Path(paths.get('cgroup') or '/sys/fs/cgroup'), (info or {}).get('pid'))
+        if memory:
+            health['containers'][name] = memory
+    return health
+
+
+def health_line(health, status_at):
+    """The one line of $STATE/health (sh and python read it without JSON). Key order is part of the format."""
+    values = dict(health, at=int(health['at']), load1=f"{health['load1']:.2f}", status_at=int(status_at))
+    return ' '.join(f'{key}={values[key]}' for key in HEALTH_LINE) + '\n'
+
+
+def read_health(state_dir=None):
+    """$STATE/health as a dict ({} = no such file yet). The PRODUCER is what freezes on a bad host, so a reader
+    judges freshness with its own clock: now - at (or the file mtime); older than 30 s = statusd is not keeping up."""
+    health = {}
+    for token in _text(Path(state_dir or STATE) / 'health').split():
+        key, equals, value = token.partition('=')
+        if equals:
+            try:
+                health[key] = value if key == 'level' else float(value) if key == 'load1' else int(value)
+            except ValueError:
+                pass
+    return health
+
+
+# ------------------------------------------------------------------ registry
+
+def _require(pattern, value, label):
+    if not isinstance(value, str) or not pattern.match(value):
+        raise LanesError(f'Invalid {label}: {value!r}')
+    return value
+
+
+def _title(value):
+    if not isinstance(value, str) or not value or re.search(r'[\x00-\x1f\x7f]', value):
+        raise LanesError('Invalid lane name')
+    return value
+
+
+def _workspace_lanes(manifest, containers):
+    """Port of coder-launch/manage.mjs: explicit tmux bindings only; nothing is ever executed."""
+    lanes = []
+    names = set()
+    repo_ids = set()
+    for repo in manifest.get('repositories') or []:
+        repo_id = _require(IDENT, repo.get('id'), 'repository id')
+        container = _require(IDENT, repo.get('host'), 'container')
+        if repo_id in repo_ids:
+            raise LanesError(f'Duplicate repository id: {repo_id}')
+        repo_ids.add(repo_id)
+        info = containers.get(container) or {}
+        registry_file = host_path(info, repo.get('registry', ''))
+        registry = json.loads(registry_file.read_text())
+        terminals = registry.get('terminals')
+        if not isinstance(terminals, list) or not terminals:
+            raise LanesError(f'No terminals in {repo_id}')
+        for source in repo.get('bindingSources') or []:
+            digest = hashlib.sha256(host_path(info, source.get('path', '')).read_bytes()).hexdigest()
+            if digest != source.get('sha256'):
+                raise LanesError(f"Binding source changed: {source.get('path')}; inspect its tmux targets "
+                                 'before updating the saved bindings.')
+        throttle = ((registry.get('throttle') or {}).get('terminals') or {})
+        declared = ((registry.get('lanes') or {}).get('terminals') or {})
+        folder = repo.get('registry', '').split('/.vscode/')[0] if '/.vscode/' in repo.get('registry', '') \
+            else (manifest.get('remoteShell') or {}).get('cwd') or CONTAINER_HOME
+        for entry in terminals:
+            name = entry.get('name')
+            own = declared.get(name) or {}
+            # `lanes cursor-sync` records the binding and the original command next to the terminal, so the
+            # Cursor-facing `command` can be the uniform `lane open <id>` entry point.
+            binding = own.get('tmux') or (throttle.get(name) or {}).get('tmux')
+            create = own.get('create') if 'create' in own else entry.get('command')
+            recovery = None if own.get('tmux') else (repo.get('bindingRecoveries') or {}).get(name)
+            if recovery:
+                if (not binding or entry.get('command') != recovery.get('expectedCommand')
+                        or binding.get('socketName') != recovery.get('expectedSocketName')
+                        or binding.get('sessionName') != recovery.get('expectedSessionName')):
+                    raise LanesError(f'Registry changed since session recovery: {repo_id}/{name}')
+                binding = recovery
+            override = None if own.get('tmux') else (repo.get('bindingOverrides') or {}).get(name)
+            if not binding and override:
+                binding = override
+                if 'expectedCommand' in binding:
+                    matches = entry.get('command') == binding['expectedCommand']
+                else:
+                    prefix = f"TMUX= tmux -L {binding.get('socketName')} new -ADs {binding.get('sessionName')} "
+                    matches = (entry.get('command') or '').startswith(prefix)
+                if not matches:
+                    raise LanesError(f'Registry command no longer agrees with saved binding: {name}')
+            if not binding:
+                raise LanesError(f'Missing explicit tmux binding: {repo_id}/{name}')
+            title = _title(f"{repo.get('prefix') or ''}{name}")
+            if title in names:
+                raise LanesError('Duplicate lane names: configure repository prefixes')
+            names.add(title)
+            color = entry.get('color') if isinstance(entry.get('color'), str) else None
+            icon = entry.get('icon') if isinstance(entry.get('icon'), str) else None
+            display = (repo.get('displayNames') or {}).get(name)
+            lanes.append({
+                'name': _title(display) if display else title, 'registry_name': title, 'repo': repo_id, 'container': container, 'holder': 'tmux',
+                'tmux': {'socket': _require(IDENT, binding.get('socketName'), 'tmux socket'),
+                         'session': _require(TMUX_SESSION, binding.get('sessionName'), 'tmux session')},
+                'focus': entry.get('focus') is True,
+                'color': ANSI_SLOTS.get(color),
+                'icon': LANE_ICONS.get(icon, '💻'),
+                'create': create if isinstance(create, str) and LANE_OPEN not in create else None,
+                'folder': folder, 'source': repo.get('registry'),
+            })
+    return lanes
+
+
+def _workspace_cwd(manifest):
+    cwd = (manifest.get('remoteShell') or {}).get('cwd')
+    if cwd:
+        return cwd
+    registry = (manifest.get('repositories') or [{}])[0].get('registry', '')
+    return registry.split('/.vscode/')[0] if '/.vscode/' in registry else CONTAINER_HOME
+
+
+SITE_SCHEMA = 1   # catalog.json / workspaces.<board>.json / commit-targets.json: optional "version" (absent = 1)
+
+
+def read_site_json(path):
+    data = json.loads(Path(path).read_text())
+    if int(data.get('version', 1)) > SITE_SCHEMA:
+        raise LanesError(f'{path} is version {data["version"]}; this server understands {SITE_SCHEMA} — update the lanes checkout')
+    return data
+
+
+def build_registry(previous=None):
+    catalog = read_site_json(workspaces_dir() / 'catalog.json')['workspaces']
+    manifests = {}
+    container_names = set()
+    for workspace in catalog:
+        manifest = read_site_json(workspaces_dir() / workspace['manifest'])
+        manifests[workspace['id']] = manifest
+        for repo in manifest.get('repositories') or []:
+            container_names.add(repo.get('host'))
+    containers = refresh_containers(name for name in container_names if name)
+    previous_by_id = {w['id']: w for w in (previous or {}).get('workspaces', [])}
+    workspaces = []
+    used_ids = set()
+    for workspace in catalog:
+        manifest = manifests[workspace['id']]
+        entry = {'id': _require(IDENT, workspace['id'], 'workspace id'), 'title': workspace['title'],
+                 'cwd': _workspace_cwd(manifest), 'errors': []}
+        try:
+            lanes = _workspace_lanes(manifest, containers)
+        except (LanesError, OSError, ValueError, KeyError) as error:
+            # Never lose a working board because one registry is momentarily invalid.
+            entry['errors'].append(str(error))
+            lanes = (previous_by_id.get(workspace['id']) or {}).get('lanes', [])
+            entry['stale'] = True
+        entry['container'] = (lanes[0]['container'] if lanes else
+                              (manifest.get('repositories') or [{}])[0].get('host', ''))
+        for lane in lanes:
+            if 'id' not in lane:  # lanes carried over from a previous registry keep their ids
+                base = f"{entry['id']}--{slug(lane['name'])}"
+                lane_id, n = base, 2
+                while lane_id in used_ids:
+                    lane_id, n = f'{base}-{n}', n + 1
+                lane['id'] = lane_id
+            used_ids.add(lane['id'])
+        extras = []
+        entry['discovery_roots'] = manifest.get('discoveryRoots') or []
+        entry['lanes'] = lanes
+        entry['extras'] = extras
+        workspaces.append(entry)
+    # One shared tool tab: the Throttle monitor of the container that hosts most boards.
+    hosts = [(m.get('monitor') or {}).get('host') for m in manifests.values() if (m.get('monitor') or {}).get('host')]
+    tools = []
+    if hosts:
+        tools.append({'id': 'tools--throttle-monitor', 'view': '_throttle', 'tab': 'Throttle', 'name': 'Throttle Monitor',
+                      'holder': 'exec', 'exec': 'monitor', 'container': max(set(hosts), key=hosts.count),
+                      'cwd': CONTAINER_HOME, 'color': None, 'icon': '📊'})
+    return {'version': 1, 'generated_at': time.time(), 'containers': containers, 'workspaces': workspaces, 'tools': tools}
+
+
+def write_resolve_files(registry):
+    """One small line-oriented file per lane so POSIX-sh viewers never parse JSON or eval data."""
+    directory = STATE / 'resolve'
+    directory.mkdir(parents=True, exist_ok=True)
+    wanted = set()
+    for tool in registry.get('tools', []):
+        # A tool tab is a view with a fixed target: views/<device>/<view>.main falls back to defaults/<view>.
+        atomic_write(STATE / 'defaults' / tool['view'], tool['id'] + '\n')
+    for workspace in registry['workspaces'] + [{'lanes': registry.get('tools', []), 'extras': []}]:
+        for lane in workspace['lanes'] + workspace['extras']:
+            wanted.add(lane['id'])
+            if lane['holder'] == 'tmux':
+                fields = ['tmux', lane['container'], lane['tmux']['socket'], lane['tmux']['session']]
+            elif lane['holder'] == 'zmx':
+                fields = ['zmx', lane['container'], lane['zmx']['name'], lane['zmx'].get('version', '')]
+            else:
+                fields = ['exec', lane['container'], lane['exec'], lane.get('cwd', CONTAINER_HOME)]
+            atomic_write(directory / lane['id'], '\n'.join(fields + [lane['name']]) + '\n')
+    for stale in directory.iterdir():
+        if stale.name not in wanted and not stale.name.startswith('.'):
+            stale.unlink()
+
+
+def export_container_registries(registry):
+    """/home/coder/.lz/registry.json inside each container (written through the volume path): what `lane open`
+    needs — holder, exact target, create recipe, folder. Only where the lane contract is installed."""
+    per_container = {}
+    for workspace in registry['workspaces']:
+        for lane in workspace['lanes']:
+            per_container.setdefault(lane['container'], {})[lane['id']] = {
+                'name': lane['name'], 'ws': workspace['id'], 'holder': lane['holder'], 'tmux': lane.get('tmux'),
+                'zmx': lane.get('zmx'), 'create': lane.get('create'), 'folder': lane.get('folder')}
+    written = []
+    for container, lanes in per_container.items():
+        home = (registry['containers'].get(container) or {}).get('home')
+        if home and (Path(home) / '.lz/bin/lane').exists():
+            atomic_write(Path(home) / '.lz/registry.json',
+                         json.dumps({'version': 1, 'generated_at': registry['generated_at'], 'lanes': lanes},
+                                    ensure_ascii=False, indent=1) + '\n', mode=0o644)
+            written.append(container)
+    return written
+
+
+def load_registry():
+    registry = read_json(STATE / 'registry.json')
+    if not registry:
+        raise LanesError('No registry yet: run `lanes sync`')
+    if int(registry.get('version', 1)) > 1:
+        raise LanesError('registry.json was written by a newer lanes: update this checkout, then `lanes sync`')
+    return registry
+
+
+def find_lane(registry, lane_id):
+    status = read_json(STATE / 'status.json', {}) or {}
+    for workspace in registry['workspaces']:
+        discovered = (status.get('unregistered') or {}).get(workspace['id'], [])
+        for lane in workspace['lanes'] + workspace['extras'] + discovered:
+            if lane['id'] == lane_id:
+                return workspace, lane
+    raise LanesError(f'Unknown lane: {lane_id}')