@vibelord/lanes 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibelord/lanes",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Installer for Lanes: shared agent terminals over SSH with Zellij views, registry sync, uploads and a phone interface.",
   "license": "MIT",
   "type": "module",

package/payload/lanes/README.md

@@ -51,6 +51,12 @@ profile). Ghostty is recommended for a separate window; `lanes-launch` works in
 The installer uses an existing SSH key or creates a dedicated one. An administrator authorizes its **public**
 key on the server. Re-run `./install.sh --check` after authorization. Your selected site is remembered.
 
+When an ended view was rebuilt on the server, the client probes that state and reconnects
+automatically. The probe's watchdog cancels and reaps its timer when the probe completes;
+a hung probe still times out. This avoids waiting for the watchdog's full ten seconds
+after a successful response. Existing installations receive the fix by re-running the
+client installer after updating their checkout.
+
 **Setting up a server:** on a Linux x86_64 Docker host, as the workspace account:
 
 ```sh
@@ -75,9 +81,13 @@ The installer starts an empty catalog safely; it does not assume anyone's contai
 | Select a lane for pane 2 or 3 | `2` / `3` in the sidebar of a wide view |
 | Open one lane directly | `lanes-launch lane <lane-id>`; find IDs with `lanes-launch ls` |
 | Create a persistent workspace shell | **New +** under **Unregistered**, or `+` in the sidebar |
-| End an unregistered session and its jobs | **×** beside the session, or select it and press `x` |
+| Register an existing session | **+** beside an unregistered session, or select it and press `a`; choose a workspace |
+| See which agents need you | The sidebar sorts **Needs you** (◆ approval, ✗ error, ◇ waiting for a prompt), **Working** (▸) and **Done** (✓, until you open the lane) above the rest; the header counts them (`◆1 ◇2 ▸6 ✓1`) and every row shows how long (agent turn, else last output) |
+| End an unregistered session and its jobs | **×** beside the session, or select it and press `x`; confirm with `y` (any other key cancels) |
 | Upload | Drop onto the sidebar upload box, use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
 | Phone setup from a client | `sh install/enable-phone.sh --host lanes` |
+| Laptop or tablet browser view | `lanes web <device> --desktop [--token]` on the server, or `sh install/enable-phone.sh --host lanes --desktop <device>` ([guide](docs/INSTALL.md#laptop-and-tablet-browser)) |
+| Switch workspace or lane in a laptop browser | The **Lanes** chip (top right) opens the workspace and lane pickers |
 | Detach | Close the window; the agents keep running |
 
 Unregistered sessions also appear when they use shared or previously unlisted tmux servers. Reopening a
@@ -85,6 +95,10 @@ session reuses it; closing a view leaves it running. Registered lanes have no **
 Docker shells labelled **Legacy** are tracked and closable, but a lost Docker connection cannot be reopened;
 new shells support reconnection. See the [runbook](docs/RUNBOOK.md) for the transition details.
 
+**Add to workspace** keeps the session running and moves it into the selected workspace's registered list.
+The picker offers workspaces using the same container. Registration keeps its name and open views, persists
+across sync/reconnects, and removes its close control. On a phone, tap the **+** and a workspace; no typing is needed.
+
 On iPhone, open the printed private HTTPS URL in Safari and choose **Share → Add to Home Screen**.
 The interface provides Workspaces, Lanes and Panes controls, safe areas, portrait/landscape layout and adjustable
 terminal text. The keyboard opens when you tap **Type here** or another input; swipes and updates leave it closed.
@@ -119,6 +133,8 @@ It retains the previous lanes if a repository's registry is temporarily invalid.
 `lanes cursor-sync --diff` previews editor integration. `lanes cursor-sync --write` backs up and normalizes
 terminal commands to `lane open <id>`, retaining each original create recipe. Cursor and Lanes then attach
 to the same terminal. Registry sync does not copy repositories between machines or automatically create agents.
+Sessions added through the picker are saved in the site's `registered-sessions.json` and included by sync.
+These registrations attach to existing sessions; they do not invent a restart command or edit editor terminal lists.
 See [workspace configuration](workspaces.example/README.md) and the [architecture](docs/ARCHITECTURE.md).
 
 ## What is included
@@ -150,3 +166,42 @@ python3 -m unittest discover -s tests/unit # no Docker or live server needed
 
 For integration tests and browser verification, see [tests/README.md](tests/README.md).
 For recovery, service updates and troubleshooting, see the [runbook](docs/RUNBOOK.md).
+
+### Register a workspace once
+
+The host's site catalog (`LANES_WORKSPACES/catalog.json`, normally
+`~/.config/lanes/workspaces/catalog.json`) is the workspace authority. Add its
+manifest there and run `lanes sync`. The existing sync timer refreshes it every
+2 minutes; the ensure timer also reconciles known device sessions every minute.
+New desktop and phone tabs appear without rebuilding sessions or restarting
+agents. Changing a catalog title renames the existing tab using its workspace ID.
+Phone workspaces receive both their full-width picker and terminal tabs.
+When a device has no attached client, new tabs wait for its next connection and
+the next ensure tick (within a minute). This avoids empty background tabs in
+Zellij 0.45.1; existing workspace names can still update while disconnected.
+
+Fixed terminals on another host can use an optional `sshWorkspaces` entry:
+
+```json
+{
+  "id": "maintenance",
+  "title": "Maintenance",
+  "host": "maintenance-views",
+  "command": "/home/operator/.local/bin/workspace-session",
+  "layout": "lanes",
+  "position": "workspace",
+  "panes": [{"id": "fixes", "name": "Fixes"}]
+}
+```
+
+Put this object in the catalog's `sshWorkspaces` array. Configure the host SSH
+alias with its dedicated key and pinned host key. The command must attach to an
+existing persistent session. Lanes does not provision or terminate remote agents.
+`layout: "lanes"` uses the standard sidebar; `position: "before-host"` places a
+control workspace immediately before Host. Existing `split` layouts stay supported.
+Split workspaces can share an SSH host and helper when their pane IDs are distinct.
+An endpoint assigned to multiple split workspaces is ambiguous and refuses sync.
+
+While a viewer connects or reconnects, it shows a Syncing indicator and discards
+pending input. Mouse reporting is reset before and after the attach client, so
+queued escape sequences cannot become shell input during the connection wait.

package/payload/lanes/VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

package/payload/lanes/bin/lanes

@@ -1,17 +1,25 @@
 #!/usr/bin/env python3
 """lanes — host-level workspace server CLI. Python 3 stdlib only.
 
-  lanes sync                     rebuild registry.json from the repos' terminal registries (read-only)
+  lanes sync                     refresh the host catalog and reconcile workspaces on every known device
   lanes ls [--json] [workspace]  list lanes with live status
   lanes resolve <lane-id>        exact target of one lane as JSON (contract for the web harness)
   lanes status                   one-line-per-workspace health summary
   lanes attach <device> [--client ID] [--mobile] [--viewports N]
                                  attach this terminal to the device's view session (creates it if needed)
-  lanes prepare <device> [--mobile]  create a device view without attaching a terminal (eg. Safari on a phone)
+  lanes prepare <device> [--mobile|--desktop]
+                                 create a device view without attaching a terminal (eg. Safari on a phone); an explicit
+                                 layout that differs from the running view is refused, never rebuilt
+  lanes web <device> [--desktop|--mobile] [--viewports N] [--token | --print-only]
+                                 browser view in one step: prepare (desktop by default), enable the loopback web
+                                 services (install/enable-web.sh), print the private https://<tailnet name>:8443/<device>
+                                 URL; --token then shows a login token in YOUR terminal only
   lanes open <lane-id>           attach this terminal straight to one lane (no multiplexer in between)
+  lanes register <lane-id> [ws]  add an unregistered session to a workspace without restarting it
+                                 use lanes ls --unregistered [--json] to find its ID
   lanes layout <device> [--mobile]   print the generated zellij layout
   lanes rebuild <device>         recreate a device's view session (agents are never touched)
-  lanes upgrade-session [device…]  add tabs a newer layout has (e.g. Throttle) to LIVE sessions, without a rebuild
+  lanes upgrade-session [device…]  sync catalog tabs and labels to live sessions without a rebuild
   lanes ensure                   recreate any known device session that is missing (never when zellij did not answer:
                                  an unknown session list is not an empty one)
   lanes reattach                 make every view re-attach its lane (after changing flags); agents untouched
@@ -19,9 +27,14 @@
                                  read a tar stream on stdin into that board's uploads/ folder (the same folder Cursor
                                  users drop files into); prints the in-container paths. --paste also types the path(s)
                                  into the lane that device is looking at. `lanes workspaces` lists board ids.
-  lanes cursor-sync [ws…] [--write] [--diff]
+  lanes cursor-sync [ws…] [--write] [--diff] [--canonicalize] [--identity]
                                  make Cursor/VS Code terminals open exactly the board's lanes through `lane open`
-                                 (dry-run by default: prints the git-style diff; --write applies with a backup)
+                                 (dry-run by default: prints the git-style diff; --write applies with a backup).
+                                 --canonicalize also replaces a create recipe that cannot create its tmux lane (null,
+                                 attach-only, missing script) with the canonical one whose `tmux new -e` flags give the
+                                 lane LANE_ID/LANE_WS and the lanes/<ws>/<id> trace; --identity adds those flags to a
+                                 working plain `tmux -L S new -ADs N [-c D] CMD` recipe, keeping CMD. The old recipe is
+                                 kept as createPrevious. Only these -e flags give a lane its identity (DEF-1422)
   lanes cursor-commit [ws…] [--push]
                                  commit the normalized terminals.json on top of each repo's REMOTE branch tip and push it,
                                  with git plumbing only (no working tree or index is touched). Dry-run without --push.
@@ -83,16 +96,10 @@ def q(text):
 # ------------------------------------------------------------------- registry
 
 def cmd_sync(_args):
-    previous = L.read_json(L.STATE / 'registry.json')
-    registry = L.build_registry(previous)
-    L.atomic_write(L.STATE / 'registry.json', json.dumps(registry, indent=1, ensure_ascii=False) + '\n')
-    L.write_resolve_files(registry)
-    L.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['extras']
-        first = focus or (candidates[0] if candidates else None)
-        L.atomic_write(L.STATE / 'defaults' / workspace['id'], (first['id'] if first else '!empty') + '\n')
+    with L.registry_lock():
+        previous = L.read_json(L.STATE / 'registry.json')
+        registry = L.build_registry(previous)
+        L.publish_registry(registry)
     total = sum(len(w['lanes']) for w in registry['workspaces'])
     failed = [w for w in registry['workspaces'] if w['errors']]
     for workspace in registry['workspaces']:
@@ -101,18 +108,37 @@ def cmd_sync(_args):
         for error in workspace['errors']:
             print(f'    ⚠ {error}' + ('  (kept previous lanes)' if workspace.get('stale') else ''))
     print(f"{total} lanes in {len(registry['workspaces'])} workspaces" + (f'; {len(failed)} with errors' if failed else ''))
+    if any((L.STATE / 'devices').glob('*.json')):
+        cmd_upgrade_session([])
     return 1 if failed else 0
 
 
+def cmd_register(args):
+    if not 1 <= len(args) <= 2:
+        raise L.LanesError('Usage: lanes register <lane-id> [workspace]')
+    import registrations
+    workspace, entry = L.find_lane(L.load_registry(), args[0])
+    lane = registrations.register(workspace['id'], entry, args[1] if len(args) == 2 else None)
+    print(f"Registered {lane['name']} in {lane['workspace']}")
+
+
 def cmd_ls(args):
     registry = L.load_registry()
-    status = (L.read_json(L.STATE / 'status.json') or {}).get('lanes', {})
+    snapshot = L.read_json(L.STATE / 'status.json') or {}
+    status = snapshot.get('lanes', {})
+    import registrations
+    registered = {registrations.key(lane) for w in registry['workspaces'] for lane in w['lanes']
+                  if lane.get('holder') == 'tmux'}
     wanted = [a for a in args if not a.startswith('-')]
     rows = []
     for workspace in registry['workspaces']:
         if wanted and workspace['id'] not in wanted:
             continue
-        for lane in workspace['lanes']:
+        entries = ((snapshot.get('unregistered') or {}).get(workspace['id'], [])
+                   if '--unregistered' in args else workspace['lanes'])
+        for lane in entries:
+            if '--unregistered' in args and registrations.eligible(lane) and registrations.key(lane) in registered:
+                continue
             rows.append(dict(lane, workspace=workspace['id'], status=status.get(lane['id'], {'state': 'unknown'})))
     if '--json' in args:
         print(json.dumps(rows, indent=1, ensure_ascii=False))
@@ -154,47 +180,97 @@ def cmd_status(_args):
 
 # --------------------------------------------------------------------- views
 
+def tab_layout(lines):
+    return '\n'.join(['layout {', '    default_tab_template {', '        children',
+                      '        pane size=1 borderless=true {', '            plugin location="zellij:compact-bar"',
+                      '        }', '    }'] + lines + ['}']) + '\n'
+
+
+def tab_specs(device, registry, mobile=False, viewports=1):
+    result = []
+    def add(key, title, lines):
+        result.append({'key': key, 'title': title, 'lines': lines, 'layout': tab_layout(lines)})
+    def board(workspace):
+        if mobile:
+            for picker in (True, False):
+                role = 'picker' if picker else 'view'
+                title = workspace['title'] + (' ☰' if picker else '')
+                add(f"workspace/{workspace['id']}/{role}", title, mobile_workspace_tab(device, workspace, picker))
+        else:
+            add(f"workspace/{workspace['id']}/view", workspace['title'], workspace_tab_kdl(device, workspace, False, viewports))
+    for workspace in registry['workspaces']:
+        if workspace.get('position') != 'before-host': board(workspace)
+    for workspace in registry.get('ssh_workspaces', []):
+        add('ssh/' + workspace['id'], workspace['title'], ssh_workspace_tab_kdl(workspace))
+    for tool in registry.get('tools', []):
+        add('tool/' + tool['view'], tool['tab'], tool_tab_kdl(device, tool, mobile=mobile))
+    for workspace in registry['workspaces']:
+        if workspace.get('position') == 'before-host': board(workspace)
+    add('host', 'Host', ['    tab name="Host" {', '        pane command="/bin/bash" {', '            args "-l"', '        }', '    }'])
+    return result
+
+
 def layout_kdl(device, mobile=False, viewports=1):
-    registry = L.load_registry()
+    specs = tab_specs(device, L.load_registry(), mobile, viewports)
+    lines = []
+    for index, spec in enumerate(specs):
+        tab = list(spec['lines'])
+        if index == 0:
+            tab[0] = tab[0].replace(' {', ' focus=true {', 1)
+        lines += tab
+    return tab_layout(lines)
+
+
+def mobile_workspace_tab(device, workspace, picker):
+    title = workspace['title'] + (' ☰' if picker else '')
+    command = str(L.REPO / 'libexec' / ('sidebar' if picker else 'view.sh'))
+    args = f'{q(device)} {q(workspace["id"])}' + ('' if picker else ' "main" "--mobile"')
+    return [f'    tab name={q(title)} {{',
+            f'        pane borderless=true name={q("Lanes" if picker else workspace["title"])} command={q(command)} {{',
+            f'            args {args}', '        }', '    }']
+
+
+def workspace_tab_kdl(device, workspace, mobile=False, viewports=1, focused=False):
     sidebar, view = str(L.REPO / 'libexec/sidebar'), str(L.REPO / 'libexec/view.sh')
-    lines = ['// Generated by `lanes layout`. Lanes are NOT part of this layout: adding, removing or',
-             '// reordering lanes only changes registry.json, so this layout never needs live surgery.',
-             'layout {',
-             '    default_tab_template {',
-             '        children',
-             '        pane size=1 borderless=true {',
-             '            plugin location="zellij:compact-bar"',
-             '        }',
-             '    }']
-    for index, workspace in enumerate(registry['workspaces']):
-        focus = ' focus=true' if index == 0 else ''
-        if mobile:
-            lines += [f'    tab name={q(workspace["title"] + " ☰")}{focus} {{',
-                      f'        pane borderless=true name="Lanes" command={q(sidebar)} {{',
-                      f'            args {q(device)} {q(workspace["id"])}',
-                      '        }', '    }',
-                      f'    tab name={q(workspace["title"])} {{',
-                      f'        pane borderless=true name={q(workspace["title"])} command={q(view)} {{',
-                      f'            args {q(device)} {q(workspace["id"])} "main" "--mobile"',
-                      '        }', '    }']
-            continue
-        lines += [f'    tab name={q(workspace["title"])}{focus} {{',
-                  '        pane split_direction="vertical" {',
-                  f'            pane size=36 borderless=true name="Lanes" command={q(sidebar)} {{',
-                  f'                args {q(device)} {q(workspace["id"])} "main" {q(str(viewports))}',
+    focus = ' focus=true' if focused else ''
+    lines = []
+    if mobile:
+        return mobile_workspace_tab(device, workspace, True) + mobile_workspace_tab(device, workspace, False)
+    lines += [f'    tab name={q(workspace["title"])}{focus} {{',
+              '        pane split_direction="vertical" {',
+              f'            pane size=36 borderless=true name="Lanes" command={q(sidebar)} {{',
+              f'                args {q(device)} {q(workspace["id"])} "main" {q(str(viewports))}',
+              '            }']
+    # Wide devices: several viewports side by side, each with its own target (slots main, b, c).
+    for index, slot in enumerate(SLOTS[:viewports]):
+        title = workspace['title'] if index == 0 else f"{workspace['title']} ·{index + 1}"
+        pane_focus = ' focus=true' if index == 0 else ''
+        lines += [f'            pane borderless={"true" if viewports == 1 else "false"}{pane_focus} name={q(title)} command={q(view)} {{',
+                  f'                args {q(device)} {q(workspace["id"])} {q(slot)}',
                   '            }']
-        # Wide devices: several viewports side by side, each with its own target (slots main, b, c).
-        for index, slot in enumerate(SLOTS[:viewports]):
-            title = workspace['title'] if index == 0 else f"{workspace['title']} ·{index + 1}"
-            pane_focus = ' focus=true' if index == 0 else ''
-            lines += [f'            pane borderless={"true" if viewports == 1 else "false"}{pane_focus} name={q(title)} command={q(view)} {{',
-                      f'                args {q(device)} {q(workspace["id"])} {q(slot)}',
-                      '            }']
-        lines += ['        }', '    }']
-    for tool in registry.get('tools', []):
-        lines += tool_tab_kdl(device, tool, mobile=mobile)
-    lines += ['    tab name="Host" {', '        pane command="/bin/bash" {', '            args "-l"', '        }', '    }', '}']
-    return '\n'.join(lines) + '\n'
+    lines += ['        }', '    }']
+    return lines
+
+
+def ssh_workspace_tab_kdl(workspace, indent='    '):
+    """Main terminal on the left; up to two worker terminals stacked on the right."""
+    holder = str(L.REPO / 'holders/ssh.sh')
+    panes = workspace['panes']
+    lines = [f'{indent}tab name={q(workspace["title"])} split_direction="vertical" {{']
+
+    def pane_lines(pane, prefix, size=''):
+        return [f'{prefix}pane name={q(pane["name"])}{size} command={q(holder)} {{',
+                f'{prefix}    args {q(workspace["host"])} {q(workspace["command"])} {q(pane["id"])}',
+                f'{prefix}}}']
+
+    lines += pane_lines(panes[0], indent + '    ', ' size="60%"' if len(panes) > 1 else '')
+    if len(panes) > 1:
+        lines.append(f'{indent}    pane split_direction="horizontal" {{')
+        for pane in panes[1:]:
+            lines += pane_lines(pane, indent + '        ')
+        lines.append(f'{indent}    }}')
+    lines.append(f'{indent}}}')
+    return lines
 
 
 def tool_tab_kdl(device, tool, indent='    ', mobile=False):
@@ -294,7 +370,11 @@ def cmd_attach(args):
     tab = None
     default = args[args.index('--default-device') + 1] if '--default-device' in args[:-1] else None
     try:
-        workspace = next((w for w in L.load_registry()['workspaces'] if w['id'] == device), None)
+        registry = L.load_registry()
+        boards = registry['workspaces'] + registry.get('ssh_workspaces', [])
+        workspace = next((w for w in boards if w['id'] == device), None)
+        if device == default or (not default and (L.STATE / 'devices' / f'{device}.json').exists()):
+            workspace = None
     except L.LanesError:
         workspace = None
     if workspace:
@@ -371,7 +451,7 @@ def cmd_open(args):
     if not resolve.exists():
         raise L.LanesError(f'Unknown lane: {lane_id}')
     holder, a, b, c = resolve.read_text().split('\n')[:4]
-    if holder not in ('tmux', 'zmx', 'exec'):
+    if holder not in ('tmux', 'zmx', 'exec', 'ssh'):
         raise L.LanesError(f'Unknown holder: {holder}')
     env = clean_env({'TERM': 'xterm-256color', 'LANES_WS': lane_id.split('--')[0]})
     os.execve(str(L.REPO / 'holders' / f'{holder}.sh'), [f'{holder}.sh', a, b, c], env)
@@ -441,31 +521,23 @@ def cmd_rebuild(args):
 
 
 def cmd_upgrade_session(args):
+    import device_sync
     registry = L.load_registry()
     live = live_sessions()
     devices = [device_name(a) for a in args] or [p.stem for p in sorted((L.STATE / 'devices').glob('*.json'))]
+    failures = []
     for device in devices:
         if device not in live:
-            print(f'{device}: not running (it gets the current layout when it is next created)')
-            continue
-        rc, out, _err = zellij(['-s', device, 'action', 'list-tabs', '-j'], 20)
-        if rc != 0:   # unknown tabs are not missing tabs: add nothing
-            print(f'{device}: zellij did not answer; left alone')
-            continue
-        tabs = json.loads(out or '[]')
-        names = {tab.get('name') for tab in tabs}
-        for tool in registry.get('tools', []):
-            if tool['tab'] in names:
-                print(f"{device}: tab '{tool['tab']}' already present")
-                continue
-            layout = '\n'.join(['layout {', '    default_tab_template {', '        children',
-                                '        pane size=1 borderless=true {', '            plugin location="zellij:compact-bar"',
-                                '        }', '    }'] + tool_tab_kdl(device, tool) + ['}'])
-            active = next((tab for tab in tabs if tab.get('active')), None)
-            zellij(['-s', device, 'action', 'new-tab', '--name', tool['tab'], '--layout-string', layout], 30)
-            if active:  # new-tab takes the focus: hand it back to where the user was
-                zellij(['-s', device, 'action', 'go-to-tab-name', active['name']], 15)
-            print(f"{device}: added tab '{tool['tab']}'")
+            continue  # ensure recreates missing sessions with the same catalog
+        meta = L.read_json(L.STATE / 'devices' / (device + '.json')) or {}
+        mobile, viewports = bool(meta.get('mobile')), int(meta.get('viewports') or 1)
+        try:
+            for change in device_sync.reconcile(device, registry, tab_specs(device, registry, mobile, viewports), mobile, zellij):
+                print(f'{device}: {change}')
+        except (L.LanesError, ValueError, KeyError) as error:
+            failures.append(str(error))
+    if failures:
+        raise L.LanesError('; '.join(failures))
     return 0
 
 
@@ -493,19 +565,116 @@ def cmd_ensure(_args):
             meta = L.read_json(meta_file) or {}
             create_session(device, bool(meta.get('mobile')), int(meta.get('viewports') or 1))
             print(f'recreated view session {device}')
-    return 0
+    return cmd_upgrade_session([])
 
 
-def cmd_prepare(args):
-    device = device_name(args[0])
+def prepare_view(device, mobile, viewports=1, explicit=False):
+    """Create the device's view session unless it runs -> 'created' | 'reused'. A running view is never rebuilt:
+    a mobile request refuses a desktop view, and an EXPLICIT desktop request (`--desktop`, `lanes web`) refuses a
+    mobile one. Without a flag, `prepare` keeps reusing whatever layout runs."""
     if device not in live_sessions():
-        create_session(device, '--mobile' in args, viewports_arg(args))
-    elif '--mobile' in args and not (L.read_json(L.STATE / 'devices' / f'{device}.json') or {}).get('mobile'):
+        create_session(device, mobile, viewports)
+        return 'created'
+    running_mobile = bool((L.read_json(L.STATE / 'devices' / f'{device}.json') or {}).get('mobile'))
+    if mobile and not running_mobile:
         raise L.LanesError(f'{device} already has a desktop layout; choose another device name')
+    if explicit and not mobile and running_mobile:
+        raise L.LanesError(f'{device} already has a mobile layout; choose another device name')
+    return 'reused'
+
+
+def cmd_prepare(args):
+    device = device_name(args[0])
+    if '--mobile' in args and '--desktop' in args:
+        raise L.LanesError('--mobile and --desktop are exclusive')
+    prepare_view(device, '--mobile' in args, viewports_arg(args), explicit='--desktop' in args)
     print(f'ready: {device}')
     return 0
 
 
+WEB_LOOPBACK = 'http://127.0.0.1:8083'   # lanes-mobile.service (web/Caddyfile); Tailscale Serve forwards :8443 here
+WEB_USAGE = 'usage: lanes web <device> [--desktop|--mobile] [--viewports N] [--token | --print-only]'
+
+
+def tailnet_name():
+    """This node's MagicDNS name, read the way install/enable-phone.sh reads it; None when tailscale is absent,
+    silent or has no name. Read-only: Tailscale Serve itself is configured once by enable-phone.sh."""
+    if not shutil.which('tailscale'):
+        return None
+    rc, out, _err = L.run_bounded(['tailscale', 'status', '--json'], 10)
+    if rc != 0:
+        return None
+    try:
+        name = (json.loads(out).get('Self') or {}).get('DNSName') or ''
+    except (ValueError, AttributeError):
+        return None
+    return name.rstrip('.') or None
+
+
+def cmd_web(args):
+    """lanes web <device> [--desktop|--mobile] [--viewports N] [--token | --print-only]
+
+    One command for a browser view (laptop, tablet, phone): prepare the device's view (idempotent; a running view
+    of the other layout is refused, never rebuilt), enable the loopback web services through install/enable-web.sh,
+    print the private URL. Without --desktop/--mobile a known device (devices/<device>.json) keeps its recorded
+    layout, exactly as a flagless `lanes prepare` reuses whatever runs; only a new device defaults to desktop.
+    --token execs the pinned `zellij web --create-token` exactly as enable-phone.sh does, in the caller's terminal
+    only; lanes never prints or logs a token. --print-only changes nothing. Output: `key: value` lines
+    (DM-LANES-WEB-CLI v1)."""
+    words, skip = [], False
+    for arg in args:
+        if skip:
+            skip = False
+        elif arg == '--viewports':
+            skip = True
+        elif arg.startswith('-'):
+            if arg not in ('--desktop', '--mobile', '--token', '--print-only'):
+                raise L.LanesError(f'unknown option {arg}; {WEB_USAGE}')
+        else:
+            words.append(arg)
+    if len(words) != 1:
+        raise L.LanesError(WEB_USAGE)
+    device = device_name(words[0])
+    if '--mobile' in args and '--desktop' in args:
+        raise L.LanesError('--mobile and --desktop are exclusive')
+    explicit = '--mobile' in args or '--desktop' in args
+    known = None if explicit else L.read_json(L.STATE / 'devices' / f'{device}.json')
+    mobile = bool(known.get('mobile')) if isinstance(known, dict) else '--mobile' in args
+    viewports = viewports_arg(args)
+    token, print_only = '--token' in args, '--print-only' in args
+    if token and print_only:
+        raise L.LanesError('--token and --print-only are exclusive')
+    if token and not (sys.stdin.isatty() and sys.stdout.isatty()):
+        print('lanes: run `lanes web --token` in your own terminal; it displays a private login token.', file=sys.stderr)
+        return 64
+    if token and not Path(ZELLIJ_BASE[0]).exists():
+        raise L.LanesError(f'{ZELLIJ_BASE[0]} is not installed: run install/host-install.sh')
+    flag = '--mobile' if mobile else '--desktop'
+    prepare = ['lanes', 'prepare', device, flag] + (['--viewports', str(viewports)] if viewports != 1 else [])
+    state = 'planned'
+    if not print_only:
+        state = prepare_view(device, mobile, viewports, explicit=explicit)
+        rc, out, err = L.run_bounded(['sh', str(L.REPO / 'install/enable-web.sh'), device, flag], 180)
+        if rc != 0:
+            raise L.LanesError('install/enable-web.sh: ' + ('no answer in 180 s' if rc is None
+                                                           else err.strip() or out.strip() or f'exit {rc}'))
+    dns = tailnet_name()
+    lines = [('device', device), ('layout', 'mobile' if mobile else 'desktop'), ('state', state),
+             ('prepare', ' '.join(prepare)), ('services', f'sh install/enable-web.sh {device} {flag}'),
+             ('url', f'https://{dns}:8443/{device}' if dns else f'{WEB_LOOPBACK}/{device}')]
+    if not dns:
+        lines.append(('note', 'no Tailscale name on this host: the loopback URL opens only here; '
+                              'there is no public fallback by design (docs/INSTALL.md)'))
+    if not token:
+        lines.append(('next', f'lanes web {device} {flag} --token   (in your own terminal: a login token)'))
+    print(''.join(f'{key}: {value}\n' for key, value in lines), end='')
+    if token:
+        print('\nThe last line is NAME: TOKEN. Paste only TOKEN into the sign-in screen.\n', flush=True)
+        # Zellij 0.45.1 requires --create-token by itself; --token-name cannot accompany it (enable-phone.sh).
+        os.execv(ZELLIJ_BASE[0], ZELLIJ_BASE + ['web', '--create-token'])
+    return 0
+
+
 # ------------------------------------------------------------------ safety
 
 PANE_FORMAT = '#{session_name}\t#{window_index}.#{pane_index}\t#{pane_pid}\t#{window_width}x#{window_height}'
@@ -911,22 +1080,22 @@ def cmd_doctor(_args):
     if registry:
         errors = [(w['id'], e) for w in registry['workspaces'] for e in w['errors']]
         check(not errors, 'registry clean', '; '.join(f'{w}: {e}' for w, e in errors))
-        # Stale registry check: any terminals.json newer than the last sync?
+        # Stale registry check: any terminals.json newer than the last sync? A lane's `source` is the container's
+        # spelling; doctor runs on the host, so it stats the file under the container's home volume.
+        sys.path.insert(0, str(L.REPO / 'libexec'))
+        import statusd as SD
         generated_at = registry.get('generated_at', 0)
+        containers = L.read_json(L.STATE / 'containers.json') or {}
         stale_sources = []
-        for w in registry['workspaces']:
-            for lane in w.get('lanes', []):
-                src = lane.get('source')
-                if src:
-                    try:
-                        if Path(src).stat().st_mtime > generated_at:
-                            stale_sources.append(src)
-                    except OSError:
-                        pass
-        unique_stale = list(dict.fromkeys(stale_sources))
-        check(not unique_stale, 'registry up to date',
-              'run lanes sync — ' + '; '.join(unique_stale[:3]) + (' …' if len(unique_stale) > 3 else ''))
-        for name, info in (L.read_json(L.STATE / 'containers.json') or {}).items():
+        for src, path in SD.registry_source_paths(registry, containers):
+            try:
+                if path.stat().st_mtime > generated_at:
+                    stale_sources.append(src)
+            except OSError:
+                pass
+        check(not stale_sources, 'registry up to date',
+              'run lanes sync — ' + '; '.join(stale_sources[:3]) + (' …' if len(stale_sources) > 3 else ''))
+        for name, info in containers.items():
             check(bool(info.get('running')), f'container {name} running', f"init pid {info.get('pid')}")
     status = L.read_json(L.STATE / 'status.json') or {}
     age = time.time() - status.get('updated_at', 0)
@@ -980,7 +1149,8 @@ def cmd_rename(args):
 
     Rename a lane's display name.
     - Unregistered sessions: writes user-sessions metadata + updates resolve.dynamic.
-    - Registered lanes: writes a displayNames override to the workspace manifest and syncs the registry.
+    - Registered sessions (adopted): writes the record's name in registered-sessions.json and publishes.
+    - Repository lanes: writes a displayNames override to the workspace manifest and syncs the registry.
     """
     if len(args) < 2:
         raise L.LanesError('usage: lanes rename <lane-id> <new-name>')
@@ -1008,21 +1178,28 @@ def cmd_rename(args):
                     return 0
     if not lane:
         raise L.LanesError(f'Unknown lane: {lane_id}')
-    # Registered lane: update displayNames in manifest
-    source = lane.get('source')
-    if not source:
-        raise L.LanesError('No manifest source for this lane; set displayNames in the workspace manifest manually')
+    # An adopted session (Add to workspace / `lanes register`) takes its name from registered-sessions.json,
+    # which is the one file renamed here; its id and binding never change (DEF-1412).
+    if lane.get('registered_session'):
+        import registrations
+        registrations.rename(lane_id, new_name)
+        print(f"renamed registered session {lane_id!r} → {new_name!r}")
+        return 0
+    # Registered lane: a displayNames override in the board's manifest (repositories[i]), never terminals.json
+    # (the lane's `source`, which the reader does not consult for display names). The lane id does not change.
+    if not lane.get('repo'):
+        raise L.LanesError('No repository for this lane; set displayNames in the workspace manifest manually')
     registry_name = lane.get('registry_name') or lane.get('name', '')
-    SA.rename_registered(source, registry_name, new_name)
+    SA.rename_registered(L.manifest_path(workspace_obj['id']), lane['repo'], registry_name, new_name)
     cmd_sync([])   # rebuild registry so all consumers see the new name
     print(f"renamed registered lane {lane_id!r} ({registry_name!r}) → {new_name!r}")
     return 0
 
 
 COMMANDS = {'rebuilt': cmd_rebuilt, 'hello': cmd_hello, 'client-config': cmd_client_config, 'cursor-commit': cmd_cursor_commit, 'upgrade-session': cmd_upgrade_session, 'upload-requests': cmd_upload_requests, 'upload-result': cmd_upload_result, 'upload': cmd_upload, 'workspaces': cmd_workspaces, 'cursor-sync': cmd_cursor_sync, 'reattach': cmd_reattach, 'gc': cmd_gc, 'install-container': cmd_install_container, 'open': cmd_open, 'sync': cmd_sync, 'ls': cmd_ls, 'resolve': cmd_resolve, 'status': cmd_status, 'layout': cmd_layout,
-            'prepare': cmd_prepare, 'attach': cmd_attach, 'rebuild': cmd_rebuild, 'ensure': cmd_ensure, 'invariant': cmd_invariant,
+            'prepare': cmd_prepare, 'web': cmd_web, 'attach': cmd_attach, 'rebuild': cmd_rebuild, 'ensure': cmd_ensure, 'invariant': cmd_invariant,
             'verify-legacy': cmd_verify_legacy, 'doctor': cmd_doctor, 'pressure': cmd_pressure, 'sockets': cmd_sockets, 'tmp': cmd_tmp,
-            'guard': cmd_guard, 'rename': cmd_rename}
+            'guard': cmd_guard, 'rename': cmd_rename, 'register': cmd_register}
 
 if __name__ == '__main__':
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS: