@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/bin/lanes

@@ -1,17 +1,27 @@
 #!/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)
+               [--ascii] [--glyphs unicode|ascii|emoji] [--theme dark|light|auto] [--color truecolor|16|none]
+                                 attach this terminal to the device's view session (creates it if needed); the look
+                                 flags are remembered in devices/<device>.json and reach its running sidebars in a tick
+  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,17 +29,26 @@
                                  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-1478)
   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.
   lanes hello [device]           what the client installer calls to prove the path, the key and the server version
   lanes client-config            site facts for clients (KEY=VALUE from ~/.config/lanes/site.conf on the server)
-  lanes install-container <name> install the `lane` contract + pinned zmx into a container's home volume (additive)
+  lanes install-container <name> install the `lane` contract (lane, lane-run, lane-signal, hooks/) + pinned zmx into a
+                                 container's home volume (additive; installs no agent hook)
+  lanes hooks install --agent claude|codex (--container <name> | --home <dir>) [--dry-run | --write]
+                                 merge the lane-signal hooks into that home's ~/.claude/settings.json or ~/.codex/hooks.json
+                                 (+ a top-level Codex notify when none is set); prints the diff, writes only with --write
+                                 (backup kept). Opt-in, per container; Codex still asks you to trust new hooks
   lanes invariant save|check     snapshot / verify every live pane's pid and window size
-  lanes verify-legacy            compare the registry with the old in-container coder-launch layouts
   lanes gc                       truncate oversized zmx logs, drop stale dynamic resolve files
   lanes sockets [check|repair]   lanes that run but cannot be reached: tmux servers whose socket file was deleted
                                  (someone emptied the container's /tmp); repair = tmux's SIGUSR1, nothing restarts
@@ -42,7 +61,32 @@
                                  one pass, by hand, that makes the next in-container out-of-memory kill take a build, never
                                  a lane: raises oom_score_adj of compilers / test runners by exact name (libexec/guard.py).
                                  No timer runs it: look at --dry-run first. The recurring half is sudo/host-guard.sh
-  lanes doctor                   full health check (every external call is bounded; includes the pressure summary)
+  lanes economy --once [--dry-run] [--status-file F --sessions-file F]
+                                 one economy poll (libexec/economy_poll.py): the Throttle daemon's loopback /status and
+                                 /sessions plus today's proxy.log fold, printed as the economy.json v1 projection
+                                 (--dry-run writes neither economy.json nor its cursor). LANES_THROTTLE_CONTROL=none
+                                 contacts no daemon; the --*-file options read fixture documents instead; stderr names
+                                 each source it could not read. LANES_THROTTLE_CONTAINER=NAME reads that container's
+                                 log through its home volume. The recurring poller is lanes-economy.service, which no
+                                 install enables (operator gate, RUNBOOK)
+  lanes next|prev --focused [--device D]
+                                 what Ctrl-Alt-Down / Ctrl-Alt-Up run in a floating pane that closes on exit: point the
+                                 focused viewport (the first one when the sidebar has the focus) at the next / previous
+                                 lane of its board in registry order, wrapping, and wake its view.sh (SIGUSR1) — the
+                                 same write as Enter in the sidebar. Reads two zellij listings; moves no focus
+  lanes preview --focused [--device D]
+                                 what Ctrl-Alt-m runs in a floating pane: the markdown files the focused lane named in
+                                 its last 300 lines (guarded tmux capture, resolved against its cwd, existing ones only),
+                                 newest first; one is shown at once, several give a numbered menu. glow (pinned in
+                                 holders.lock) in the device's dark/light theme, else less -R
+  lanes doctor                   full health check (every external call is bounded; includes the pressure summary), with
+                                 the lanes per create-recipe class (idempotent / attach-only / null / external /
+                                 retired-path), lane identity, numeric session names, crowded `default` sockets and
+                                 orphan tmux socket files (report only; in a container `lane gc --sockets` removes them),
+                                 and any record left in the retired legacy-sessions/ directory
+  lanes device list | forget <name>
+                                 the devices `lanes ensure` recreates view sessions for; forget removes devices/<name>.json
+                                 (a running view session is left alone and is not brought back once it ends)
 """
 import json
 import os
@@ -83,16 +127,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 +139,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 +211,121 @@ def cmd_status(_args):
 
 # --------------------------------------------------------------------- views
 
-def layout_kdl(device, mobile=False, viewports=1):
-    registry = L.load_registry()
-    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 ''
+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:
-            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"',
-                      '        }', '    }']
+            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):
+    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"')
+    # The picker's sidebar pane has NO layout name: Zellij reports a non-empty pane name instead of the pane's own
+    # OSC 2 title, and that title (the attention counts) is what the phone reads (DEF-1450).
+    name = '' if picker else f' name={q(workspace["title"])}'
+    return [f'    tab name={q(title)} {{',
+            f'        pane borderless=true{name} command={q(command)} {{',
+            f'            args {args}', '        }', '    }']
+
+
+def stale_picker_layouts():
+    """Phone devices whose stored layout still names the picker's sidebar pane (the pre-Task 26 `name="Lanes"`).
+
+    `upgrade-session` / `ensure` only add missing tabs and rename titles: a picker tab created from an older layout
+    keeps its pane name, which Zellij reports instead of the OSC 2 counts, until `lanes rebuild <device>` (DEF-1450).
+    `create_session` is the only writer of layouts/<device>.kdl, so the file is the layout the session was built from.
+    """
+    sidebar = str(L.REPO / 'libexec' / 'sidebar')
+    stale = []
+    for meta_file in sorted((L.STATE / 'devices').glob('*.json')):
+        if not (L.read_json(meta_file) or {}).get('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))}',
+        try:
+            text = (L.STATE / 'layouts' / f'{meta_file.stem}.kdl').read_text()
+        except OSError:
+            continue
+        if any('name="Lanes"' in line and f'command={q(sidebar)}' in line for line in text.splitlines()):
+            stale.append(meta_file.stem)
+    return stale
+
+
+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')
+    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):
@@ -249,9 +380,16 @@ def create_session(device, mobile, viewports=1):
     L.atomic_write(layout_file, layout_kdl(device, mobile, viewports))
     meta_file = L.STATE / 'devices' / f'{device}.json'
     meta = {'version': 1, 'mobile': mobile, 'viewports': viewports, 'created_at': time.time()}
-    base = (L.read_json(meta_file) or {}).get('base')
-    if base:   # learnt at attach (see base_device); `ensure` and `rebuild` must not forget it
-        meta['base'] = base
+    old = L.read_json(meta_file) if meta_file.exists() else None
+    old = old if isinstance(old, dict) else {}
+    if old.get('base'):   # learnt at attach (see base_device); `ensure` and `rebuild` must not forget it
+        meta['base'] = old['base']
+    # The look `lanes attach --ascii|--glyphs|--theme|--color` recorded (record_look) is the operator's choice, not
+    # session state: a recreation (ensure after a reboot, rebuild) keeps every valid one, or every sidebar of the
+    # device would flip back to the environment defaults within one tick of this rewrite.
+    for key, allowed in LOOK_KEYS.values():
+        if old.get(key) in allowed:
+            meta[key] = old[key]
     L.atomic_write(meta_file, json.dumps(meta) + '\n')
     command = ZELLIJ_BASE + ['--layout', str(layout_file), 'attach', '--create-background', device]
     if shutil.which('systemd-run'):
@@ -282,6 +420,39 @@ def viewports_arg(args, default=1):
     return default
 
 
+LOOK_KEYS = {'--theme': ('theme', ('dark', 'light', 'auto')), '--color': ('color', ('truecolor', '16', 'none')),
+             '--glyphs': ('glyphs', ('unicode', 'ascii', 'emoji'))}
+
+
+def look_args(args):
+    """The look `lanes attach` was asked for: {'glyphs'|'theme'|'color': value}, validated (spec §2.4)."""
+    look = {}
+    if '--ascii' in args:
+        look['glyphs'] = 'ascii'
+    for flag, (key, allowed) in LOOK_KEYS.items():
+        if flag in args:
+            value = args[args.index(flag) + 1] if flag in args[:-1] else ''
+            if value not in allowed:
+                raise L.LanesError(f'{flag} must be one of {", ".join(allowed)}')
+            look[key] = value
+    return look
+
+
+def record_look(device, args):
+    """`lanes attach DEVICE --ascii|--glyphs M|--theme T|--color C`: remembered in devices/<device>.json, the file every
+    sidebar of that device re-reads when it changes (its reload() stamp), so a RUNNING session follows within one tick.
+    Returns what was recorded: empty when nothing was asked — or when the device has no file yet, because `ensure`
+    builds a session for every devices/*.json and a look flag must never create that stub on its own."""
+    look = look_args(args)
+    meta_file = L.STATE / 'devices' / f'{device}.json'
+    meta = L.read_json(meta_file) if meta_file.exists() else None
+    if not look or not isinstance(meta, dict):
+        return {}
+    if any(meta.get(key) != value for key, value in look.items()):
+        L.atomic_write(meta_file, json.dumps(dict(meta, **look)) + '\n')
+    return look
+
+
 def cmd_layout(args):
     print(layout_kdl(device_name(args[0]), '--mobile' in args, viewports_arg(args)), end='')
     return 0
@@ -289,12 +460,17 @@ def cmd_layout(args):
 
 def cmd_attach(args):
     device = device_name(args[0])
+    look_args(args)          # a bad --theme/--color/--glyphs refuses here, before any session is created
     # Old muscle memory: `coder-launch worlds`. A workspace id is not a device: open the caller's normal
     # device session and bring that workspace's tab to the front.
     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:
@@ -325,6 +501,7 @@ def cmd_attach(args):
     meta = L.read_json(meta_file) or {}
     if default and meta and meta.get('base') != base_device(device, default):
         L.atomic_write(meta_file, json.dumps(dict(meta, base=base_device(device, default))) + '\n')
+    record_look(device, args)
     # Views idle until a real client (with a real size) has attached once. We exec into the zellij
     # client below, so a detached helper raises the flag shortly after the client has sized the session.
     ready = L.STATE / 'clients' / f'{device}.ready'
@@ -371,7 +548,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)
@@ -405,8 +582,13 @@ def cmd_install_container(args):
     root = Path(info['home']) / '.lz'
     for sub in ('bin', 's', 'meta', 'state'):
         (root / sub).mkdir(parents=True, exist_ok=True)
-    for source in (L.REPO / 'container/lane', L.REPO / 'container/lane-run'):
+    for source in (L.REPO / 'container/lane', L.REPO / 'container/lane-run', L.REPO / 'container/lane-signal'):
         shutil.copy2(source, root / 'bin' / source.name)
+    # The hook DEFINITIONS travel with the contract for reference; no hook is installed here — that is the opt-in,
+    # per-container `lanes hooks install --agent claude|codex --container <name> --write` (RUNBOOK).
+    (root / 'hooks').mkdir(exist_ok=True)
+    for source in sorted((L.REPO / 'container/hooks').glob('*.json')):
+        shutil.copy2(source, root / 'hooks' / source.name)
     env_file = L.REPO / 'container/env.sh'   # TMPDIR off the RAM-backed /tmp; only NEW shells and agents read it
     if env_file.exists():
         shutil.copy2(env_file, root / 'env.sh')
@@ -420,8 +602,139 @@ def cmd_install_container(args):
     if link.is_symlink() or link.exists():
         link.unlink()
     link.symlink_to(root)
-    print(f'installed {root}/bin/{{lane,lane-run,zmx-*}}' + (f' and {root}/env.sh' if env_file.exists() else '')
-          + f'; host link {link} -> {root}')
+    print(f'installed {root}/bin/{{lane,lane-run,lane-signal,zmx-*}}, {root}/hooks/'
+          + (f' and {root}/env.sh' if env_file.exists() else '') + f'; host link {link} -> {root}')
+    return 0
+
+
+HOOK_TARGETS = {'claude': ('claude-settings.json', '.claude/settings.json'),
+                'codex': ('codex-hooks.json', '.codex/hooks.json')}
+HOOKS_USAGE = ('usage: lanes hooks install --agent claude|codex (--container <name> | --home <dir>) '
+               '[--dry-run | --write]')
+
+
+def render_hooks(agent):
+    """The shipped hook definitions with `~/` spelled as the container home: the command reaches lane-signal whether
+    or not the harness runs it through a shell that expands `~`."""
+    doc = json.loads((L.REPO / 'container/hooks' / HOOK_TARGETS[agent][0]).read_text())
+    for groups in doc['hooks'].values():
+        for group in groups:
+            for hook in group['hooks']:
+                hook['command'] = hook['command'].replace('~/', L.CONTAINER_HOME + '/', 1)
+    return doc
+
+
+def is_lane_signal_group(group):
+    hooks = group.get('hooks') if isinstance(group, dict) else None
+    return bool(hooks) and all(isinstance(h, dict) and 'lane-signal' in str(h.get('command') or '') for h in hooks)
+
+
+def merge_hooks(existing, ours):
+    """`existing` (a settings.json / hooks.json document) with every lane-signal group from an earlier install removed
+    and `ours` appended per event. Every other key, event and group stays exactly where it was."""
+    merged = dict(existing)
+    hooks = existing.get('hooks', {})
+    if not isinstance(hooks, dict) or not all(isinstance(groups, list) for groups in hooks.values()):
+        raise L.LanesError('the existing file has a "hooks" value that is not {event: [groups]} — fix it by hand first')
+    out = {}
+    for event, groups in hooks.items():
+        kept = [group for group in groups if not is_lane_signal_group(group)]
+        if kept or event in ours['hooks']:
+            out[event] = kept
+    for event, groups in ours['hooks'].items():
+        out[event] = out.get(event, []) + groups
+    merged['hooks'] = out
+    return merged
+
+
+def codex_notify(text):
+    """config.toml with a top-level `notify` that hands Codex's turn-complete to lane-signal, or `text` unchanged when
+    a top-level `notify` already exists (an operator's own notifier is never replaced). The line goes first, so it is
+    top level whatever tables follow; a `notify` inside a table is not Codex's notify."""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith('['):
+            break
+        if re.match(r'notify\s*=', stripped):
+            return text
+    argv = [f'{L.CONTAINER_HOME}/.lz/bin/lane-signal', 'done', '--harness', 'codex', '--event', 'notify']
+    return ('# lanes: Codex turn-complete -> lane-signal (lanes hooks install)\nnotify = '
+            + json.dumps(argv) + '\n' + text)
+
+
+def show_change(path, before, after):
+    import difflib
+    if before == after:
+        print(f'{path}: no change')
+        return False
+    sys.stdout.writelines(difflib.unified_diff(before.splitlines(True), after.splitlines(True),
+                                               f'{path} (now)', f'{path} (with lanes hooks)'))
+    return True
+
+
+def write_with_backup(path, before, after):
+    """Atomic replace, the previous bytes kept beside it first. `before` is what the diff was computed from."""
+    if path.exists():
+        backup = path.with_name(f'{path.name}.lanes-bak-{time.strftime("%Y%m%dT%H%M%S")}')
+        shutil.copy2(path, backup)
+        print(f'backup {backup}')
+    elif before:
+        raise L.LanesError(f'{path} vanished while the diff was printed — run again')
+    L.atomic_write(path, after, mode=(path.stat().st_mode & 0o777) if path.exists() else 0o600)
+    print(f'wrote {path}')
+
+
+def cmd_hooks(args):
+    """`lanes hooks install`: merge the lane-signal hook definitions into ONE container home's agent config. Dry run
+    (the printed diff) unless --write; never touches Codex's hook trust (`[hooks.state]` is Codex's own decision)."""
+    if not args or args[0] != 'install':
+        raise L.LanesError(HOOKS_USAGE)
+    opts, rest = {}, list(args[1:])
+    while rest:
+        word = rest.pop(0)
+        if word in ('--agent', '--container', '--home') and rest:
+            opts[word] = rest.pop(0)
+        elif word in ('--dry-run', '--write'):
+            opts[word] = True
+        else:
+            raise L.LanesError(HOOKS_USAGE)
+    agent = opts.get('--agent')
+    if agent not in HOOK_TARGETS or ('--container' in opts) == ('--home' in opts) or \
+            ('--dry-run' in opts and '--write' in opts):
+        raise L.LanesError(HOOKS_USAGE)
+    if '--container' in opts:
+        home = (L.container_info(opts['--container']) or {}).get('home')
+        if not home:
+            raise L.LanesError(f"{opts['--container']}: home volume not found")
+        home = Path(home)
+    else:
+        home = Path(opts['--home'])
+    if not home.is_dir():
+        raise L.LanesError(f'{home}: not a directory')
+    target = home / HOOK_TARGETS[agent][1]
+    before = target.read_text() if target.exists() else ''
+    try:
+        existing = json.loads(before) if before.strip() else {}
+    except ValueError as error:
+        raise L.LanesError(f'{target}: not valid JSON ({error}) — refusing to rewrite it')
+    if not isinstance(existing, dict):
+        raise L.LanesError(f'{target}: not a JSON object — refusing to rewrite it')
+    after = json.dumps(merge_hooks(existing, render_hooks(agent)), indent=2, ensure_ascii=False) + '\n'
+    changes = [(target, before, after)] if show_change(target, before, after) else []
+    if agent == 'codex':
+        config = home / '.codex/config.toml'
+        text = config.read_text() if config.exists() else ''
+        patched = codex_notify(text)
+        if patched == text:
+            print(f'{config}: notify already set; left alone (lane-signal still hears Stop)')
+        elif show_change(config, text, patched):
+            changes.append((config, text, patched))
+        print('Codex asks you to review and trust new hooks before it runs them; lanes never writes that trust.')
+    if not opts.get('--write'):
+        print('dry run: nothing written (add --write to apply)')
+        return 0
+    for path, old, new in changes:
+        write_with_backup(path, old, new)
     return 0
 
 
@@ -441,31 +754,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,36 +798,133 @@ 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}'
 
 
 def all_panes():
-    """Every pane on every LIVE tmux server that the registry references (ps-discovered, read-only).
-    Ephemeral test-harness sockets come and go on their own and are not lanes.
-    Raises when ps or a live server did not ANSWER: a partial list would be saved as a weaker invariant, or
-    compared as panes that are "gone" — on a busy host both are wrong."""
+    """Every pane on every LIVE tmux server that the registry references (found in the containers' cgroups the way
+    statusd finds them, read-only). Ephemeral test-harness sockets come and go on their own and are not lanes.
+    Raises when a container's cgroup could not be read or a live server did not ANSWER: a partial list would be
+    saved as a weaker invariant, or compared as panes that are "gone" — on a busy host both are wrong."""
     sys.path.insert(0, str(L.REPO / 'libexec'))
     import statusd
     unknown = 'the panes are UNKNOWN, not gone — nothing saved or compared; try again'
-    live = statusd.live_tmux_sockets()
-    if live is None:
-        raise L.LanesError(f'ps did not answer: {unknown}')
     containers = L.read_json(L.STATE / 'containers.json') or {}
+    live = statusd.live_tmux_sockets(containers)
+    if live is None:
+        raise L.LanesError(f'the live tmux servers could not be read from the container cgroups: {unknown}')
     referenced = {}
     for workspace in L.load_registry()['workspaces']:
         for lane in workspace['lanes']:
@@ -566,32 +968,6 @@ def cmd_invariant(args):
     return 1 if (gone or changed_pid or (resized and sizes_matter)) else 0
 
 
-def cmd_verify_legacy(_args):
-    registry = L.load_registry()
-    containers = registry['containers']
-    bad = 0
-    for workspace in registry['workspaces']:
-        info = containers.get(workspace['container']) or {}
-        layout = Path(info.get('home', '')) / '.config/coder-launch/layouts' / f"{workspace['id']}.kdl"
-        try:
-            text = layout.read_text()
-        except OSError:
-            print(f"? {workspace['id']:<18} no deployed legacy layout")
-            continue
-        deployed = {}
-        for match in re.finditer(r'tab name=("(?:[^"\\]|\\.)*")[^\n]*\{\s*pane [^\n]*coder-launch/connect"\s*\{\s*args ("(?:[^"\\]|\\.)*") ("(?:[^"\\]|\\.)*")', text):
-            name, socket, session = (json.loads(g) for g in match.groups())
-            deployed[name] = (socket, session)
-        ours = {lane['name']: (lane['tmux']['socket'], lane['tmux']['session'])
-                for lane in workspace['lanes'] if lane['holder'] == 'tmux'}
-        diffs = [n for n in sorted(set(ours) | set(deployed)) if ours.get(n) != deployed.get(n)]
-        bad += len(diffs)
-        print(f"{'✓' if not diffs else '✗'} {workspace['id']:<18} registry={len(ours):>3} deployed={len(deployed):>3}")
-        for name in diffs:
-            print(f'    {name!r}: registry={ours.get(name)} deployed={deployed.get(name)}')
-    return 1 if bad else 0
-
-
 def active_workspace(registry, device):
     """The board the device's view is showing right now (its active zellij tab)."""
     out = zellij(['-s', device, 'action', 'list-tabs', '-j'], 15)[1]
@@ -834,7 +1210,15 @@ def cmd_gc(_args):
             except OSError as error:
                 print(f'skip {log}: {error}')
     status = L.read_json(L.STATE / 'status.json') or {}
-    known = set(status.get('lanes', {}))
+    # Every id statusd publishes. statusd already mirrors each id it lists under `unregistered` (tmux ghosts, legacy
+    # shells) and `zmx` into `lanes` (statusd.observe/build_payload; pinned by test_statusd
+    # Cycle.test_every_published_row_id_is_also_a_lanes_key), so `lanes` alone covers them today. The union is
+    # defensive: the sweep does not rest on that invariant if the payload is ever decoupled. The mtime is no
+    # liveness signal — make_entry rewrites an unregistered session's file only when it changes (DEF-1456).
+    known = set(status.get('lanes') or {})
+    for key in ('unregistered', 'zmx'):
+        for entries in (status.get(key) or {}).values():
+            known.update(e['id'] for e in entries or () if isinstance(e, dict) and e.get('id'))
     for stale in (L.STATE / 'resolve.dynamic').glob('*'):
         if stale.name not in known and time.time() - stale.stat().st_mtime > 3600:
             stale.unlink()
@@ -891,12 +1275,142 @@ def cmd_sockets(args):
     return 1 if guard.sockets(env, guard.container_names(env), repair=verb == 'repair') else 0
 
 
+def cmd_economy(args):
+    if '--once' not in args:
+        raise L.LanesError('usage: lanes economy --once [--dry-run] [--status-file F --sessions-file F] '
+                           '(the recurring poller is lanes-economy.service, opt-in)')
+    return libexec_module('economy_poll').main(args)
+
+
 def cmd_pressure(_args):
     health = L.compute_health()
     print('\n'.join(pressure_lines(health, L.read_json(L.STATE / 'containers.json') or {})))
     return 0 if health.get('level') == 'ok' else 1
 
 
+# Past this many lanes on one container's tmux socket `default` the doctor warns: that is the server every plain
+# `tmux` typed in the container talks to, so one stray `tmux kill-server` (or a crash of that one server) ends them all.
+DEFAULT_SOCKET_LANES = 4
+
+
+def recipe_report(registry):
+    """(info lines, warnings) of the registry's tmux lanes for `lanes doctor` (plan Task 18): lanes per create-recipe
+    class (lanes_lib.classify_recipe), how many create with their identity (-e LANE_ID, DEF-1478), lanes bound to a
+    numeric session name, and crowded `default` sockets. Reads registry.json only: no tmux, no container."""
+    counts, identity, total = dict.fromkeys(L.RECIPE_CLASSES, 0), 0, 0
+    broken, numeric, on_default = [], [], {}
+    for workspace in registry.get('workspaces') or []:
+        for lane in workspace.get('lanes') or []:
+            if lane.get('holder') != 'tmux':
+                continue
+            total += 1
+            kind = L.classify_recipe(lane.get('create'))
+            counts[kind] += 1
+            identity += 1 if L.recipe_identity(lane.get('create')) else 0
+            if kind in ('attach-only', 'null', 'retired-path'):
+                broken.append(lane['id'])
+            tmux = lane.get('tmux') or {}
+            if str(tmux.get('session') or '').isdigit():
+                numeric.append(lane['id'])
+            if tmux.get('socket') == 'default':
+                on_default.setdefault(lane.get('container') or '?', []).append(lane['id'])
+
+    def some(ids):
+        return ', '.join(ids[:3]) + (' …' if len(ids) > 3 else '')
+    lines = ['create recipes: ' + ' · '.join(f'{k} {counts[k]}' for k in L.RECIPE_CLASSES) + f' (of {total} tmux lanes)',
+             f'lane identity: {identity} of {total} tmux lanes create with LANE_ID / LANE_WS and the lanes/<ws>/<id> trace '
+             '(lanes cursor-sync --identity / --canonicalize add it)']
+    warnings = []
+    if broken:
+        warnings.append(f'{len(broken)} lanes that `lane open` cannot recreate once they end (attach-only, no recipe, or '
+                        f'the retired coder-launch path): lanes cursor-sync --canonicalize — {some(broken)}')
+    if numeric:
+        warnings.append(f'{len(numeric)} lanes bound to a numeric tmux session name (tmux numbers unnamed sessions '
+                        f'itself, so a recreated one gets another number): {some(numeric)}')
+    for container, ids in sorted(on_default.items()):
+        if len(ids) > DEFAULT_SOCKET_LANES:
+            warnings.append(f'{container}: {len(ids)} lanes on the tmux socket `default` (more than {DEFAULT_SOCKET_LANES}): '
+                            f'every plain `tmux` in the container talks to that one server — {some(ids)}')
+    return lines, warnings
+
+
+def socket_report(containers, live_by_container):
+    """Warnings for `lanes doctor`: tmux socket FILES in a container's /tmp/tmux-<uid> that no running tmux server
+    (from the container's cgroup, `live_by_container()`, called only when some container has socket files) owns.
+    REPORT ONLY: the host never unlinks a container's socket (RUNBOOK NEVER rule); `lane gc --sockets` in the
+    container does, after tmux itself is refused on the file (ECONNREFUSED). A container whose servers cannot be read
+    is said to be not checked, never concluded."""
+    found = {}
+    for name, info in sorted(containers.items()):
+        if not (info or {}).get('pid'):
+            continue
+        directory = PROC / str(info['pid']) / 'root/tmp' / f'tmux-{L.CONTAINER_UID}'
+        try:
+            files = sorted(path.name for path in directory.iterdir() if path.is_socket())
+        except OSError:
+            continue
+        if files:
+            found[name] = files
+    if not found:
+        return []
+    live = live_by_container({name: containers[name] for name in found}) or {}
+    warnings = []
+    for name, files in found.items():
+        servers = live.get(name)
+        if servers is None:
+            warnings.append(f'{name}: {len(files)} tmux socket files; its tmux servers could not be read from its cgroup: '
+                            'not checked')
+            continue
+        orphans = [f for f in files if f not in servers]
+        if orphans:
+            warnings.append(f'{name}: {len(orphans)} tmux socket files with no server found for them ({" ".join(orphans)}) '
+                            '— report only; to remove the ones tmux is refused on, in the container: ~/.lz/bin/lane gc --sockets')
+    return warnings
+
+
+def cmd_device(args):
+    """lanes device list | lanes device forget <name>: the devices/<name>.json files `lanes ensure` (lanes-ensure.timer)
+    recreates a view session from, and `sync`/`upgrade-session` update. Forgetting removes that file only: a running
+    view session is never ended here."""
+    usage = 'usage: lanes device list | lanes device forget <name>'
+    devices = L.STATE / 'devices'
+    if args == ['list']:
+        try:
+            live = live_sessions()
+        except L.LanesError:
+            live = None
+        for meta_file in sorted(devices.glob('*.json')):
+            meta = L.read_json(meta_file) or {}
+            kind = 'phone' if meta.get('mobile') else f"desktop, {int(meta.get('viewports') or 1)} viewports"
+            running = 'unknown (zellij did not answer)' if live is None else (
+                'running' if meta_file.stem in live else 'not running')
+            print(f'{meta_file.stem:<16} {kind:<24} {running}' + (f"  base {meta['base']}" if meta.get('base') else ''))
+        return 0
+    if len(args) != 2 or args[0] != 'forget':
+        raise L.LanesError(usage)
+    device = device_name(args[1])
+    meta_file = devices / f'{device}.json'
+    if not meta_file.exists():
+        raise L.LanesError(f'no device {device!r} is known (lanes device list)')
+    meta = L.read_json(meta_file) or {}
+    try:
+        live = device in live_sessions()
+    except L.LanesError:
+        live = None
+    meta_file.unlink()
+    kind = 'phone' if meta.get('mobile') else f"desktop, {int(meta.get('viewports') or 1)} viewports"
+    print(f'forgot {device} ({kind}): `lanes ensure` (lanes-ensure.timer) no longer recreates its view session, and '
+          '`lanes sync` / `upgrade-session` no longer update it')
+    if live:
+        print(f'its view session {device} is still running and was left alone; once it ends, nothing brings it back')
+    elif live is None:
+        print(f'zellij did not answer: whether a view session {device} runs now is unknown (nothing was touched)')
+    else:
+        print(f'no view session {device} is running')
+    print(f'`lanes attach {device}` or `lanes prepare {device}` creates it again')
+    return 0
+
+
 def cmd_doctor(_args):
     problems = 0
 
@@ -911,23 +1425,39 @@ 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?
-        generated_at = registry.get('generated_at', 0)
+        # 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
+        # A sync that found nothing to rewrite keeps registry.json and its old `generated_at` (Task 17) and
+        # records itself in registry.synced: the later of the two is when the registry was last known current.
+        generated_at = max(registry.get('generated_at', 0), L.registry_synced_at())
+        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')}")
+        # Recipes, identity, session names, crowded `default` sockets, orphan socket files: warnings, never a ✗
+        # (they describe the boards' declarations and the containers' /tmp, which doctor reports and never changes).
+        lines, warnings = recipe_report(registry)
+        for line in lines:
+            print(f'  {line}')
+        for warning in warnings + socket_report(containers, SD.live_by_container):
+            print(f'⚠ {warning}')
+    # Plan Task 19 retired the pre-persistence Docker-shell tracker. A record still in its directory is inert (never
+    # observed, never closable from the sidebar): name it, so the operator ends that shell by hand and removes it.
+    legacy = sorted(p.stem for p in (L.STATE / 'legacy-sessions').glob('*.json'))
+    if legacy:
+        print(f'⚠ legacy-sessions/ holds {len(legacy)} record{"s" if len(legacy) != 1 else ""} the retired legacy-shell '
+              f'tracker no longer reads: {", ".join(legacy[:5])}{" …" if len(legacy) > 5 else ""} — end those shells '
+              'in their containers by hand, then delete the records')
     status = L.read_json(L.STATE / 'status.json') or {}
     age = time.time() - status.get('updated_at', 0)
     check(age < 30, 'statusd heartbeat', f'{age:.0f}s old')
@@ -963,10 +1493,15 @@ def cmd_doctor(_args):
     zmx_lanes = sum(len(v) for v in (status.get('zmx') or {}).values())
     installed = [link.name for link in sorted((Path.home() / '.lz').glob('*')) if (link / 'bin/lane').exists()]
     print(f"  lane contract installed in: {', '.join(installed) or 'no container yet'}; zmx-held lanes: {zmx_lanes}")
+    print(f'  preview renderer: {preview_renderer()}')
     try:
         print('  view sessions:', ', '.join(sorted(live_sessions())) or 'none')
     except (OSError, L.LanesError) as error:
         check(False, 'zellij reachable', str(error))
+    stale_pickers = stale_picker_layouts()
+    check(not stale_pickers, 'phone picker panes report their own title (DEF-1450)',
+          'built from a layout that names the picker pane, so the phone shows no counts; upgrade-session does not '
+          're-lay-out a tab — run ' + '; '.join(f'lanes rebuild {d}' for d in stale_pickers))
     print('PRESSURE')
     health = L.compute_health()
     print('\n'.join(pressure_lines(health, L.read_json(L.STATE / 'containers.json') or {})))
@@ -980,7 +1515,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 +1544,263 @@ 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-1475).
+    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
 
 
+# ------------------------------------------------------------------ preview
+# Ctrl-Alt-m (zellij/config.kdl, spec §5.4) opens a floating pane running `lanes preview --focused`: the markdown file
+# the focused lane printed last, rendered by glow (else `less -R`). Read-only: two zellij listings, one guarded tmux
+# capture, file tests through /proc/<init>/root.
+
+PREVIEW_LINES = 300
+
+
+def pinned_binary(name):
+    """SHARE/bin/<name>-<version> as holders.lock pins it (install/host-install.sh installs it there), or None."""
+    for line in (L.REPO / 'holders.lock').read_text().splitlines():
+        fields = line.split()
+        if len(fields) >= 4 and not line.startswith('#') and fields[0] == name:
+            return L.SHARE / 'bin' / f'{name}-{fields[1]}'
+    return None
+
+
+def glow_binary():
+    """The pinned glow when installed, else a glow on the VIEW SERVER's PATH (clean_env, which the Run pane inherits;
+    the installer skips the download only when that same PATH finds one), else None. Never the caller's PATH: a glow
+    in ~/.local/bin or ~/go/bin is invisible to the pane, so doctor and the pane must agree on one lookup."""
+    pinned = pinned_binary('glow')
+    if pinned and os.access(pinned, os.X_OK):
+        return str(pinned)
+    return shutil.which('glow', path=clean_env()['PATH'])
+
+
+def preview_renderer():
+    """What `lanes preview` renders with, as doctor reports it: pinned glow | system glow (<path>) | less -R."""
+    glow = glow_binary()
+    if glow and glow == str(pinned_binary('glow')):
+        return f'pinned glow ({glow})'
+    if glow:
+        return f'system glow ({glow})'
+    return 'less -R (no glow on the view server PATH; ./install.sh --server installs the pinned one)'
+
+
+def focused_view(device):
+    """(view device, workspace, slot) behind the focused pane of `device`'s active tab. The floating preview pane holds
+    the focus while this runs, so the TILED view pane zellij marks focused decides; a focused sidebar (or none
+    marked) means the tab's first viewport. A tab without a board (Host, tools) is said, never guessed."""
+    import shlex
+    listings = []
+    for action in ('list-tabs', 'list-panes'):
+        rc, out, err = zellij(['-s', device, 'action', action, '-j'] + (['-a'] if action == 'list-panes' else []), 10)
+        if rc != 0:
+            raise L.LanesError(f'zellij did not answer {action} for {device}: {err.strip() or "no answer"}')
+        try:
+            listings.append(json.loads(out))
+        except ValueError:
+            raise L.LanesError(f'zellij answered {action} for {device} with something that is not JSON')
+    tabs, panes = listings
+    active = next((t.get('tab_id') for t in tabs if isinstance(t, dict) and t.get('active')), None)
+    view_sh, sidebar = str(L.REPO / 'libexec/view.sh'), str(L.REPO / 'libexec/sidebar')
+    views, boards = [], []
+    for pane in panes:
+        if not isinstance(pane, dict) or pane.get('is_plugin') or pane.get('is_floating') or pane.get('tab_id') != active:
+            continue
+        try:
+            args = shlex.split(pane.get('terminal_command') or pane.get('pane_command') or '')
+        except ValueError:
+            continue
+        for script in (view_sh, sidebar):
+            tail = args[args.index(script) + 1:] if script in args else []
+            if len(tail) < 2 or not all(L.IDENT.match(part) for part in tail[:2]):
+                continue
+            if script == view_sh:
+                slot = tail[2] if len(tail) > 2 and tail[2] in SLOTS else 'main'
+                views.append((not pane.get('is_focused'), SLOTS.index(slot), (tail[0], tail[1], slot)))
+            else:
+                boards.append((tail[0], tail[1], 'main'))
+    if views:
+        return min(views)[2]
+    if boards:
+        return boards[0]
+    raise L.LanesError('the focused tab shows no board (Host or a tool tab): nothing to preview')
+
+
+def lane_shown(view_device, workspace, slot):
+    """The lane id a viewport shows: its target file, else (first viewport only) the board's default lane."""
+    for path in (L.STATE / 'views' / view_device / f'{workspace}.{slot}.target',
+                 L.STATE / 'defaults' / workspace if slot == 'main' else None):
+        try:
+            lane_id = path.read_text().split('\n')[0].strip() if path else ''
+        except OSError:
+            lane_id = ''
+        if lane_id:
+            return lane_id
+    raise L.LanesError(f'no lane is shown in {workspace} ({slot})')
+
+
+def lane_scrollback(info, lane):
+    """The last PREVIEW_LINES lines of a tmux lane, wrapped lines joined — through lanes_lib.tmux_probe (-N, scrubbed
+    env, the socket under /proc/<init>/root) with holders/tmux.sh's guards: the `=<session>:` target, and the session
+    that ANSWERS must be the one asked for (an object-id name like `$0` resolves another session, DEF-968)."""
+    socket, session = lane['tmux']['socket'], lane['tmux']['session']
+    target = f'={session}:'
+    outcome, answer = L.tmux_probe(info, socket, ['display-message', '-p', '-t', target, '#{session_name}'])
+    if outcome != 'ok' or answer.rstrip('\n') != session:
+        raise L.LanesError(f"lane {lane['name']} did not answer ({outcome})")
+    outcome, text = L.tmux_probe(info, socket, ['capture-pane', '-p', '-J', '-S', f'-{PREVIEW_LINES}', '-t', target])
+    if outcome != 'ok':
+        raise L.LanesError(f"lane {lane['name']}: no scrollback ({outcome})")
+    return text
+
+
+def preview_argv(path, device):
+    """(argv, env) that shows `path`: glow in the device's theme (`STATE/clients/<device>.theme`, written by the
+    sidebar from the OSC 11 answer; dark when absent), else `less -R`, else None (print it). glow 3.0.0 ignores
+    GLAMOUR_STYLE (measured 2026-10-04: dark and light rendered identical bytes), so `-s` carries the style too."""
+    try:
+        style = (L.STATE / 'clients' / f'{device}.theme').read_text().strip()
+    except OSError:
+        style = ''
+    style = style if style in ('dark', 'light') else 'dark'
+    env = dict(os.environ, GLAMOUR_STYLE=style)
+    glow = glow_binary()
+    if glow:
+        return [glow, '-s', style, '-p', path], env
+    less = shutil.which('less')
+    return ([less, '-R', path] if less else None), env
+
+
+def preview_choose(paths):
+    """One path: it. Several: a numbered menu, newest first; Enter = 1, q (or anything unusable) = None."""
+    if len(paths) == 1:
+        return paths[0]
+    newest = list(reversed(paths))
+    print('Markdown files this lane printed (newest first):')
+    for number, path in enumerate(newest, 1):
+        print(f'  {number}  {path}')
+    print('Number [1], q to close: ', end='', flush=True)
+    answer = sys.stdin.readline().strip()
+    if not answer:
+        return newest[0]
+    return newest[int(answer) - 1] if answer.isdigit() and 1 <= int(answer) <= len(newest) else None
+
+
+def preview_hold():
+    """close_on_exit closes the pane the moment this exits: let a message be read first (only on a terminal)."""
+    if sys.stdin.isatty():
+        print('\nPress Enter to close.', end='', flush=True)
+        sys.stdin.readline()
+
+
+def cmd_preview(args):
+    if '--focused' not in args:
+        print('usage: lanes preview --focused [--device D]   (the Ctrl-Alt-m floating pane runs this)')
+        return 2
+    device = args[args.index('--device') + 1] if '--device' in args else os.environ.get('ZELLIJ_SESSION_NAME', '')
+    try:
+        device = device_name(device)
+        view_device, workspace, slot = focused_view(device)
+        registry = L.load_registry()
+        board, lane = L.find_lane(registry, lane_shown(view_device, workspace, slot))
+        if lane.get('holder') != 'tmux':
+            raise L.LanesError(f"{lane['name']} is a {lane.get('holder')} lane: preview reads tmux lanes only")
+        info = (L.read_json(L.STATE / 'containers.json') or {}).get(lane['container']) or {}
+        text = lane_scrollback(info, lane)
+        status = ((L.read_json(L.STATE / 'status.json') or {}).get('lanes') or {}).get(lane['id']) or {}
+        cwd = status.get('cwd') or lane.get('folder') or board.get('cwd') or ''
+        root = PROC / str(info.get('pid') or 0) / 'root'
+        found = [p for p in L.markdown_candidates(text, cwd) if info.get('pid') and (root / p.lstrip('/')).is_file()]
+    except L.LanesError as error:
+        print(f'lanes preview: {error}')
+        preview_hold()
+        return 1
+    if not found:
+        print(f"No markdown file named in the last {PREVIEW_LINES} lines of {lane['name']} ({cwd or 'no cwd'}).")
+        preview_hold()
+        return 0
+    chosen = preview_choose(found)
+    if not chosen:
+        return 0
+    host = str(root / chosen.lstrip('/'))
+    argv, env = preview_argv(host, view_device)
+    if argv:
+        os.execve(argv[0], argv, env)
+        return 0   # only reached when execve is a test double
+    sys.stdout.write(Path(host).read_text(errors='replace'))
+    preview_hold()
+    return 0
+
+
+# ------------------------------------------------------------------ next / prev
+# Ctrl-Alt-Down / Ctrl-Alt-Up (zellij/config.kdl, plan Task 19) run `lanes next|prev --focused` in a floating pane that
+# closes when it exits. They used to walk the focus left three times and type J/K into whatever pane that reached
+# (the sidebar, or — on a tab without one — the lane itself). Now nothing is typed and no focus moves: the viewport
+# zellij marks focused is pointed at the neighbouring lane exactly as the sidebar's open_lane points it
+# (lanes_lib.show_lane), and a lane with an agent is marked seen on the device as open_lane marks it.
+
+
+def step_lane(args, step):
+    verb = 'next' if step > 0 else 'prev'
+    if '--focused' not in args:
+        print(f'usage: lanes {verb} --focused [--device D]   (Ctrl-Alt-{"Down" if step > 0 else "Up"} runs this)')
+        return 2
+    device = args[args.index('--device') + 1] if '--device' in args else os.environ.get('ZELLIJ_SESSION_NAME', '')
+    try:
+        device = device_name(device)
+        view_device, workspace, slot = focused_view(device)
+        registry = L.load_registry()
+        board = next((w for w in registry['workspaces'] if w['id'] == workspace), None)
+        ids = [lane['id'] for lane in (board or {}).get('lanes', [])]
+        if not ids:
+            raise L.LanesError(f'{workspace} has no lanes to step through')
+        try:
+            shown = lane_shown(view_device, workspace, slot)
+        except L.LanesError:
+            shown = ''
+        # A lane outside the list (an unregistered session, nothing shown yet): next starts at the first, prev at
+        # the last.
+        index = ids.index(shown) if shown in ids else (-1 if step > 0 else len(ids))
+        lane_id = ids[(index + step) % len(ids)]
+    except L.LanesError as error:
+        print(f'lanes {verb}: {error}')
+        return 1
+    status = (L.read_json(L.STATE / 'status.json') or {}).get('lanes') or {}
+    agent = (status.get(lane_id) or {}).get('agent') if isinstance(status, dict) else None
+    if isinstance(agent, dict) and agent:
+        L.record_seen(L.STATE / 'clients' / f'{view_device}.seen.json', lane_id, agent.get('since'), set(status))
+    if not L.show_lane(str(L.STATE / 'views' / view_device), workspace, slot, lane_id):
+        print('view not running yet')
+    return 0
+
+
+def cmd_next(args):
+    return step_lane(args, +1)
+
+
+def cmd_prev(args):
+    return step_lane(args, -1)
+
+
 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,
-            'verify-legacy': cmd_verify_legacy, 'doctor': cmd_doctor, 'pressure': cmd_pressure, 'sockets': cmd_sockets, 'tmp': cmd_tmp,
-            'guard': cmd_guard, 'rename': cmd_rename}
+            'prepare': cmd_prepare, 'web': cmd_web, 'attach': cmd_attach, 'rebuild': cmd_rebuild, 'ensure': cmd_ensure, 'invariant': cmd_invariant,
+            'doctor': cmd_doctor, 'pressure': cmd_pressure, 'sockets': cmd_sockets, 'tmp': cmd_tmp,
+            'guard': cmd_guard, 'rename': cmd_rename, 'register': cmd_register, 'hooks': cmd_hooks, 'economy': cmd_economy,
+            'preview': cmd_preview, 'device': cmd_device, 'next': cmd_next, 'prev': cmd_prev}
 
 if __name__ == '__main__':
     if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS: