@vibelord/lanes 1.0.1 → 1.0.3

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

@@ -13,6 +13,7 @@ import json
 import os
 import re
 import shlex
+import signal
 import subprocess
 import tempfile
 import time
@@ -118,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())
@@ -125,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()
@@ -177,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.
@@ -222,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
 
 
@@ -238,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}"
 
@@ -571,6 +713,100 @@ def canonical_recipe(lane_id, ws, socket, session, folder, cmd='bash -l'):
             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-1559)? 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):
@@ -617,7 +853,7 @@ def ssh_workspaces(catalog):
 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': [], 'extras': [], 'discovery_roots': [],
+            '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': '💻',
@@ -662,10 +898,8 @@ def build_registry(previous=None):
                     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']
@@ -682,15 +916,27 @@ def build_registry(previous=None):
 
 
 def publish_registry(registry):
-    """Publish a prepared registry while holding registry_lock()."""
+    """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)
-        candidates = workspace['lanes'] or workspace.get('extras', [])
-        first = focus or (candidates[0] if candidates else None)
-        atomic_write(STATE / 'defaults' / workspace['id'], (first['id'] if first else '!empty') + '\n')
-    atomic_write(STATE / 'registry.json', json.dumps(registry, indent=1, ensure_ascii=False) + '\n')
+        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):
@@ -700,9 +946,9 @@ 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']]
@@ -712,7 +958,7 @@ def write_resolve_files(registry):
                 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()
@@ -733,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
 
@@ -752,7 +999,7 @@ def load_registry():
 def find_lane(registry, lane_id):
     status = read_json(STATE / 'status.json', {}) or {}
     for workspace in registry['workspaces']:
-        for lane in workspace['lanes'] + workspace.get('extras', []):
+        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.