@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/libexec/notify.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Opt-in push notifications: one ntfy message per lane per transition into needs-you (plan Task 14).
+
+The desktop sidebar already raises one OSC 9 per transition while a terminal shows it (spec §4.9); this is the same
+event for the operator who is away from every terminal. `lanes-notify.service` (opt-in — no installer enables it)
+re-reads `STATE/status.json` when its mtime changes (checked every `--interval` seconds, 3 in the unit) and POSTs
+to an ntfy server when a lane's `agent.status` ENTERS `needs_input`, `needs_approval` or `errored` — the sidebar's
+NEEDS_YOU set. The six-word `state` is never read: the agent status is the only input.
+
+  * A status that stays the same is not news; a change between two needs-you statuses is (input → approval).
+  * The first document the service reads only seeds it: lanes that were already waiting when it (re)started are
+    not announced, so a restart never sends a burst.
+  * Presence suppression: nothing is sent while any device was at a desk within `quiet_when_device_active_s`
+    (default 120 s) — measured as the mtime of `STATE/clients/<device>.<client>.pid` (written only by
+    `lanes attach`), or of `STATE/clients/<device>.seen.json` (written by a sidebar when the operator opens a
+    lane) for a DESK device only: one with a `<device>.*.pid` of any age whose `STATE/devices/<device>.json` is not
+    `mobile: true`. Phone presence is decided by the device's mobile layout, not by how it attached: a Safari phone
+    has no `.pid`, and an SSH-only phone that ran `lanes attach phone --mobile` is still mobile, so opening a lane
+    from the phone's picker never mutes pushes (DEF-1452). A phone's own attach within the window still counts.
+    Typing in a lane touches neither file, so this is "attached or opened a lane at a desk recently", not "is
+    looking now" (DEF-1451). A suppressed transition is consumed, never sent later.
+  * Payload: `<lane name>: <agent task> — <status>` and, on a second line, the client command that opens the lane
+    (`lanes-launch lane <id>`). No client registers a URL scheme for it, so the push carries a tappable action only
+    when `action_url` (a template over `{lane}`) is configured.
+  * A failed send is one journal line (lane id and the failure class — never the topic or the bearer) and is not
+    retried; it never stops the service.
+
+Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `key=value` lines, `#` comments,
+re-read when its mtime changes: `url` (ntfy server, http/https, required), `topic` (`[A-Za-z0-9_-]{1,64}`,
+required), `token_file` (a file holding an ntfy access token, optional — sent as a bearer, never logged; an
+unreadable one disables sending rather than sending unauthenticated), `quiet_when_device_active_s` (default 120;
+0 never suppresses), `action_url` (optional template, e.g. `https://lanes.example/?lane={lane}`). Without a valid
+`url` and `topic` the service only tracks transitions and sends nothing.
+
+Answering a `PermissionRequest`-held approval FROM the phone needs a request/response channel back into the hook;
+that is a follow-up design, not part of this module.
+"""
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lanes_lib as L  # noqa: E402
+import tokens  # noqa: E402
+
+TRIGGERS = ('needs_input', 'needs_approval', 'errored')   # the sidebar's NEEDS_YOU (sidebar.ATTENTION[0][3])
+LABELS = tokens.MOBILE_AGENT_LABELS                       # the phone's words: Needs you / Needs approval / Error
+PRIORITY = {'needs_approval': 4, 'errored': 4, 'needs_input': 3}
+DEFAULT_QUIET = 120
+DEFAULT_CONF = '~/.config/lanes/notify.conf'
+KEYS = ('url', 'topic', 'token_file', 'quiet_when_device_active_s', 'action_url')
+TOPIC = re.compile(r'^[A-Za-z0-9_-]{1,64}$')
+UNSAFE = re.compile(r'[\x00-\x1f\x7f-\x9f]')              # C0, DEL, C1: never inside a push line
+TEXT_MAX = 200                                            # characters of the first payload line
+TIMEOUT = 5
+PRESENCE = '*.pid'                                        # clients/ files only `lanes attach` writes
+SEEN = '.seen.json'                                       # a sidebar's opened-lane record; desk devices only
+                                                          # (a .pid of any age, devices/<device>.json not mobile)
+
+
+def _text(value):
+    return UNSAFE.sub('', str(value or ''))
+
+
+def read_config(path):
+    """notify.conf -> {url, topic, token_file, token, quiet_when_device_active_s, action_url, enabled}. Never raises."""
+    raw = {}
+    try:
+        lines = Path(os.path.expanduser(str(path))).read_text().splitlines()
+    except (OSError, UnicodeDecodeError):
+        lines = []
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith('#') or '=' not in line:
+            continue
+        key, value = (part.strip() for part in line.split('=', 1))
+        if key in KEYS:
+            raw[key] = value
+    try:
+        quiet = max(0, int(raw.get('quiet_when_device_active_s', DEFAULT_QUIET)))
+    except ValueError:
+        quiet = DEFAULT_QUIET
+    url = raw.get('url', '').rstrip('/')
+    topic = raw.get('topic', '')
+    config = {'url': url, 'topic': topic, 'token_file': raw.get('token_file', ''), 'token': None,
+              'quiet_when_device_active_s': quiet, 'action_url': raw.get('action_url', '')}
+    enabled = url.startswith(('http://', 'https://')) and bool(TOPIC.match(topic))
+    if enabled and config['token_file']:
+        try:
+            config['token'] = Path(os.path.expanduser(config['token_file'])).read_text().strip() or None
+        except (OSError, UnicodeDecodeError):
+            config['token'] = None
+        enabled = config['token'] is not None
+    config['enabled'] = enabled
+    return config
+
+
+def agent_statuses(document):
+    """status.json -> {lane id: agent status} for lanes with an agent{} (the six-word `state` is never read)."""
+    lanes = document.get('lanes') if isinstance(document, dict) else None
+    out = {}
+    for lane_id, entry in (lanes.items() if isinstance(lanes, dict) else ()):
+        agent = entry.get('agent') if isinstance(entry, dict) else None
+        if isinstance(agent, dict) and isinstance(agent.get('status'), str):
+            out[lane_id] = agent['status']
+    return out
+
+
+def lane_names(registry):
+    """registry.json -> {lane id: display name} over every workspace's lanes."""
+    out = {}
+    workspaces = registry.get('workspaces') if isinstance(registry, dict) else None
+    for ws in workspaces if isinstance(workspaces, list) else ():
+        if not isinstance(ws, dict):
+            continue
+        for lane in ws.get('lanes') or ():
+            if isinstance(lane, dict) and isinstance(lane.get('id'), str) and lane.get('name'):
+                out[lane['id']] = str(lane['name'])
+    return out
+
+
+def is_mobile(devices_dir, device):
+    """True when `STATE/devices/<device>.json` says `mobile: true` — the phone layout `lanes prepare|attach
+    --mobile` created, the same mark the device's sidebar reads. Missing or unreadable meta is not mobile."""
+    meta = L.read_json(Path(devices_dir) / f'{device}.json')
+    return isinstance(meta, dict) and bool(meta.get('mobile'))
+
+
+def device_active(clients_dir, window, now, devices_dir=None):
+    """True when a device attached (`<device>.<client>.pid`) or a desk device opened a lane (`<device>.seen.json`)
+    within `window` seconds of `now`. `seen.json` counts only for a device that has a `<device>.*.pid` of any age
+    (the mark of `lanes attach`) AND whose `devices_dir/<device>.json` is not `mobile: true`. The mobile flag is
+    the authoritative phone mark: a Safari phone never runs `lanes attach`, but an SSH-only phone may
+    (`lanes attach phone --mobile`, RUNBOOK) and its pid is never removed — so a lane opened from the phone's picker
+    never mutes the phone's own pushes, however it attached (DEF-1452). `devices_dir` defaults to the `devices`
+    directory beside `clients_dir` (both live in STATE). A missing directory is nobody present; a window of 0 is
+    never present."""
+    if window <= 0:
+        return False
+    devices_dir = Path(clients_dir).parent / 'devices' if devices_dir is None else Path(devices_dir)
+
+    def recent(path):
+        try:
+            return now - path.stat().st_mtime <= window
+        except OSError:
+            return False
+
+    try:
+        directory = Path(clients_dir)
+        if any(recent(path) for path in directory.glob(PRESENCE)):
+            return True
+        for path in directory.glob('*' + SEEN):
+            device = path.name[:-len(SEEN)]
+            if (device and recent(path) and any(directory.glob(glob.escape(device) + '.' + PRESENCE))
+                    and not is_mobile(devices_dir, device)):
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _note(lane_id, status, agent, names, config):
+    label = LABELS.get(status, status)
+    name = _text(names.get(lane_id) or lane_id)
+    task = _text(agent.get('name'))
+    first = f'{name}: {task} — {label}' if task else f'{name} — {label}'
+    if len(first) > TEXT_MAX:
+        first = first[:TEXT_MAX - 1] + '…'
+    note = {'lane': lane_id, 'status': status, 'title': label,
+            'message': f'{first}\nlanes-launch lane {lane_id}', 'priority': PRIORITY.get(status, 3)}
+    template = config.get('action_url') or ''
+    if template:
+        url = template.replace('{lane}', urllib.parse.quote(lane_id, safe=''))
+        note['click'] = url
+        note['actions'] = [{'action': 'view', 'label': 'Open lane', 'url': url}]
+    return note
+
+
+def notify_changes(prev_status, new_status, config, names=None, now=None, clients_dir=None, devices_dir=None):
+    """The notifications for lanes whose agent status ENTERED needs-you between two status.json documents.
+    `prev_status` None = the first read: seed only, nothing is news. Empty when a desk device is present."""
+    if prev_status is None:
+        return []
+    before = agent_statuses(prev_status)
+    lanes = new_status.get('lanes') if isinstance(new_status, dict) else None
+    changed = [(lane_id, status) for lane_id, status in agent_statuses(new_status).items()
+               if status in TRIGGERS and before.get(lane_id) != status]
+    if not changed:
+        return []
+    now = time.time() if now is None else now
+    window = int(config.get('quiet_when_device_active_s', DEFAULT_QUIET) or 0)
+    if device_active(clients_dir if clients_dir is not None else L.STATE / 'clients', window, now, devices_dir):
+        return []
+    names = names or {}
+    return [_note(lane_id, status, lanes[lane_id]['agent'], names, config) for lane_id, status in sorted(changed)]
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *_args, **_kwargs):   # a redirect would carry the bearer elsewhere: refuse it
+        return None
+
+
+def default_opener():
+    return urllib.request.build_opener(_NoRedirect()).open
+
+
+def send(note, config, opener=None):
+    """POST one notification as ntfy JSON to `config['url']`. True when the server accepted it. Any failure is one
+    stderr (journal) line naming the lane and the failure class — never the topic or the bearer — and False."""
+    body = {'topic': config['topic'], 'title': note['title'], 'message': note['message'],
+            'priority': note.get('priority', 3)}
+    for key in ('click', 'actions'):
+        if key in note:
+            body[key] = note[key]
+    headers = {'Content-Type': 'application/json'}
+    if config.get('token'):
+        headers['Authorization'] = f"Bearer {config['token']}"
+    request = urllib.request.Request(config['url'], data=json.dumps(body).encode(), headers=headers, method='POST')
+    try:
+        with (opener or default_opener())(request, timeout=TIMEOUT) as response:
+            status = getattr(response, 'status', 200)
+            if not 200 <= status < 300:
+                raise urllib.error.HTTPError(config['url'], status, 'not accepted', {}, None)
+        return True
+    except urllib.error.HTTPError as error:
+        why = f'HTTP {error.code}'
+    except urllib.error.URLError as error:
+        why = f'unreachable ({type(error.reason).__name__})' if not isinstance(error.reason, str) else 'unreachable'
+    except TimeoutError:
+        why = 'timed out'
+    except OSError as error:
+        why = type(error).__name__
+    except Exception as error:   # a push must never stop the service
+        why = type(error).__name__
+    print(f'notify: send failed for {note.get("lane")}: {why}', file=sys.stderr, flush=True)
+    return False
+
+
+class Watcher:
+    """Tails status.json by mtime; sends what notify_changes returns. The config and registry are re-read when
+    their mtime changes. The first readable document seeds the previous one."""
+
+    def __init__(self, state, conf_path, opener=None, clock=time.time):
+        self.state = Path(state)
+        self.conf_path = Path(os.path.expanduser(str(conf_path)))
+        self.opener, self.clock = opener, clock
+        self.prev = None
+        self.stamps = {}
+        self.config = read_config(self.conf_path)
+        self.names = {}
+
+    def _changed(self, key, path):
+        try:
+            stamp = path.stat().st_mtime_ns
+        except OSError:
+            stamp = None
+        if self.stamps.get(key, 'unset') == stamp:
+            return False
+        self.stamps[key] = stamp
+        return True
+
+    def tick(self):
+        if self._changed('conf', self.conf_path):
+            self.config = read_config(self.conf_path)
+        if self._changed('registry', self.state / 'registry.json'):
+            self.names = lane_names(L.read_json(self.state / 'registry.json'))
+        if not self._changed('status', self.state / 'status.json'):
+            return []
+        document = L.read_json(self.state / 'status.json')
+        if not isinstance(document, dict):
+            return []                   # a torn or missing file: keep the previous document
+        notes = notify_changes(self.prev, document, self.config, names=self.names, now=self.clock(),
+                               clients_dir=self.state / 'clients', devices_dir=self.state / 'devices')
+        self.prev = document
+        if not self.config['enabled']:
+            return []
+        for note in notes:
+            send(note, self.config, self.opener)
+        return notes
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='notify', description='push needs-you transitions to an ntfy topic')
+    parser.add_argument('--interval', type=float, default=3.0, help='seconds between status.json checks')
+    parser.add_argument('--test', action='store_true', help='send one test notification and exit (1 = not sent)')
+    args = parser.parse_args(argv)
+    conf = os.environ.get('LANES_NOTIFY_CONF') or DEFAULT_CONF
+    state = Path(os.environ.get('LANES_STATE') or L.STATE)
+    if args.test:
+        config = read_config(conf)
+        if not config['enabled']:
+            print(f'notify: {conf} has no valid url and topic (or its token_file is unreadable)', file=sys.stderr)
+            return 1
+        note = {'lane': 'test', 'status': 'test', 'title': 'lanes', 'message': 'lanes notify: test notification',
+                'priority': 3}
+        return 0 if send(note, config) else 1
+    watcher = Watcher(state, conf)
+    if not watcher.config['enabled']:
+        print(f'notify: {conf} has no valid url and topic; tracking only until it does', file=sys.stderr, flush=True)
+    while True:
+        try:
+            watcher.tick()
+        except Exception as error:   # one bad tick is a journal line; the next tick tries again
+            print(f'notify: {type(error).__name__}: {error}', file=sys.stderr, flush=True)
+        time.sleep(max(1.0, args.interval))
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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-1475)."""
+    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

@@ -72,8 +72,9 @@ def make_entry(workspace, container, socket, name, pane, previous=None):
     meta = L.read_json(L.STATE / 'user-sessions' / (entry['id'] + '.json'), {}) or {}
     if session_key(meta) == session_key(entry):
         entry['name'] = meta.get('name') or entry['name']
-    L.atomic_write(L.STATE / 'resolve.dynamic' / entry['id'],
-                   '\n'.join(['tmux', container, socket, name, entry['name']]) + '\n')
+    # statusd calls this for every unregistered session on every cycle: rewrite only a changed target or name.
+    L.atomic_write_if_changed(L.STATE / 'resolve.dynamic' / entry['id'],
+                              '\n'.join(['tmux', container, socket, name, entry['name']]) + '\n')
     return entry
 
 
@@ -82,6 +83,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 +143,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 +177,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-1474). 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,17 +233,21 @@ 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'):
         raise L.LanesError('Session changed; reload before closing')
     if entry.get('legacy'):
-        import legacy_sessions
-        legacy_sessions.close(entry)
-        clear_viewers(entry['id'])
-        (L.STATE / 'resolve.dynamic' / entry['id']).unlink(missing_ok=True)
-        return
+        # Plan Task 19 retired the pre-persistence Docker-shell tracker (legacy_sessions.py): only a status.json an
+        # older statusd wrote can still carry such a row. Refused before any process, tmux or file is touched.
+        raise L.LanesError('Legacy shells are retired; nothing was closed')
     registered = {session_key(lane) for w in registry['workspaces'] for lane in w.get('lanes', [])
                   if lane.get('holder') == 'tmux'}
     if session_key(entry) in registered: