@vibelord/lanes 1.0.1 → 1.0.2

package/payload/lanes/bin/lanes

@@ -6,7 +6,9 @@
   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)
+               [--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
@@ -34,15 +36,19 @@
                                  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)
+                                 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
@@ -55,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
@@ -225,11 +256,35 @@ 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={q("Lanes" if picker else workspace["title"])} command={q(command)} {{',
+            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
+        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 ''
@@ -325,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'):
@@ -358,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
@@ -365,6 +460,7 @@ 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
@@ -405,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'
@@ -485,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')
@@ -500,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
 
 
@@ -681,17 +914,17 @@ PANE_FORMAT = '#{session_name}\t#{window_index}.#{pane_index}\t#{pane_pid}\t#{wi
 
 
 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']:
@@ -735,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]
@@ -1003,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()
@@ -1060,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
 
@@ -1084,7 +1429,9 @@ def cmd_doctor(_args):
         # 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)
+        # 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 src, path in SD.registry_source_paths(registry, containers):
@@ -1097,6 +1444,20 @@ def cmd_doctor(_args):
               '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')
@@ -1132,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 {})))
@@ -1179,7 +1545,7 @@ def cmd_rename(args):
     if not lane:
         raise L.LanesError(f'Unknown lane: {lane_id}')
     # 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).
+    # 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)
@@ -1196,10 +1562,245 @@ def cmd_rename(args):
     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, '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, 'register': cmd_register}
+            '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: