@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/libexec/guard.py

@@ -14,7 +14,9 @@ allow-list — so that one of them is the victim instead. A build can be re-run;
 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).
+This module is also where tmpscan.py gets the container's pids from (Env, container_pid, cgroup_pids), and where
+statusd gets its live tmux servers from (tmux_servers_by_container). Importing it has no side effect: the pass runs
+only under `__main__`.
 """
 import os
 import signal
@@ -137,6 +139,30 @@ def tmux_servers(env, pid):
     return found
 
 
+def tmux_servers_by_container(env, containers, errors=None):
+    """{container: {socket name: host pid}} for statusd's live-server set (plan Task 16), from each container's OWN
+    cgroup — never a host-wide `ps`. `containers` is statusd's {name: info}; the init pid is `info['pid']` (statusd
+    keeps it current from /proc), not the pid file `container_pid` reads.
+
+    A container with no init pid (down, or never answered for) runs no servers: it is left out. A container whose
+    recorded pid cannot be walked — no such /proc entry, not a docker cgroup, not a namespace init (a recycled pid)
+    — maps to None: nobody knows which servers it runs, and the caller must not conclude that any of them is gone.
+    `errors`, when given, receives {container: why} for each such None, so the caller can NAME the container whose
+    pid broke the read (the None alone said only that some container did)."""
+    found = {}
+    for name, info in containers.items():
+        pid = (info or {}).get('pid')
+        if not pid:
+            continue
+        try:
+            found[name] = tmux_servers(env, int(pid))
+        except (L.LanesError, OSError, ValueError) as error:
+            found[name] = None
+            if errors is not None:
+                errors[name] = f'pid {pid}: {error}'
+    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

package/payload/lanes/libexec/lanes_lib.py

@@ -6,10 +6,14 @@ Safety rules encoded here (see docs/ARCHITECTURE.md):
   * 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 contextlib
+import fcntl
 import hashlib
 import json
 import os
 import re
+import shlex
+import signal
 import subprocess
 import tempfile
 import time
@@ -115,6 +119,28 @@ def atomic_write(path, text, mode=0o600):
         raise
 
 
+def atomic_write_if_changed(path, text, mode=0o600):
+    """atomic_write, skipped when the file already holds exactly `text` -> True when it wrote. Readers that reload
+    on mtime (statusd and notify on registry.json, every sidebar) then do not wake for a projection that did not
+    change, and the timer-driven sync stops rewriting the container volumes every two minutes."""
+    try:
+        if Path(path).read_text() == text:
+            return False
+    except (OSError, ValueError):
+        pass
+    atomic_write(path, text, mode)
+    return True
+
+
+def _same_json(path, document, ignore=('generated_at',)):
+    """True when `path` holds `document` minus the `ignore` keys (a timestamp alone is not a change)."""
+    old = read_json(path)
+    if not isinstance(old, dict):
+        return False
+    return ({k: v for k, v in old.items() if k not in ignore} ==
+            {k: v for k, v in json.loads(json.dumps(document)).items() if k not in ignore})
+
+
 def read_json(path, default=None):
     try:
         return json.loads(Path(path).read_text())
@@ -122,6 +148,53 @@ def read_json(path, default=None):
         return default
 
 
+def show_lane(view_dir, workspace, slot, lane_id):
+    """Point one viewport at a lane — the one implementation behind the sidebar's open_lane and `lanes next|prev`
+    (plan Task 19): write `<view_dir>/<workspace>.<slot>.target` atomically, then SIGUSR1 the process the viewport's
+    `.pid` file names, only when its /proc cmdline says it is a view.sh (a recycled pid is never signalled).
+    -> True when a view.sh was woken; False when none runs yet (the target is written either way: a view.sh that
+    starts later reads it)."""
+    target_file = os.path.join(view_dir, f'{workspace}.{slot}.target')
+    os.makedirs(view_dir, exist_ok=True)
+    tmp = target_file + f'.{os.getpid()}.tmp'
+    with open(tmp, 'w') as handle:
+        handle.write(lane_id + '\n')
+    os.replace(tmp, target_file)
+    try:
+        with open(os.path.join(view_dir, f'{workspace}.{slot}.pid')) as handle:
+            pid = int(handle.read().strip())
+        with open(os.path.join(proc_root(), str(pid), 'cmdline'), 'rb') as handle:
+            if b'view.sh' not in handle.read():
+                return False
+        os.kill(pid, signal.SIGUSR1)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def clean_seen(document):
+    """DM-LANES-CLIENT-SEEN as read: string keys with numeric values only (anything else is ignored)."""
+    return {k: v for k, v in (document.items() if isinstance(document, dict) else ())
+            if isinstance(k, str) and isinstance(v, (int, float))}
+
+
+def record_seen(path, lane_id, since, known, mine=None):
+    """Mark `lane_id` opened now on this device (DM-LANES-CLIENT-SEEN): the file on disk merged with `mine` (the
+    caller's in-memory marks; the later mark per lane wins, so the per-workspace sidebars of one device and
+    `lanes next|prev` never clobber each other), bounded to the lane ids in `known` (what status.json lists), the
+    mark at least the agent's `since`. Written atomically; an unwritable file is not an error. -> the merged dict."""
+    seen = clean_seen(read_json(path))
+    for key, value in (mine or {}).items():
+        seen[key] = max(value, seen.get(key, value))
+    seen = {k: v for k, v in seen.items() if k in known}
+    seen[lane_id] = max(time.time(), since if isinstance(since, (int, float)) else 0)
+    try:
+        atomic_write(Path(path), json.dumps(seen, sort_keys=True) + '\n')
+    except OSError:
+        pass
+    return seen
+
+
 def slug(text):
     text = unicodedata.normalize('NFKD', text).encode('ascii', 'ignore').decode()
     text = re.sub(r'[^A-Za-z0-9]+', '-', text).strip('-').lower()
@@ -174,36 +247,78 @@ 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)
+INSPECT_FORMAT = ('{{.Name}}\t{{.State.Pid}}\t{{range .Mounts}}{{if eq .Destination "' + CONTAINER_HOME +
+                  '"}}{{.Source}}{{end}}{{end}}')
+_GONE = re.compile(r'no such (?:object|container): (\S+)', re.I)
+
+
+def containers_info(names):
+    """{name: {pid, home, running}} for every container in ONE `docker inspect` (it was two spawns per container
+    per sync). A name docker ANSWERED does not exist maps to None; a name docker said nothing about is left out (the
+    caller must not conclude anything about it). Raises LanesError when docker gave no answer at all.
+
+    "Error: No such container/object: <name>" (after a `docker rm`) is an answer ABOUT that container. Any other
+    failure — daemon unreachable or busy, fork refused, permission — says nothing about it, whatever the exit code.
+
+    `--type container`: an image or volume that shares a name would otherwise be inspected, and its missing
+    `.State` would fail the template for the whole batch. Found containers are printed (one line each, keyed by
+    `.Name`) even when docker exits 1 because another name is gone."""
+    names = sorted(set(names))
+    for name in names:
+        if not IDENT.match(name):
+            raise LanesError(f'Invalid container name: {name}')
+    if not names:
+        return {}
+    label = 'docker inspect ' + ' '.join(names)
+    rc, out, err = run_bounded(['docker', 'inspect', '--type', 'container', '-f', INSPECT_FORMAT, *names], 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()
+        raise LanesError(f'{label}: no answer within 20 s')
+    result = {}
+    for line in out.splitlines():
+        parts = line.split('\t')
+        if len(parts) != 3 or parts[0].lstrip('/') not in names:
+            continue
+        try:
+            pid = int(parts[1] or 0)
+        except ValueError:
+            continue
+        result[parts[0].lstrip('/')] = {'pid': pid, 'home': parts[2].strip(), 'running': pid > 0}
+    for match in _GONE.finditer(err):
+        if match.group(1) in names and match.group(1) not in result:
+            result[match.group(1)] = None
+    if rc and not result:
+        # Daemon unreachable or busy, fork refused, permission: nothing was said about any container.
+        raise LanesError(f'{label}: {err.strip()}')
+    return result
 
 
 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}
+    """Init pid and host path of the container's /home/coder volume (one name of `containers_info`)."""
+    found = containers_info([container])
+    if container not in found:
+        raise LanesError(f'docker inspect {container}: no answer about it')
+    if found[container] is None:
+        raise NoSuchContainer(f'docker inspect {container}: no such container')
+    return found[container]
 
 
 def refresh_containers(names):
     previous = read_json(STATE / 'containers.json', {}) or {}
     info = {}
-    for name in sorted(set(names)):
+    names = sorted(set(names))
+    try:   # ONE docker spawn for every container; an invalid name stays that name's error, not the batch's
+        answers, failure = containers_info([n for n in names if IDENT.match(n)]), None
+    except (LanesError, subprocess.SubprocessError, ValueError) as error:
+        answers, failure = {}, error
+    for name in names:
         try:
-            info[name] = container_info(name)
+            if not IDENT.match(name):
+                raise LanesError(f'Invalid container name: {name}')
+            if name not in answers:
+                raise failure or LanesError(f'docker inspect {name}: no answer about it')
+            if answers[name] is None:
+                raise NoSuchContainer(f'docker inspect {name}: no such container')
+            info[name] = answers[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.
@@ -219,8 +334,8 @@ def refresh_containers(names):
             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')
+        atomic_write_if_changed(STATE / 'containers' / f'{name}.pid', f"{info[name]['pid']}\n")
+    atomic_write_if_changed(STATE / 'containers.json', json.dumps(info, indent=2) + '\n')
     return info
 
 
@@ -235,6 +350,36 @@ def host_path(info, container_path):
     return Path(info['home']) / container_path[len(CONTAINER_HOME) + 1:]
 
 
+# A markdown path as a lane prints it: not glued to a word or a `/` on its left, `.md` ending at a word boundary
+# (`foo.md5`, `c.mdx` are not markdown). `lanes preview` (plan Task 15) offers what this finds.
+MARKDOWN_PATH = re.compile(r'(?<![\w/])(?:\.{0,2}/)?[\w./-]+\.md\b')
+
+
+def markdown_candidates(text, cwd):
+    """The in-container paths of the markdown files `text` (a lane's scrollback) names, resolved against the lane's
+    `cwd`, de-duplicated with each path at its NEWEST position (oldest first, newest last). A match right after a `:`
+    is the path part of a URL (`https://host/a.md`) and is skipped; `~/x.md` is under the container home; a relative
+    path needs an absolute `cwd`. Pure: whether a path exists is the caller's question."""
+    found = []
+    for match in MARKDOWN_PATH.finditer(text):
+        raw, before = match.group(0), text[match.start() - 1:match.start()]
+        if before == ':' or raw.startswith('//'):
+            continue
+        if before == '~' and raw.startswith('/'):
+            raw = CONTAINER_HOME + raw
+        if not raw.startswith('/'):
+            if not cwd.startswith('/'):
+                continue
+            raw = cwd.rstrip('/') + '/' + raw
+        path = os.path.normpath(raw)
+        if not SAFE_PATH.match(path):
+            continue
+        if path in found:
+            found.remove(path)
+        found.append(path)
+    return found
+
+
 def tmux_socket(info, socket_name):
     return f"/proc/{info['pid']}/root/tmp/tmux-{CONTAINER_UID}/{socket_name}"
 
@@ -397,6 +542,26 @@ def read_health(state_dir=None):
 
 # ------------------------------------------------------------------ registry
 
+@contextlib.contextmanager
+def registry_lock(timeout=5):
+    """Serialize sync, registration and close across device sidebars and the timer."""
+    STATE.mkdir(parents=True, exist_ok=True)
+    with (STATE / 'registry.lock').open('a') as handle:
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise LanesError('Workspace sync is busy; try again shortly')
+                time.sleep(0.05)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
 def _require(pattern, value, label):
     if not isinstance(value, str) or not pattern.match(value):
         raise LanesError(f'Invalid {label}: {value!r}')
@@ -467,6 +632,8 @@ def _workspace_lanes(manifest, containers):
             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
+            # Keyed by the DECLARED (unprefixed) terminal name; written by session_actions.rename_registered.
+            # The override changes `name` only: the id derives from `registry_name` (lane_id_for).
             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',
@@ -499,8 +666,206 @@ def read_site_json(path):
     return data
 
 
-def build_registry(previous=None):
+def manifest_path(workspace_id):
+    """The `workspaces.<board>.json` that build_registry opens for this board (resolved through catalog.json)."""
     catalog = read_site_json(workspaces_dir() / 'catalog.json')['workspaces']
+    workspace = next((w for w in catalog if w.get('id') == workspace_id), None)
+    if workspace is None:
+        raise LanesError(f'Workspace {workspace_id!r} is not in catalog.json')
+    return workspaces_dir() / workspace['manifest']
+
+
+def lane_id_for(workspace_id, lane):
+    """The stable id: workspace + slug of the DECLARED terminal name. A display override (`displayNames`)
+    changes `name`, never the id, or every resolve file, view target and `lane open <id>` would break."""
+    return f"{workspace_id}--{slug(lane.get('registry_name') or lane['name'])}"
+
+
+# The proxy's `x-throttle-trace` charset and cap (src/proxy.rs): a lane trace outside it would be dropped there.
+TRACE = re.compile(r'[A-Za-z0-9._/-]{1,256}')
+
+
+def lane_trace(lane_id, ws):
+    """`lanes/<ws>/<id>` — the trace a lane's agents send as `x-throttle-trace`; None if the proxy would reject it."""
+    if not isinstance(ws, str) or not isinstance(lane_id, str):
+        return None
+    trace = f'lanes/{ws}/{lane_id}'
+    return trace if TRACE.fullmatch(trace) else None
+
+
+def canonical_recipe(lane_id, ws, socket, session, folder, cmd='bash -l'):
+    """The one create recipe that gives a new tmux lane its identity: LANE_ID / LANE_WS for scripts and hooks, the
+    lanes/<ws>/<id> trace for Throttle (ANTHROPIC_CUSTOM_HEADERS for Claude Code, THROTTLE_TRACE for the rest).
+    `tmux new -A` attaches when the session already exists, so the env lands only on a real create — never through
+    `set-environment`, which would leak into unrelated windows. `cmd` is a shell command string, appended as is."""
+    trace = lane_trace(lane_id, ws)
+    if trace is None:
+        raise LanesError(f'Invalid lane trace: lanes/{ws}/{lane_id} (allowed: A-Z a-z 0-9 . _ - /, at most 256)')
+    _require(IDENT, socket, 'tmux socket')
+    _require(TMUX_SESSION, session, 'tmux session')
+    if not isinstance(folder, str) or not folder.startswith('/'):
+        raise LanesError(f'Invalid lane folder: {folder!r}')
+    if not isinstance(cmd, str) or not cmd.strip():
+        raise LanesError('Invalid lane command')
+    header = shlex.quote(f'x-throttle-trace: {trace}')
+    return (f'tmux -L {shlex.quote(socket)} new -ADs {shlex.quote(session)} -c {shlex.quote(folder)} '
+            f'-e LANE_ID={lane_id} -e LANE_WS={ws} -e ANTHROPIC_CUSTOM_HEADERS={header} '
+            f'-e THROTTLE_TRACE={trace} {cmd}')
+
+
+# What `lane open` gets when it runs a lane's recorded `create` for a lane that does not exist (plan Task 18; the
+# shapes measured in the boards' terminals.json on 2026-10-03). `lanes doctor` counts the lanes per class.
+#   idempotent    a tmux new-session with -A: creates the lane, or attaches when it exists (the canonical recipe)
+#   attach-only   tmux attach without any new-session: a lane that is gone stays gone
+#   null          no recipe at all
+#   external      anything else (a script, a new-session without -A, unparseable): run as written, unvouched for
+#   retired-path  names the retired in-container coder-launch config, which no longer creates anything
+# attach-only, null and retired-path are what `lanes cursor-sync --canonicalize` replaces (cursor_sync.needs_canonical
+# reads them through this function, says why per lane, and also catches an external recipe whose script is missing in
+# the container).
+RECIPE_CLASSES = ('idempotent', 'attach-only', 'null', 'external', 'retired-path')
+RETIRED_RECIPE_PATH = '.config/coder-launch'
+_RECIPE_ATTACH = {'attach-session'[:n] for n in range(1, 15)}    # tmux takes any unique prefix (+ `attach`)
+_RECIPE_NEW = {'new-session'[:n] for n in range(3, 12)}
+_TMUX_GLOBAL_ARGS = {'-L', '-S', '-f', '-T', '-c'}
+_NEW_SESSION_ARGS = set('cefFnstxy')                           # new-session options that take a value
+
+
+def _recipe_word_lists(text, depth=3):
+    """The shell words of a recipe as one list, then one list per quoted word that holds a command of its own
+    (`bash -lc 'tmux … new …'`), each kept apart so a nested string never lands among an outer command's options;
+    None = unparseable."""
+    try:
+        words = shlex.split(text)
+    except ValueError:
+        return None
+    lists = [words]
+    for word in words:
+        if depth and any(c.isspace() for c in word):
+            lists += _recipe_word_lists(word, depth - 1) or []
+    return lists
+
+
+def _tmux_commands(lists):
+    """[(verb, the words after it)] of every tmux invocation in these word lists (its global options skipped)."""
+    found = []
+    for words in lists:
+        for i, word in enumerate(words):
+            if word == 'tmux' or word.endswith('/tmux'):
+                j = i + 1
+                while j < len(words) and words[j].startswith('-'):
+                    j += 2 if words[j] in _TMUX_GLOBAL_ARGS else 1
+                if j < len(words):
+                    found.append((words[j], words[j + 1:]))
+    return found
+
+
+def _new_session_options(words):
+    """[(letter, value or None)] of a new-session's options, getopt-style: `-ADs x` gives A, D, (s, x); an option's
+    VALUE (the `A=1` of `-e A=1`, the `A` of `-s A`) is never read as flags. Stops at the first word that is no
+    option (the command)."""
+    options, i = [], 0
+    while i < len(words) and words[i].startswith('-') and len(words[i]) > 1 and words[i] != '--':
+        word, i = words[i], i + 1
+        for k, letter in enumerate(word[1:]):
+            if letter not in _NEW_SESSION_ARGS:
+                options.append((letter, None))
+                continue
+            value = word[k + 2:]
+            if not value:           # the value is the next word
+                value = words[i] if i < len(words) else ''
+                i += 1
+            options.append((letter, value))
+            break
+    return options
+
+
+def classify_recipe(create):
+    """One of RECIPE_CLASSES for a lane's recorded create recipe (None, a string, or anything a registry holds)."""
+    if not isinstance(create, str) or not create.strip():
+        return 'null'
+    if RETIRED_RECIPE_PATH in create:
+        return 'retired-path'
+    lists = _recipe_word_lists(create)
+    if lists is None:
+        return 'external'
+    commands = _tmux_commands(lists)
+    if any(verb in _RECIPE_NEW and ('A', None) in _new_session_options(rest) for verb, rest in commands):
+        return 'idempotent'
+    if any(verb in _RECIPE_ATTACH for verb, _ in commands) and not any(verb in _RECIPE_NEW for verb, _ in commands):
+        return 'attach-only'
+    return 'external'
+
+
+def recipe_identity(create):
+    """Does the recipe give the lane it creates its identity — an `-e LANE_ID=…` on a tmux new-session (the
+    canonical recipe's flags, DEF-1478)? An env prefix (`LANE_ID=x tmux …`) does not count: it reaches the tmux
+    client, never the session."""
+    lists = _recipe_word_lists(create) if isinstance(create, str) else None
+    return any(verb in _RECIPE_NEW and any(letter == 'e' and value.startswith('LANE_ID=')
+                                           for letter, value in _new_session_options(rest))
+               for verb, rest in _tmux_commands(lists or []))
+
+
+def ssh_workspaces(catalog):
+    """Native tabs for sessions on hosts outside the workspace containers; no network calls."""
+    def require(pattern, value, label):
+        if not isinstance(value, str) or not pattern.fullmatch(value):
+            raise LanesError(f'Invalid {label}: {value!r}')
+        return value
+
+    result = []
+    ids = {w['id'] for w in catalog['workspaces']}
+    titles = {w['title'] for w in catalog['workspaces']} | {'Host', 'Throttle'}
+    host_pattern = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_.-]*(?:@[A-Za-z0-9_][A-Za-z0-9_.-]*)?$')
+    for source in catalog.get('sshWorkspaces', []):
+        ident = require(IDENT, source.get('id'), 'SSH workspace id')
+        title = _title(source.get('title'))
+        if ident in ids or title in titles:
+            raise LanesError('Duplicate SSH workspace id or title')
+        ids.add(ident)
+        titles.add(title)
+        host = require(host_pattern, source.get('host'), 'SSH host')
+        command = require(SAFE_PATH, source.get('command'), 'SSH command path')
+        if '..' in command.split('/'):
+            raise LanesError('Unsafe SSH command path')
+        panes, pane_ids = [], set()
+        for pane in source.get('panes', []):
+            pane_id = require(IDENT, pane.get('id'), 'SSH pane id')
+            if pane_id in pane_ids:
+                raise LanesError('Duplicate SSH pane id')
+            pane_ids.add(pane_id)
+            panes.append({'id': pane_id, 'name': _title(pane.get('name'))})
+        layout = source.get('layout', 'split')
+        if layout not in ('split', 'lanes'):
+            raise LanesError('SSH workspace layout must be split or lanes')
+        limit = 32 if layout == 'lanes' else 3
+        if not 1 <= len(panes) <= limit:
+            raise LanesError(f'An SSH workspace needs one to {limit} panes')
+        position = source.get('position', 'before-host')
+        if position not in ('workspace', 'before-host'):
+            raise LanesError('SSH workspace position must be workspace or before-host')
+        result.append({'id': ident, 'title': title, 'host': host, 'command': command,
+                       'panes': panes, 'layout': layout, 'position': position})
+    return result
+
+
+def ssh_workspace_board(workspace):
+    """Use the standard sidebar/view layout for fixed, attach-only remote lanes."""
+    return {'id': workspace['id'], 'title': workspace['title'], 'container': '',
+            'cwd': '', 'errors': [], 'discovery_roots': [],
+            'attach_only': True, 'position': workspace.get('position', 'before-host'),
+            'lanes': [{'id': f"{workspace['id']}--{pane['id']}", 'name': pane['name'],
+                       'holder': 'ssh', 'container': '', 'color': None, 'icon': '💻',
+                       'focus': index == 0,
+                       'ssh': {'host': workspace['host'], 'command': workspace['command'], 'pane': pane['id']}}
+                      for index, pane in enumerate(workspace['panes'])]}
+
+
+def build_registry(previous=None):
+    site = read_site_json(workspaces_dir() / 'catalog.json')
+    remote_tabs = ssh_workspaces(site)
+    catalog = site['workspaces']
     manifests = {}
     container_names = set()
     for workspace in catalog:
@@ -527,17 +892,17 @@ def build_registry(previous=None):
                               (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'])}"
+                base = lane_id_for(entry['id'], lane)
                 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)
+    workspaces += [ssh_workspace_board(w) for w in remote_tabs if w['layout'] == 'lanes']
+    remote_tabs = [w for w in remote_tabs if w['layout'] != 'lanes']
     # 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 = []
@@ -545,7 +910,33 @@ def build_registry(previous=None):
         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}
+    import registrations
+    return registrations.apply({'version': 1, 'generated_at': time.time(), 'containers': containers,
+                                'workspaces': workspaces, 'tools': tools, 'ssh_workspaces': remote_tabs})
+
+
+def publish_registry(registry):
+    """Publish a prepared registry while holding registry_lock(). Every projection is written only when its content
+    changed (plan Task 17): `lanes sync` runs every 2 minutes and a registry.json rewritten with nothing but a new
+    `generated_at` made statusd, notify and every sidebar reload it. An unchanged registry.json therefore keeps its
+    OLD `generated_at`; the sync itself is recorded in `registry.synced`, which only `lanes doctor` reads."""
+    write_resolve_files(registry)
+    export_container_registries(registry)
+    for workspace in registry['workspaces']:
+        focus = next((lane for lane in workspace['lanes'] if lane.get('focus')), None)
+        first = focus or (workspace['lanes'][0] if workspace['lanes'] else None)
+        atomic_write_if_changed(STATE / 'defaults' / workspace['id'], (first['id'] if first else '!empty') + '\n')
+    if not _same_json(STATE / 'registry.json', registry):
+        atomic_write(STATE / 'registry.json', json.dumps(registry, indent=1, ensure_ascii=False) + '\n')
+    atomic_write(STATE / 'registry.synced', f"{registry['generated_at']}\n")
+
+
+def registry_synced_at():
+    """When a sync last published (or confirmed unchanged) the registry; 0 when no sync has recorded it."""
+    try:
+        return float((STATE / 'registry.synced').read_text().strip())
+    except (OSError, ValueError):
+        return 0.0
 
 
 def write_resolve_files(registry):
@@ -555,17 +946,19 @@ def write_resolve_files(registry):
     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']:
+        atomic_write_if_changed(STATE / 'defaults' / tool['view'], tool['id'] + '\n')
+    for workspace in registry['workspaces'] + [{'lanes': registry.get('tools', [])}]:
+        for lane in workspace['lanes']:
             wanted.add(lane['id'])
             if lane['holder'] == 'tmux':
                 fields = ['tmux', lane['container'], lane['tmux']['socket'], lane['tmux']['session']]
+            elif lane['holder'] == 'ssh':
+                fields = ['ssh', lane['ssh']['host'], lane['ssh']['command'], lane['ssh']['pane']]
             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')
+            atomic_write_if_changed(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()
@@ -577,6 +970,8 @@ def export_container_registries(registry):
     per_container = {}
     for workspace in registry['workspaces']:
         for lane in workspace['lanes']:
+            if not lane.get('container'):
+                continue
             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')}
@@ -584,9 +979,10 @@ def export_container_registries(registry):
     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)
+            document = {'version': 1, 'generated_at': registry['generated_at'], 'lanes': lanes}
+            if not _same_json(Path(home) / '.lz/registry.json', document):   # `generated_at` alone is no change
+                atomic_write(Path(home) / '.lz/registry.json',
+                             json.dumps(document, ensure_ascii=False, indent=1) + '\n', mode=0o644)
             written.append(container)
     return written
 
@@ -603,8 +999,12 @@ def load_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:
+        for lane in workspace['lanes']:
+            if lane['id'] == lane_id:
+                return workspace, lane
+    # Registration can move a session before the next observer cycle clears its previous workspace.
+    for workspace in registry['workspaces']:
+        for lane in (status.get('unregistered') or {}).get(workspace['id'], []):
             if lane['id'] == lane_id:
                 return workspace, lane
     raise LanesError(f'Unknown lane: {lane_id}')