@vibelord/lanes 1.0.0 → 1.0.1

package/payload/lanes/libexec/device_sync.py

@@ -0,0 +1,134 @@
+"""Reconcile catalog tabs without switching focus or touching persistent agents."""
+import fcntl
+import json
+import shlex
+
+import lanes_lib as L
+
+
+def observe(device, call):
+    values = []
+    for action in ('list-tabs', 'list-panes'):
+        rc, output, error = call(['-s', device, 'action', action, '--json'], 20)
+        if rc != 0:
+            raise L.LanesError(f'{device}: cannot read {action}: {error or "no answer"}')
+        try:
+            value = json.loads(output)
+            if not isinstance(value, list):
+                raise ValueError('expected a list')
+        except (ValueError, TypeError) as error:
+            raise L.LanesError(f'{device}: invalid {action} response') from error
+        values.append(value)
+    tabs, panes = values
+    if tabs and not panes:
+        raise L.LanesError(f"{device}: pane identities unavailable")
+    if any(type(t.get('tab_id')) is not int or type(t.get('position')) is not int for t in tabs):
+        raise L.LanesError(f'{device}: tab identities unavailable')
+    return tabs, panes
+
+
+def identities(device, tabs, panes, registry, mobile):
+    """Read workspace IDs from the launched commands, independent of tab labels."""
+    by_tab = {}
+    for pane in panes:
+        if pane.get('is_plugin'):
+            continue
+        try:
+            args = shlex.split(pane.get('terminal_command') or pane.get('pane_command') or '')
+        except ValueError:
+            continue
+        for script in ('sidebar', 'view.sh'):
+            path = str(L.REPO / 'libexec' / script)
+            if path not in args:
+                continue
+            tail = args[args.index(path) + 1:]
+            if len(tail) < 2 or tail[0] != device:
+                continue
+            workspace = tail[1]
+            if workspace.startswith('_'):
+                key = 'tool/' + workspace
+            else:
+                role = 'picker' if mobile and script == 'sidebar' else 'view'
+                key = f'workspace/{workspace}/{role}'
+            by_tab.setdefault(pane['tab_id'], set()).add(key)
+        holder = str(L.REPO / 'holders/ssh.sh')
+        if holder in args:
+            tail = args[args.index(holder) + 1:]
+            for workspace in registry.get('ssh_workspaces', []):
+                if (len(tail) == 3 and tail[:2] == [workspace['host'], workspace['command']]
+                        and any(pane['id'] == tail[2] for pane in workspace['panes'])):
+                    by_tab.setdefault(pane['tab_id'], set()).add('ssh/' + workspace['id'])
+    result = {}
+    for tab in tabs:
+        keys = by_tab.get(tab['tab_id'], set())
+        if not keys and tab['name'] == 'Host':
+            keys = {'host'}
+        if len(keys) > 1:
+            raise L.LanesError(f'{device}: ambiguous workspace tab {tab["tab_id"]}')
+        for key in keys:
+            if key in result:
+                raise L.LanesError(f'{device}: duplicate workspace identity {key}')
+            result[key] = tab
+    return result
+
+
+def reconcile(device, registry, specs, mobile, call):
+    lock = L.STATE / 'locks' / f'device-sync.{device}.lock'
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    with lock.open('a') as handle:
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        tabs, panes = observe(device, call)
+        known = identities(device, tabs, panes, registry, mobile)
+        wanted = []
+        changes = []
+
+        def action(args):
+            rc, output, error = call(['-s', device, 'action'] + args, 30)
+            if rc != 0:
+                raise L.LanesError(f'{device}: {args[0]} failed: {error or "no answer"}')
+            return output
+
+        for spec in specs:
+            tab = known.get(spec['key'])
+            if tab is None:
+                if any(t['name'] == spec['title'] for t in tabs):
+                    raise L.LanesError(f'{device}: tab {spec["title"]!r} has no matching workspace identity; left intact')
+                # Zellij 0.45.1 acknowledges background tabs without spawning their
+                # panes when no client is attached. Wait for a client; the ensure
+                # timer retries after attach without leaving empty tabs behind.
+                if not any(t.get('active') is True for t in tabs):
+                    continue
+                output = action(['new-tab', '--no-focus', '--name', spec['title'],
+                                 '--layout-string', spec['layout']])
+                # Zellij 0.45.1 returns the stable ID. Do not guess after a timeout
+                # or repeat creation if the answer is missing: next sync observes it.
+                try:
+                    tab_id = int(output.strip())
+                except ValueError as error:
+                    raise L.LanesError(f'{device}: created tab ID unavailable; retry sync after observation') from error
+                tab = {'tab_id': tab_id, 'name': spec['title'], 'position': len(tabs)}
+                tabs.append(tab)
+                changes.append('added ' + spec['title'])
+            elif tab['name'] != spec['title']:
+                action(['rename-tab', spec['title'], '--tab-id', str(tab['tab_id'])])
+                changes.append('renamed ' + tab['name'] + ' to ' + spec['title'])
+            wanted.append(tab['tab_id'])
+
+        # Sort managed tabs by adjacent moves using stable IDs. Each observation
+        # must answer. Unmanaged tabs remain open; no close/rebuild/focus action exists.
+        for position, tab_id in enumerate(wanted):
+            for _ in range(len(tabs) + 1):
+                rc, output, error = call(['-s', device, 'action', 'list-tabs', '--json'], 20)
+                if rc != 0:
+                    raise L.LanesError(f'{device}: cannot check tab order: {error or "no answer"}')
+                live = json.loads(output)
+                tab = next((t for t in live if t.get('tab_id') == tab_id), None)
+                if tab is None:
+                    raise L.LanesError(f'{device}: workspace tab changed during sync')
+                if tab['position'] == position:
+                    break
+                action(['move-tab', 'left' if tab['position'] > position else 'right',
+                        '--tab-id', str(tab_id)])
+            else:
+                raise L.LanesError(f'{device}: tab order did not settle')
+        return changes

package/payload/lanes/libexec/lanes_lib.py

@@ -6,10 +6,13 @@ 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 subprocess
 import tempfile
 import time
@@ -397,6 +400,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 +490,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 +524,112 @@ 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}')
+
+
+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': [], 'extras': [], '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,7 +656,7 @@ 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
@@ -538,6 +667,8 @@ def build_registry(previous=None):
         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 +676,21 @@ 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()."""
+    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')
 
 
 def write_resolve_files(registry):
@@ -561,6 +706,8 @@ def write_resolve_files(registry):
             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:
@@ -577,6 +724,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')}
@@ -603,8 +752,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'] + workspace.get('extras', []):
+            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}')

package/payload/lanes/libexec/registrations.py

@@ -0,0 +1,148 @@
+"""Durable, attach-only registrations for sessions adopted through the sidebar or CLI."""
+import json
+import time
+
+import lanes_lib as L
+
+FILENAME = 'registered-sessions.json'
+VERSION = 1
+
+
+def key(entry):
+    binding = entry.get('tmux') or {}
+    return entry.get('container'), binding.get('socket'), binding.get('session')
+
+
+def eligible(entry):
+    return entry.get('holder') == 'tmux' and bool(entry.get('tmux')) and not entry.get('legacy')
+
+
+def destinations(registry, entry):
+    if not eligible(entry):
+        return []
+    return [w for w in registry['workspaces'] if w.get('container') == entry.get('container') or
+            any(lane.get('container') == entry.get('container') for lane in w.get('lanes', []))]
+
+
+def load():
+    path = L.workspaces_dir() / FILENAME
+    try:
+        data = json.loads(path.read_text())
+    except FileNotFoundError:
+        return {'version': VERSION, 'sessions': []}
+    except (OSError, ValueError) as error:
+        raise L.LanesError(f'Cannot read {path}: {error}') from error
+    if not isinstance(data, dict) or type(data.get('version')) is not int or data['version'] != VERSION:
+        raise L.LanesError(f'Unsupported {FILENAME} version; this server reads version {VERSION}')
+    if not isinstance(data.get('sessions'), list):
+        raise L.LanesError(f'Invalid sessions in {FILENAME}')
+    ids, bindings = set(), set()
+    for record in data['sessions']:
+        if not isinstance(record, dict) or not isinstance(record.get('tmux'), dict):
+            raise L.LanesError(f'Invalid registration in {FILENAME}')
+        for field in ('id', 'workspace', 'container'):
+            L._require(L.IDENT, record.get(field), field)
+        L._title(record.get('name'))
+        L._require(L.IDENT, record['tmux'].get('socket'), 'tmux socket')
+        L._require(L.TMUX_SESSION, record['tmux'].get('session'), 'tmux session')
+        L._require(L.SAFE_PATH, record.get('folder'), 'working directory')
+        if record['id'] in ids or key(record) in bindings:
+            raise L.LanesError(f'Duplicate registration in {FILENAME}')
+        ids.add(record['id']); bindings.add(key(record))
+    return data
+
+
+def apply(registry, data=None):
+    """Overlay local registrations. Repository declarations win if they adopt the same binding."""
+    data = load() if data is None else data
+    by_id = {w['id']: w for w in registry['workspaces']}
+    for workspace in by_id.values():
+        # A stale repository can retain a previous board. Rebuild its local registrations from authority too.
+        workspace['lanes'] = [lane for lane in workspace['lanes'] if not lane.get('registered_session')]
+    lanes = [lane for w in by_id.values() for lane in w['lanes']]
+    bindings = {key(lane) for lane in lanes if lane.get('holder') == 'tmux'}
+    ids = {lane['id'] for lane in lanes}
+    for record in data['sessions']:
+        workspace = by_id.get(record['workspace'])
+        if not workspace or key(record) in bindings:
+            continue
+        lane = dict(record, holder='tmux', registered_session=True, icon='💻', color=None, create=None)
+        if workspace not in destinations(registry, lane):
+            workspace.setdefault('errors', []).append('Registered session belongs to a different container: ' + record['name'])
+            continue
+        if lane['id'] in ids:
+            raise L.LanesError('Registered session ID collides with another lane: ' + lane['id'])
+        workspace['lanes'].append(lane)
+        bindings.add(key(lane)); ids.add(lane['id'])
+    return registry
+
+
+def rename(lane_id, new_name):
+    """Display name of one registered session — this file is its only name authority (`apply` takes the lane's
+    name from the record). Only `name` changes: the id, binding, workspace and folder stay, so view targets,
+    resolve files and `lane open <id>` keep working. The `user-sessions/` and `resolve.dynamic/` files an
+    UNREGISTERED session is renamed through are never read for a registered one (DEF-1412)."""
+    name = L._title(new_name)
+    with L.registry_lock():
+        data = load()
+        record = next((item for item in data['sessions'] if item['id'] == lane_id), None)
+        if record is None:
+            raise L.LanesError(f'{lane_id} is not a registered session in {FILENAME}; reload')
+        record['name'] = name
+        registry = apply(L.load_registry(), data)
+        registry['generated_at'] = time.time()
+        L.atomic_write(L.workspaces_dir() / FILENAME, json.dumps(data, ensure_ascii=False, indent=2) + '\n')
+        try:
+            L.publish_registry(registry)
+        except OSError as error:
+            raise L.LanesError('Rename saved; run lanes sync to finish publishing: ' + str(error)) from error
+        return next((lane for w in registry['workspaces'] for lane in w['lanes'] if lane['id'] == lane_id),
+                    dict(record))
+
+
+def register(workspace, entry, destination=None):
+    """Keep the same binding and ID; registration never starts, stops, renames or reattaches a process."""
+    destination = destination or workspace
+    with L.registry_lock():
+        data = load()
+        registry = apply(L.load_registry(), data)
+        if not eligible(entry):
+            raise L.LanesError('Only reconnectable tmux sessions can be registered')
+        for board in registry['workspaces']:
+            if any(key(lane) == key(entry) for lane in board['lanes'] if lane.get('holder') == 'tmux'):
+                raise L.LanesError('Already registered in ' + (board.get('title') or board['id']))
+        board = next((w for w in destinations(registry, entry) if w['id'] == destination), None)
+        if not board:
+            raise L.LanesError('Choose a workspace that uses this session’s container')
+        published = (L.read_json(L.STATE / 'status.json', {}) or {}).get('unregistered', {}).get(workspace, [])
+        actual = next((item for item in published if item.get('id') == entry.get('id')), None)
+        if not actual or key(actual) != key(entry) or actual.get('identity') != entry.get('identity'):
+            raise L.LanesError('Session changed; reload before registering')
+        container, socket, name = key(actual)
+        L._require(L.IDENT, actual['id'], 'lane id')
+        L._require(L.IDENT, container, 'container')
+        L._require(L.IDENT, socket, 'tmux socket')
+        L._require(L.TMUX_SESSION, name, 'tmux session')
+        identity = actual.get('identity') or {}
+        sid, created = identity.get('session_id', ''), identity.get('created', '')
+        if not isinstance(sid, str) or not isinstance(created, str) or not sid.startswith('$') or not sid[1:].isdigit() or not created.isdigit():
+            raise L.LanesError('Session identity is not ready; wait for the next status update')
+        info = (L.read_json(L.STATE / 'containers.json', {}) or {}).get(container) or {}
+        outcome, observed = L.tmux_probe(info, socket, ['display-message', '-p', '-t', '=' + name + ':',
+                                                      '#{session_id}\t#{session_created}'], 5)
+        if outcome != 'ok' or observed.strip() != sid + '\t' + created:
+            raise L.LanesError('Session changed or could not be checked; nothing was registered')
+        record = {'id': actual['id'], 'workspace': destination, 'name': L._title(actual['name']),
+                  'container': container, 'tmux': dict(actual['tmux']),
+                  'folder': L._require(L.SAFE_PATH, board.get('cwd') or L.CONTAINER_HOME, 'working directory')}
+        if any(item['id'] == record['id'] or key(item) == key(record) for item in data['sessions']):
+            raise L.LanesError(f'Registration already saved; check {FILENAME} and run lanes sync')
+        data['sessions'].append(record)
+        registry = apply(registry, data)
+        registry['generated_at'] = time.time()
+        L.atomic_write(L.workspaces_dir() / FILENAME, json.dumps(data, ensure_ascii=False, indent=2) + '\n')
+        try:
+            L.publish_registry(registry)
+        except OSError as error:
+            raise L.LanesError('Registration saved; run lanes sync to finish publishing: ' + str(error)) from error
+        return next(lane for lane in board['lanes'] if lane['id'] == record['id'])

package/payload/lanes/libexec/session_actions.py

@@ -82,6 +82,8 @@ def new_shell(workspace):
     board = next((w for w in registry['workspaces'] if w['id'] == workspace), None)
     if not board:
         raise L.LanesError('Workspace no longer exists; reload the sidebar')
+    if board.get('attach_only'):
+        raise L.LanesError('Select an existing remote terminal in this workspace')
     container = L._require(L.IDENT, board['container'], 'container')
     cwd = L._require(L.SAFE_PATH, board['cwd'], 'working directory')
     socket = shell_socket(workspace)
@@ -140,19 +142,30 @@ def rename_session(workspace, entry, new_name):
     return dict(entry, name=new_name)
 
 
-def rename_registered(manifest_path, registry_name, new_name):
-    """Rename a registered lane by writing a displayNames override to the workspace manifest JSON.
-    `manifest_path` is the path to workspaces.<board>.json; `registry_name` is the terminal's declared
-    name; `new_name` is the display override. Callers must run `lanes sync` after this returns."""
+def rename_registered(manifest_path, repo_id, registry_name, new_name):
+    """Display override for one declared terminal. The reader is `lanes_lib._workspace_lanes`, which looks at
+    `repositories[i].displayNames` keyed by the terminal's declared name — the manifest's top level (and the
+    lane's terminals.json `source`) has no such key. `registry_name` is the lane's title (repository prefix +
+    declared name); renaming back to it clears the override. The lane id never changes (lanes_lib.lane_id_for).
+    The first write keeps a `<manifest>.bak-<UTC timestamp>` copy beside it. Callers run `lanes sync`."""
     L._title(new_name)
-    data = json.loads(Path(manifest_path).read_text())
-    if 'displayNames' not in data:
-        data['displayNames'] = {}
+    path = Path(manifest_path)
+    original = path.read_text()
+    data = json.loads(original)
+    repo = next((r for r in data.get('repositories') or [] if r.get('id') == repo_id), None)
+    if repo is None:
+        raise L.LanesError(f'Repository {repo_id!r} not in {path.name}')
+    prefix = repo.get('prefix') or ''
+    declared = registry_name[len(prefix):] if prefix and registry_name.startswith(prefix) else registry_name
+    names = repo.setdefault('displayNames', {})
     if new_name == registry_name:
-        data['displayNames'].pop(registry_name, None)   # removing the override restores the default
+        names.pop(declared, None)   # removing the override restores the default title
     else:
-        data['displayNames'][registry_name] = new_name
-    L.atomic_write(manifest_path, json.dumps(data, indent=2, ensure_ascii=False) + '\n', mode=0o644)
+        names[declared] = new_name
+    if not any(path.parent.glob(path.name + '.bak-*')):
+        L.atomic_write(path.parent / (path.name + '.bak-' + time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())),
+                       original, mode=0o644)
+    L.atomic_write(path, json.dumps(data, indent=2, ensure_ascii=False) + '\n', mode=0o644)
 
 
 def promote_to_registered(workspace_id, entry, registry):
@@ -163,19 +176,32 @@ def promote_to_registered(workspace_id, entry, registry):
     Raises LanesError for unsupported configurations or invalid session state."""
     if entry.get('holder') != 'tmux':
         raise L.LanesError('Only tmux sessions can be promoted (zmx and exec holders are not supported)')
+    # A binding any board already holds — a repository declaration or an adopted registered session — is
+    # registered. Appending it again would make the repository declaration win the binding on the next sync,
+    # re-keying an adopted lane's id and orphaning its view targets (DEF-1411). Nothing is written.
+    if entry.get('registered_session') or session_key(entry) in {
+            session_key(lane) for w in registry.get('workspaces', []) for lane in w.get('lanes', [])
+            if lane.get('holder') == 'tmux'}:
+        raise L.LanesError('Already registered; nothing was promoted')
     board = next((w for w in registry.get('workspaces', []) if w['id'] == workspace_id), None)
     if not board:
         raise L.LanesError('Workspace not found')
-    # Find the terminals.json source — must be a single unambiguous path
-    sources = [lane.get('source') for lane in board.get('lanes', []) if lane.get('source')]
-    unique_sources = list(dict.fromkeys(s for s in sources if s))
+    # Find the terminals.json source — must be a single unambiguous file. A source is (container, spelling): the
+    # same spelling in two containers (one repository cloned in two boxes) is two files, so it is still ambiguous.
+    sources = [(lane.get('container') or board.get('container') or '', lane['source'])
+               for lane in board.get('lanes', []) if lane.get('source')]
+    unique_sources = list(dict.fromkeys(sources))
     if not unique_sources:
         raise L.LanesError(
             'No registry source found for this workspace; add the lane to terminals.json manually')
     if len(unique_sources) > 1:
         raise L.LanesError(
             'Multiple registry sources in this workspace; add the lane to terminals.json manually')
-    terminals_path = Path(unique_sources[0])
+    # The source is the container's spelling of terminals.json; this process runs on the host, where the file only
+    # exists under the container's home volume. Writing Path(source) would miss it (or write a stray host file).
+    container, source = unique_sources[0]
+    info = (L.read_json(L.STATE / 'containers.json') or {}).get(container) or {}
+    terminals_path = L.host_path(info, source)
     if not terminals_path.exists():
         raise L.LanesError(f'Registry file not found: {terminals_path}')
     tmux = entry.get('tmux') or {}
@@ -206,7 +232,13 @@ def promote_to_registered(workspace_id, entry, registry):
 
 def close_session(workspace, entry):
     """Close the exact observed session, never an identically named replacement or a registered lane."""
-    registry = L.load_registry()
+    with L.registry_lock():
+        return _close_session(workspace, entry)
+
+
+def _close_session(workspace, entry):
+    import registrations
+    registry = registrations.apply(L.load_registry())
     current = (L.read_json(L.STATE / 'status.json', {}) or {}).get('unregistered', {}).get(workspace, [])
     published = next((x for x in current if x['id'] == entry['id']), None)
     if not published or session_key(published) != session_key(entry) or not entry.get('closable'):