@vibelord/lanes 1.1.1 → 1.2.0

package/payload/lanes/libexec/lanes_lib.py

@@ -11,10 +11,14 @@ import fcntl
 import hashlib
 import json
 import os
+import posixpath
 import re
+import secrets
 import shlex
 import signal
+import stat
 import subprocess
+import sys
 import tempfile
 import time
 import unicodedata
@@ -23,6 +27,144 @@ 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'))
+PACKAGE_STAMP = '.lanes-package.json'   # npm/lanes/bin/lanes-install.mjs `STAMP`, written into every tree it stages
+RUN_DIR = 'run'                         # STATE/run/<name>.tree: the tree each long-running process started from
+CURRENT_LINK = '.local/share/lanes/current'   # under the HOME directory, never $XDG_DATA_HOME: install/services.py
+
+
+def current_link(home=None):
+    """Where install/services.py writes the `current` link: `<home>/.local/share/lanes/current` (default: this
+    account's home; raises KeyError/RuntimeError with no HOME and no passwd entry). The npm wrapper's prune protects the
+    same path (npm/lanes/lib/plan.mjs `currentLink`); `current_tree` and `lanes version` read it."""
+    return (Path(home) if home is not None else Path.home()) / CURRENT_LINK
+
+
+def staged_tree(path):
+    """Whether `path` is a tree the npm wrapper staged, not a checkout: it sits in the default pkg root
+    (`…/pkg/<version>`), or it carries the wrapper's stamp (PACKAGE_STAMP, a regular file lanes-install.mjs stage()
+    writes into every tree it stages — under `$LANES_PKG_ROOT/<version>` too, whatever that directory is called;
+    DEF-1757). A checkout has neither."""
+    path = Path(path)
+    if path.parent.name == 'pkg':
+        return True
+    try:
+        return (path / PACKAGE_STAMP).is_file()
+    except OSError:                      # an unreadable directory says nothing either way: not staged
+        return False
+
+
+def current_links(repo, home=None):
+    """Where the `current` link of the staged tree `repo` can be, in the order current_tree and installed_tree look:
+    beside the pkg root (`<pkg>/../current`, the default `…/pkg/<version>` layout only), then under the home
+    (current_link; left out with no HOME and no passwd entry)."""
+    repo = Path(repo)
+    links = [repo.parent.parent / 'current'] if repo.parent.name == 'pkg' else []
+    try:
+        links.append(current_link(home))
+    except (KeyError, RuntimeError):     # no HOME and no passwd entry: the pkg-root candidate alone
+        pass
+    return links
+
+
+def current_tree(repo=None, home=None):
+    """The path `repo` is INSTALLED under — the one layouts, units and wrappers should embed (plan W9 U1): the `current`
+    link when `repo` is an npm-staged tree (`staged_tree`: `…/pkg/<version>`, or any `$LANES_PKG_ROOT/<version>` with
+    the wrapper's stamp) and the link resolves to exactly that tree; else `repo` itself — a checkout install, or a
+    staged tree the link no longer names (after an update an old tree must never hand out a link that now means
+    another version). REPO is always the RESOLVED tree, because __file__ is resolved through the link.
+
+    The link is where install/services.py writes it, `~/.local/share/lanes/current` from the home directory, and —
+    for the default `…/pkg/<version>` layout only — beside the pkg root (`<pkg>/../current`, the same path unless the
+    npm wrapper staged under $XDG_DATA_HOME, or the only candidate with no home). The link stays under the home either
+    way (the wrapper's prune protects the same link: npm/lanes/lib/plan.mjs `currentLink`); beside a `$LANES_PKG_ROOT`
+    of another name nothing manages a link, so none is looked for there."""
+    repo = Path(repo) if repo is not None else REPO
+    if not staged_tree(repo):
+        return repo
+    links = current_links(repo, home)
+    try:
+        target = repo.resolve()
+    except (OSError, RuntimeError):
+        return repo
+    for link in links:
+        try:
+            if link.resolve() == target:
+                return link
+        except (OSError, RuntimeError):  # a dangling link or a loop names no tree
+            continue
+    return repo
+
+
+CURRENT = current_tree()
+
+
+def installed_tree(repo=None, home=None):
+    """Where a running process re-reads the INSTALLED release (the sidebar's version note and self-swap, cockpit v3 V2
+    and U5): for a staged `repo` (default REPO), the first of its current_links that is a link — whatever tree it names
+    NOW, unlike current_tree, which collapses to `repo` once an update has flipped the link to another tree (that flip
+    is exactly what this reader must see); else `repo` itself: a checkout, or a staged tree no link stands beside, is
+    its own installed tree. lstat only: nothing is resolved here."""
+    repo = Path(repo) if repo is not None else REPO
+    if not staged_tree(repo):
+        return repo
+    for link in current_links(repo, home):
+        try:
+            if link.is_symlink():
+                return link
+        except OSError:
+            continue
+    return repo
+
+# The tree files a generated layout runs (bin/lanes layout_kdl, `lanes doctor` layouts_doctor), as `<tree>/<file>`.
+LAYOUT_FILES = ('libexec/sidebar', 'libexec/view.sh', 'holders/ssh.sh')
+
+
+def tree_file_at(words, name):
+    """The index of the first of a pane command's `words` that runs the tree file `name` (one of LAYOUT_FILES) of ANY
+    lanes tree, else None: an absolute path ending in `/<name>`. Since W9 U1 a layout names its files through CURRENT
+    (`…/current/<name>`), a layout built before names the `pkg/<version>` tree that built it, a checkout names itself —
+    and one session can hold panes of each after an update. They are the same pane, so a reader (device_sync's tab
+    identities, bin/lanes focused_view and stale_picker_layouts) matches the suffix, never one tree's full path; a
+    relative path, or a file that only ends like it (`/opt/myview.sh`), runs no tree file."""
+    suffix = '/' + name
+    return next((index for index, word in enumerate(words) if word.startswith('/') and word.endswith(suffix)), None)
+
+
+def tree_version(path):
+    """A tree's release, `<path>/VERSION` stripped; None when the file is absent, unreadable or empty. One open(), no
+    stat: the sidebar re-reads the installed tree's every 30 s through it (cockpit v3 V2), and its tick budget counts
+    stats."""
+    try:
+        with open(Path(path) / 'VERSION', encoding='utf-8') as handle:
+            text = handle.read().strip()
+    except (OSError, ValueError):        # ValueError: undecodable bytes
+        return None
+    return text or None
+
+
+def tree_stamp(path=None):
+    """The npm wrapper's stamp of a staged tree (default REPO), as {version, digest, commit}: each a string, else None.
+    None for a checkout (no stamp) and for a stamp that is not a JSON object."""
+    document = read_json(Path(path if path is not None else REPO) / PACKAGE_STAMP)
+    if not isinstance(document, dict):
+        return None
+    return {key: document[key] if isinstance(document.get(key), str) else None
+            for key in ('version', 'digest', 'commit')}
+
+
+def record_tree(name, state=None):
+    """Write `<state>/run/<name>.tree` (default STATE) = the tree this process runs from — str(REPO), the RESOLVED path,
+    and a newline — rewritten at every start, so its mtime is the start time. Each long-running process calls it once
+    when it starts (statusd, enrold, economy, notify, the Studio Host enable step, the sidebar); `lanes version` and
+    doctor compare the records with `current` (plan W9 V1, V3). -> the path written, or None when the state directory
+    cannot be written: a record is observation, never a reason for a daemon or a sidebar not to start."""
+    _require(IDENT, name, 'tree record name')
+    path = Path(state if state is not None else STATE) / RUN_DIR / f'{name}.tree'
+    try:
+        atomic_write(path, f'{REPO}\n')
+    except OSError:
+        return None
+    return path
 
 
 def workspaces_dir():
@@ -104,6 +246,20 @@ class LanesError(Exception):
     pass
 
 
+class ProjectionRefused(LanesError):
+    """A change a person made (register, rename) was SAVED and published everywhere except these containers' own
+    `~/.lz/registry.json` — `publish_registry`'s `[(container, why)]` (DEF-1796 refusals). The action that published
+    raises it so the person hears it at once: `lane open` / `lane-signal` in those containers still resolve against
+    the old projection, and the next timer sync only reports it to its journal. `result` is what the action returns
+    on success (the sidebar finishes its success path with it); `pending` is the sentence after `<what> saved; `."""
+
+    def __init__(self, what, refused, result=None):
+        self.what, self.refused, self.result = what, list(refused), result
+        self.pending = 'run lanes sync to finish publishing: ' + '; '.join(
+            f'container {container}: {why}' for container, why in self.refused)
+        super().__init__(f'{what} saved; {self.pending}')
+
+
 def atomic_write(path, text, mode=0o600):
     """Replace `path` with `text` atomically (temp file in the same directory, chmod, rename). `text` may be bytes:
     then it is written byte for byte, never through the locale's encoding (keys.py keeps foreign authorized_keys
@@ -138,9 +294,101 @@ def atomic_write_if_changed(path, text, mode=0o600):
     return True
 
 
+# Writing INTO a directory a container owns (LNS-32: statusd's `~/.lz/status.json`, written from the host through
+# /proc/<container init pid>/root; DEF-1796: `lanes sync`'s `~/.lz/registry.json`, through the home volume). The
+# container can plant anything there: an absolute symlink resolves against the HOST's root when the host follows it,
+# and a FIFO blocks a plain open-for-read forever. So the directory is walked with O_NOFOLLOW per component, the
+# compare read never follows a link or blocks, and the temp file is O_EXCL in the same directory, renamed over
+# whatever the name holds (rename replaces a link, it never writes through it).
+_DIR_FLAGS = os.O_RDONLY | os.O_DIRECTORY | getattr(os, 'O_CLOEXEC', 0)
+
+
+def _leaf(name):
+    """`name` when it is one directory entry (no `/`, not `.`/`..`/empty): every *_at helper resolves exactly one."""
+    if not isinstance(name, str) or not name or '/' in name or name in ('.', '..') or '\0' in name:
+        raise LanesError(f'Invalid path component: {name!r}')
+    return name
+
+
+def open_real_dir(base, parts):
+    """fd of `base`/<parts…>, every component in `parts` a REAL directory (a symlink is refused with OSError, never
+    followed). `base` itself is trusted and opened as given (it may be the /proc/<pid>/root magic link). The caller
+    closes the fd."""
+    fd = os.open(str(base), _DIR_FLAGS)
+    try:
+        for part in parts:
+            child = os.open(_leaf(part), _DIR_FLAGS | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = child
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def read_regular_at(dir_fd, name, limit):
+    """The bytes of `name` in `dir_fd` when it is a regular file of at most `limit` bytes, else None (absent, a
+    symlink, a FIFO or device, bigger). Never follows a link, never blocks on a FIFO (O_NONBLOCK on the open)."""
+    _leaf(name)
+    try:
+        fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, 'O_CLOEXEC', 0), dir_fd=dir_fd)
+    except OSError:
+        return None
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_size > limit:
+            return None
+        chunks, size = [], 0
+        while size <= limit:
+            chunk = os.read(fd, limit + 1 - size)
+            if not chunk:
+                break
+            chunks.append(chunk)
+            size += len(chunk)
+        return b''.join(chunks) if size <= limit else None
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+
+
+def atomic_write_if_changed_at(dir_fd, name, text, mode=0o600):
+    """`atomic_write_if_changed` inside an open directory (see `open_real_dir`) -> True when it wrote. `text` is str
+    (UTF-8) or bytes; the file is replaced only when it is not already a regular file holding exactly these bytes."""
+    data = text.encode() if isinstance(text, str) else text
+    if read_regular_at(dir_fd, name, len(data)) == data:
+        return False
+    atomic_write_at(dir_fd, name, data, mode)
+    return True
+
+
+def atomic_write_at(dir_fd, name, text, mode=0o600):
+    """`atomic_write` inside an open directory: an O_EXCL|O_NOFOLLOW temp file beside `name`, chmod, then a rename
+    that replaces whatever `name` is (a symlink or FIFO planted there is replaced, never followed or opened)."""
+    _leaf(name)
+    data = text.encode() if isinstance(text, str) else text
+    temporary = f'.{name}.{secrets.token_hex(6)}'
+    fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0),
+                 0o600, dir_fd=dir_fd)
+    try:
+        with os.fdopen(fd, 'wb') as handle:
+            handle.write(data)
+            os.fchmod(handle.fileno(), mode)
+        os.replace(temporary, name, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+    except BaseException:
+        try:
+            os.unlink(temporary, dir_fd=dir_fd)
+        except OSError:
+            pass
+        raise
+
+
 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)
+    return _same_document(read_json(path), document, ignore)
+
+
+def _same_document(old, document, ignore=('generated_at',)):
     if not isinstance(old, dict):
         return False
     return ({k: v for k, v in old.items() if k not in ignore} ==
@@ -178,6 +426,38 @@ def show_lane(view_dir, workspace, slot, lane_id):
         return False
 
 
+# DM-LANES-SIDEBAR-CMD (cockpit v3 S4): a key handed to a sidebar without typing it. Ctrl-Alt-/ and Ctrl-Alt-u
+# (zellij/config.kdl) walk the focus to the sidebar and run `lanes sidebar-key filter|upload --focused`, which writes
+# {"cmd": <one of SIDEBAR_KEYS>, "at": <epoch seconds>} to <view_dir>/<workspace>.sidebar.cmd; that workspace's sidebar
+# acts on each new file (reload()'s stamp, and before every read of keys). Writer and reader share these helpers.
+SIDEBAR_KEYS = ('filter', 'upload')
+SIDEBAR_KEY_FRESH = 10.0   # seconds: an older command (one a sidebar took before it restarted) is history, not a key
+
+
+def sidebar_key_path(view_dir, workspace):
+    return os.path.join(str(view_dir), f'{workspace}.sidebar.cmd')
+
+
+def send_sidebar_key(view_dir, workspace, key, now=None):
+    """Write one sidebar command atomically (0600). `key` must be one of SIDEBAR_KEYS."""
+    if key not in SIDEBAR_KEYS:
+        raise LanesError(f'unknown sidebar key {key!r} (one of {", ".join(SIDEBAR_KEYS)})')
+    at = time.time() if now is None else now
+    atomic_write(sidebar_key_path(view_dir, workspace), json.dumps({'cmd': key, 'at': at}) + '\n')
+
+
+def read_sidebar_key(path, now=None):
+    """The key a sidebar command file holds, or None: unreadable, not the v1 shape, an unknown key, or an `at` more
+    than SIDEBAR_KEY_FRESH seconds away from now."""
+    document = read_json(path)
+    if not isinstance(document, dict):
+        return None
+    key, at = document.get('cmd'), document.get('at')
+    if key not in SIDEBAR_KEYS or isinstance(at, bool) or not isinstance(at, (int, float)):
+        return None
+    return key if abs((time.time() if now is None else now) - at) <= SIDEBAR_KEY_FRESH else None
+
+
 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 ())
@@ -256,6 +536,9 @@ class NoSuchContainer(LanesError):
 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)
+# How long the one `docker inspect` of a sync may take before it counts as no answer. A bound other code sizes its
+# waits by (the sidebar's PENDING_S), so it is named here, where it is enforced.
+DOCKER_INSPECT_S = 20
 
 
 def containers_info(names):
@@ -276,9 +559,10 @@ def containers_info(names):
     if not names:
         return {}
     label = 'docker inspect ' + ' '.join(names)
-    rc, out, err = run_bounded(['docker', 'inspect', '--type', 'container', '-f', INSPECT_FORMAT, *names], 20)
+    rc, out, err = run_bounded(['docker', 'inspect', '--type', 'container', '-f', INSPECT_FORMAT, *names],
+                               DOCKER_INSPECT_S)
     if rc is None:
-        raise LanesError(f'{label}: no answer within 20 s')
+        raise LanesError(f'{label}: no answer within {DOCKER_INSPECT_S} s')
     result = {}
     for line in out.splitlines():
         parts = line.split('\t')
@@ -356,6 +640,21 @@ def host_path(info, container_path):
     return Path(info['home']) / container_path[len(CONTAINER_HOME) + 1:]
 
 
+def lane_core():
+    """container/lane_core.py — the in-container contract's shared helpers — as a module, one instance per process
+    (sys.modules, the same one `bin/lanes` loads for the agents' MCP entries): the host edits a container's
+    terminals.json with the very editor lane-mcp runs inside it (session_actions.unregister_declared, LNS-35)."""
+    import sys
+    module = sys.modules.get('lane_core')
+    if module is None:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location('lane_core', str(REPO / 'container' / 'lane_core.py'))
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        sys.modules['lane_core'] = module
+    return module
+
+
 # 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')
@@ -386,6 +685,116 @@ def markdown_candidates(text, cwd):
     return found
 
 
+# ------------------------------------------------------- container file system
+# `lanes edit` (W9 E2, LNS-96) looks at a lane's checkout through /proc/<init>/root (`root`). A symbolic link in there
+# is the container's: walked by the kernel from the host, an ABSOLUTE target would restart at the HOST's root (and
+# os.path.realpath reads /proc/<init>/root itself as `/`), so every path below is resolved one component at a time
+# with the container's root as `/`, and only a path whose every component is no link is opened.
+
+CONTROL_CHARS = re.compile(r'[\x00-\x1f\x7f]')
+SYMLINK_LIMIT = 40          # as the kernel's ELOOP bound
+GIT_FILE_LIMIT = 4096       # a .git link file or a commondir file is one short line
+
+
+def container_realpath(root, path):
+    """The absolute container path `path` names, every symbolic link resolved inside the container whose root
+    directory is `root` on the host: an absolute target restarts at `root`, `..` climbs from where a link led (the
+    kernel's walk, not string folding) and never above `/`. A component that does not exist (or cannot be read) is
+    kept as it is, like os.path.realpath(strict=False). Raises LanesError after SYMLINK_LIMIT links, and for a path
+    with a NUL byte (no file has one; os.readlink would raise ValueError)."""
+    if '\x00' in path:
+        raise LanesError('a path with a NUL byte names no file')
+    pending = [part for part in path.split('/') if part not in ('', '.')]
+    resolved, links = [], 0
+    while pending:
+        part = pending.pop(0)
+        if part == '..':
+            if resolved:
+                resolved.pop()
+            continue
+        try:
+            target = os.readlink(Path(root, *resolved, part))
+        except OSError:            # EINVAL: no link; ENOENT, EACCES: kept as it is
+            resolved.append(part)
+            continue
+        links += 1
+        if links > SYMLINK_LIMIT:
+            raise LanesError('too many symbolic links')
+        if target.startswith('/'):
+            resolved = []
+        pending = [p for p in target.split('/') if p not in ('', '.')] + pending
+    return '/' + '/'.join(resolved)
+
+
+def container_lstat(root, path):
+    """os.lstat of a RESOLVED container path (container_realpath) under `root`, or None for any OSError: a caller that
+    names the file it asked about never prints the error, which carries the host path (W9 E2: `.env.local`)."""
+    try:
+        return os.lstat(Path(root, path.lstrip('/')))
+    except (OSError, ValueError):   # ValueError: a NUL byte
+        return None
+
+
+def _container_line(root, path):
+    """The first line of the small regular file at the resolved container path `path`, trailing whitespace removed, or
+    None when it is missing, no regular file, a link, or unreadable. Never follows a link and never blocks on a FIFO."""
+    try:
+        fd = os.open(Path(root, path.lstrip('/')), os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC)
+    except (OSError, ValueError):
+        return None
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            return None
+        text = os.read(fd, GIT_FILE_LIMIT).decode('utf-8', 'replace')
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+    return (text.splitlines() or [''])[0].rstrip()
+
+
+def _main_checkout(root, gitdir, worktree):
+    """The main checkout of a linked worktree whose gitdir is `gitdir`: the folder holding the common `.git` its
+    `commondir` names (relative to the gitdir; git writes `../..`). No commondir (a submodule, a --separate-git-dir
+    checkout) or a common dir that is not a checkout's `.git` (a bare repository): the worktree is its own. The file is
+    the container's to write: one with a control character names no main checkout either."""
+    common = _container_line(root, container_realpath(root, posixpath.join(gitdir, 'commondir')))
+    if not common or CONTROL_CHARS.search(common):
+        return worktree
+    common = container_realpath(root, posixpath.join(gitdir, common))
+    if posixpath.basename(common) != '.git':
+        return worktree
+    main = posixpath.dirname(common)
+    found = container_lstat(root, main)
+    return main if found and stat.S_ISDIR(found.st_mode) else worktree
+
+
+def repo_roots(cwd, root):
+    """(worktree root, main checkout) of the git checkout the container path `cwd` is in, both resolved container paths,
+    read through `root` (/proc/<init>/root). Walks up from `cwd` to the first `.git`: a directory holding HEAD makes
+    that folder the top level and its own main checkout; a `.git` FILE (`gitdir: <path>`, relative to its folder or
+    absolute in the container) makes it a linked worktree whose gitdir's `commondir` leads to the main checkout
+    (_main_checkout). Raises LanesError for a cwd that is not an absolute path without control characters, a `.git`
+    file without a gitdir line (or with a control character in it), and no checkout up to `/`."""
+    if not isinstance(cwd, str) or not cwd.startswith('/') or CONTROL_CHARS.search(cwd):
+        raise LanesError('the lane has no usable working directory')
+    here = container_realpath(root, cwd)
+    while True:
+        dotgit = container_realpath(root, posixpath.join(here, '.git'))
+        found = container_lstat(root, dotgit)
+        if found and stat.S_ISDIR(found.st_mode) and os.path.lexists(Path(root, dotgit.lstrip('/'), 'HEAD')):
+            return here, here
+        if found and stat.S_ISREG(found.st_mode):
+            line = _container_line(root, dotgit) or ''
+            if not line.startswith('gitdir: ') or not line[8:] or CONTROL_CHARS.search(line):
+                raise LanesError(f'{posixpath.join(here, ".git")} is not a git link file')
+            gitdir = container_realpath(root, posixpath.join(here, line[8:]))
+            return here, _main_checkout(root, gitdir, here)
+        if here == '/':
+            raise LanesError(f'no git checkout in or above {cwd}')
+        here = posixpath.dirname(here)
+
+
 def tmux_socket(info, socket_name):
     return f"/proc/{info['pid']}/root/tmp/tmux-{CONTAINER_UID}/{socket_name}"
 
@@ -548,8 +957,11 @@ def read_health(state_dir=None):
 
 # ------------------------------------------------------------------ registry
 
+REGISTRY_LOCK_S = 5   # how long a sync, registration or close waits for the lock before "busy" (sizes PENDING_S)
+
+
 @contextlib.contextmanager
-def registry_lock(timeout=5):
+def registry_lock(timeout=REGISTRY_LOCK_S):
     """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:
@@ -568,6 +980,93 @@ def registry_lock(timeout=5):
             fcntl.flock(handle, fcntl.LOCK_UN)
 
 
+# ------------------------------------------------------------------ view sessions
+
+SESSIONS_LOCK = 'locks/sessions.lock'   # under STATE: the view-session lock (sessions_lock, DEF-1792)
+SESSIONS_POLL = 0.1                      # seconds between two tries while another process holds it
+_SESSIONS_DOING = re.compile(r'[A-Za-z0-9_. -]{1,80}\Z')
+_SESSIONS_SINCE = re.compile(r'[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\Z')
+_sessions_depth = 0                      # how many sessions_lock blocks this process is inside (re-entry)
+
+
+class SessionsBusy(LanesError):
+    """sessions_lock was not taken in time: another lanes process is acting on the view sessions."""
+
+
+def sessions_holder(path=None):
+    """Who holds the view-session lock, as sessions_lock recorded it: 'lanes rebuild mac (pid 4242, since
+    2026-10-07T08:40:12Z)'. 'another lanes process' when the record is missing, cut short or not one sessions_lock
+    writes: no file text reaches a terminal unchecked."""
+    record = read_json(STATE / SESSIONS_LOCK if path is None else path)
+    if (isinstance(record, dict) and isinstance(record.get('doing'), str) and _SESSIONS_DOING.match(record['doing'])
+            and type(record.get('pid')) is int and record['pid'] > 0
+            and _SESSIONS_SINCE.match(str(record.get('since', '')))):
+        return f"{record['doing']} (pid {record['pid']}, since {record['since']})"
+    return 'another lanes process'
+
+
+@contextlib.contextmanager
+def sessions_lock(timeout, doing):
+    """Serialize every check-then-act on the zellij view sessions across processes (DEF-1792): `lanes ensure` (the
+    minute timer, and `--if-layout-changed`, the server update's last step), `lanes rebuild` (also the sidebar's `r`),
+    the create of `lanes attach`, `prepare` and `web`, the end `lanes offboard` gives a view and `lanes device forget`.
+    Each decides from the session list (or the devices/ record) and then creates, kills or deletes a session, or removes
+    the record `ensure` recreates from; interleaved, one could start a second `zellij attach --create-background` for a
+    name another had just killed and was about to create.
+
+    An exclusive flock(2) on STATE/locks/sessions.lock, tried every SESSIONS_POLL s for up to `timeout` s (one line on
+    stderr the first time it is busy, naming the holder). Taken, it records `{pid, doing, since}` for a waiter to name
+    (`doing`: what this process is, e.g. 'lanes rebuild mac'), and empties the record again when the block ends. The
+    lock belongs to the open file: a holder that dies releases it, and no child inherits it (O_CLOEXEC; subprocess
+    closes every other descriptor). Re-entrant within one process — `lanes ensure` rebuilds through `cmd_rebuild` while
+    it holds it. Raises SessionsBusy (naming the holder) when not taken in time, LanesError when the file cannot be
+    opened."""
+    global _sessions_depth
+    if _sessions_depth:
+        _sessions_depth += 1
+        try:
+            yield
+        finally:
+            _sessions_depth -= 1
+        return
+    path = STATE / SESSIONS_LOCK
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
+    except OSError as error:
+        raise LanesError(f'cannot open the view-session lock {path}: {error.strerror or error}')
+    try:
+        deadline, said = time.monotonic() + timeout, False
+        while True:
+            try:
+                fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise SessionsBusy(f'{sessions_holder(path)} is acting on the view sessions '
+                                       f'(waited {timeout:g} s)')
+                if not said:
+                    print(f'lanes: {sessions_holder(path)} is acting on the view sessions; waiting up to {timeout:g} s',
+                          file=sys.stderr, flush=True)
+                    said = True
+                time.sleep(SESSIONS_POLL)
+        os.ftruncate(descriptor, 0)
+        os.pwrite(descriptor, (json.dumps({'pid': os.getpid(), 'doing': doing,
+                                           'since': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())})
+                               + '\n').encode(), 0)
+        _sessions_depth = 1
+        try:
+            yield
+        finally:
+            _sessions_depth = 0
+            try:
+                os.ftruncate(descriptor, 0)
+            except OSError:
+                pass
+    finally:
+        os.close(descriptor)   # releases the lock
+
+
 def _require(pattern, value, label):
     if not isinstance(value, str) or not pattern.match(value):
         raise LanesError(f'Invalid {label}: {value!r}')
@@ -580,9 +1079,20 @@ def _title(value):
     return value
 
 
+def declared_tmux(registry_doc, name):
+    """The tmux binding ({socketName, sessionName}) one terminals.json declares for its terminal `name` — the terminal's
+    own `lanes.terminals[name].tmux`, else the one recorded under `throttle.terminals[name]` — exactly as
+    _workspace_lanes reads it; None when the file declares none (the manifest's recoveries and overrides are the
+    board's, not the file's). session_actions.promote_to_registered asks it which session a file already binds."""
+    own = ((registry_doc.get('lanes') or {}).get('terminals') or {}).get(name) or {}
+    return own.get('tmux') or ((((registry_doc.get('throttle') or {}).get('terminals') or {}).get(name) or {})
+                               .get('tmux'))
+
+
 def _workspace_lanes(manifest, containers):
     """Port of coder-launch/manage.mjs: explicit tmux bindings only; nothing is ever executed."""
     lanes = []
+    layers = []   # (lane, title, host override, container-declared name): _settle_declared_displays
     names = set()
     repo_ids = set()
     for repo in manifest.get('repositories') or []:
@@ -602,7 +1112,6 @@ def _workspace_lanes(manifest, containers):
             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
@@ -611,7 +1120,7 @@ def _workspace_lanes(manifest, containers):
             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')
+            binding = declared_tmux(registry, name)
             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:
@@ -638,11 +1147,15 @@ 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',
+            # Two display layers, both keyed by the DECLARED (unprefixed) terminal name and both changing `name` only:
+            # the id derives from `registry_name` (lane_id_for). The host manifest's `repositories[i].displayNames`
+            # (the operator's override, written by session_actions.rename_registered) wins over the container's own
+            # `lanes.terminals[<name>].displayName` (LNS-33: what the repository, or an agent in the container,
+            # declares). The container layer is read leniently, like color/icon: a value that is no usable lane name
+            # is ignored, never a board error — and it is settled only once the whole board is known (below).
+            override = (repo.get('displayNames') or {}).get(name)
+            lane = {
+                'name': _title(override) if override 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,
@@ -650,10 +1163,56 @@ def _workspace_lanes(manifest, containers):
                 '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'),
-            })
+            }
+            lanes.append(lane)
+            layers.append((lane, title, override or None, _declared_display(own.get('displayName'))))
+    _settle_declared_displays(layers)
     return lanes
 
 
+def _settle_declared_displays(layers):
+    """The container layer names only its OWN lane (LNS-33 review fix). The "Duplicate lane names" refusal above
+    covers titles; a container-declared name is not refused but DROPPED when another lane of the same board also
+    answers to it — that lane's title (the name it shows the moment its override is cleared), its host `displayNames`
+    override (the operator wins), or its own container-declared name (dropped on both sides, so terminal order never
+    decides who keeps it). Names are compared as a row reads them (`_shown_key`). A dropped name leaves the lane on
+    its override or title, with no board error. A kept one is carried as `declared_display` — only then, so a board
+    that declares none publishes the registry it did before — because a rename back to it drops the override; a
+    dropped one is not, so a rename back to the title is "back to the default" (rename_registered).
+    `layers` is [(lane, title, override or None, declared or None)] in board order; the lanes are updated in place."""
+    holders = {}
+    for lane, title, override, declared in layers:
+        for key in {_shown_key(value) for value in (title, override, declared) if value}:
+            holders[key] = holders.get(key, 0) + 1
+    for lane, title, override, declared in layers:
+        if declared and holders[_shown_key(declared)] == 1:
+            lane['declared_display'] = declared
+            if not override:
+                lane['name'] = declared
+
+
+def _shown_key(value):
+    """A lane name as a row reads it: Unicode compatibility forms folded (NFKC), invisible format characters (Cf:
+    zero-width space/joiner, word joiner, BOM) dropped, whitespace runs collapsed and trimmed. Two names with the same
+    key are two rows nobody can tell apart; an empty key is a row that reads blank."""
+    text = ''.join(ch for ch in unicodedata.normalize('NFKC', value) if unicodedata.category(ch) != 'Cf')
+    return ' '.join(text.split())
+
+
+def _declared_display(value):
+    """A container-declared `displayName` (terminals.json), or None when it is no usable lane name: not a string,
+    reading blank (whitespace or invisible format characters only), no UTF-8 text (a lone surrogate JSON can spell,
+    which would make every projection's write raise), or holding a control character (the `_title` rule). Never
+    raises — the container's file must not be able to take a board down over a label."""
+    if not isinstance(value, str) or not _shown_key(value):
+        return None
+    try:
+        value.encode('utf-8')
+        return _title(value)
+    except (LanesError, UnicodeEncodeError):
+        return None
+
+
 def _workspace_cwd(manifest):
     cwd = (manifest.get('remoteShell') or {}).get('cwd')
     if cwd:
@@ -927,9 +1486,11 @@ 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."""
+    OLD `generated_at`; the sync itself is recorded in `registry.synced`, which only `lanes doctor` reads.
+    -> [(container, why)] for each container whose `~/.lz/registry.json` was refused (DEF-1796): it costs only that
+    container, never the other projections; `lanes sync` reports it."""
     write_resolve_files(registry)
-    export_container_registries(registry)
+    _written, refused = 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)
@@ -937,6 +1498,7 @@ def publish_registry(registry):
     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")
+    return refused
 
 
 def registry_synced_at():
@@ -974,7 +1536,13 @@ def write_resolve_files(registry):
 
 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."""
+    needs — holder, exact target, create recipe, folder. Only where the lane contract is installed.
+
+    LNS-32: each entry also says who declares the lane and where, for the in-container Agent API (`lane-mcp`):
+    `source` (the container's spelling of its terminals.json), `repo` (the manifest's repository id) and
+    `registry_name` (the declared terminal name with the repository prefix — what the id derives from, whatever the
+    display name), all null for a session adopted through `registered-sessions.json` (`registered_session: true`),
+    plus `container`. Additive within version 1: `lane` and the Studio's registry reader read by key."""
     per_container = {}
     for workspace in registry['workspaces']:
         for lane in workspace['lanes']:
@@ -982,17 +1550,47 @@ def export_container_registries(registry):
                 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')}
-    written = []
+                'zmx': lane.get('zmx'), 'create': lane.get('create'), 'folder': lane.get('folder'),
+                'source': lane.get('source'), 'repo': lane.get('repo'), 'registry_name': lane.get('registry_name'),
+                'container': lane['container'], 'registered_session': bool(lane.get('registered_session'))}
+    written, refused = [], []
     for container, lanes in per_container.items():
         home = (registry['containers'].get(container) or {}).get('home')
-        if home and (Path(home) / '.lz/bin/lane').exists():
+        if not home:
+            continue
+        # `~/.lz` belongs to the container: walked without following a link, read without blocking on a FIFO,
+        # replaced by rename (DEF-1796: a planted absolute symlink redirected this write on the HOST — into another
+        # container's ~/.lz through its `~/.lz/<name>` host link — and a FIFO at registry.json hung the sync).
+        try:
+            fd = open_real_dir(home, ('.lz',))
+        except FileNotFoundError:
+            continue                                  # no ~/.lz: the lane contract is not installed there
+        except OSError as error:
+            refused.append((container, f'~/.lz is not a real directory ({type(error).__name__}: {error})'))
+            continue
+        try:
+            try:
+                os.stat('bin/lane', dir_fd=fd)
+            except FileNotFoundError:
+                continue                              # a ~/.lz without `lane`: not installed either
             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)
+            old = read_regular_at(fd, 'registry.json', EXPORT_READ_MAX)
+            try:
+                old = json.loads(old) if old is not None else None
+            except ValueError:
+                old = None
+            if not _same_document(old, document):    # `generated_at` alone is no change
+                atomic_write_at(fd, 'registry.json', json.dumps(document, ensure_ascii=False, indent=1) + '\n',
+                                mode=0o644)
             written.append(container)
-    return written
+        except OSError as error:
+            refused.append((container, f'~/.lz/registry.json not written ({type(error).__name__}: {error})'))
+        finally:
+            os.close(fd)
+    return written, refused
+
+
+EXPORT_READ_MAX = 16 << 20   # a ~/.lz/registry.json bigger than this is not ours: it is replaced, never read whole
 
 
 def load_registry():