@vibelord/lanes 1.0.0 → 1.0.1

package/payload/lanes/libexec/statusd.py

@@ -13,6 +13,7 @@ or positively does not exist.
 """
 import json
 import os
+import subprocess
 import sys
 import time
 from pathlib import Path
@@ -20,6 +21,7 @@ from pathlib import Path
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import lanes_lib as L  # noqa: E402
 import session_actions as A  # noqa: E402
+import agent_state as AS  # noqa: E402
 import legacy_sessions as Legacy  # noqa: E402
 
 INTERVAL = float(os.environ.get('LANES_STATUS_INTERVAL', '3'))
@@ -35,7 +37,12 @@ FIELDS = ['session_name', 'pane_pid', 'pane_dead', 'window_activity', 'pane_curr
           'session_id', 'session_created',
           # Alignment contract A4a: the group a session is attached onto (a Throttle Studio browser view is a
           # grouped session), and which pane of which window represents the session's state.
-          'session_group', 'pane_active', 'window_active']
+          'session_group', 'pane_active', 'window_active',
+          # Task 5 (`agent{}`): the window bell, the ids a Claude session file names its pane by
+          # (`<session>:@<win>.%<pane>`), and the pane title Codex writes its status into. APPENDED, so every
+          # column above keeps its index; the title is the one free-text column and comes LAST, so a tab inside it
+          # stays in the title (the row is split at most len(FIELDS) - 1 times) instead of shifting the ids.
+          'window_bell_flag', 'window_id', 'pane_id', 'pane_title']
 FORMAT = '\t'.join('#{' + f + '}' for f in FIELDS)
 VIEW_PREFIX = 'view-'   # a Throttle Studio browser attach: a grouped session named view-<studio>-<ch>
 
@@ -196,10 +203,11 @@ def keep(previous, lane_id, outcome):
     return dict(old, state=state, stale=True, observed=outcome, stale_since=since)
 
 
-def lane_entry(pane, now, activity=None, viewing=()):
+def lane_entry(pane, now, activity=None, viewing=(), agent=None):
     """One live session's published row. `activity` is the NEWEST `window_activity` across the session's panes
     (see `newest_activity`) and `viewing` the rows of the sessions that VIEW it (see `split_viewers`); both
-    default to "this pane alone", which is what a caller with a single row has."""
+    default to "this pane alone", which is what a caller with a single row has. `agent` is `agent_state.merge`'s
+    verdict for the session's pane: published as the additive `agent` key, absent when no signal names an agent."""
     if activity is None:
         try:
             activity = int(pane['window_activity'])
@@ -224,9 +232,53 @@ def lane_entry(pane, now, activity=None, viewing=()):
              'tty': pane['pane_tty']}
     if viewing:   # skipped when 0, so a lane nobody views publishes byte-identically to before A4a
         entry['viewers'] = len(viewing)
+    if agent:     # absent = no agent: a plain shell's row is byte-identical to before Task 5
+        entry['agent'] = agent
     return entry
 
 
+def agent_signals(containers, sessions_by_server):
+    """The per-container inputs `agent_state.merge` needs, read ONCE per container per cycle through the
+    container's root as the host sees it (`/proc/<init pid>/root`), so liveness is judged in the container's pid
+    namespace and nothing is spawned. -> {container: claude_by_pane}.
+
+    Also sets `pane_has_child` on the session rows that need it, in place: only a pane whose title Codex wrote
+    (`parse_codex_title`) over a bare-shell foreground can be a harness that ended into its shell, and only the
+    child read (`child_liveness`) tells that apart from a live harness launched under `bash -c` or a wrapper. A pane
+    a live Claude session file already claims is not probed (the file outranks the title). The key is set only for
+    a known answer: unknown liveness leaves it absent, and an absent key never demotes a title (DEF-1420). A
+    container whose files cannot be read costs only its own agents, never a lane its `state`."""
+    claude = {}
+    for container in sorted({container for container, _socket in sessions_by_server}):
+        info = containers.get(container) or {}
+        if not info.get('pid'):
+            continue
+        root = Path(L.proc_root()) / str(info['pid']) / 'root'
+        try:
+            claude[container] = AS.claude_sessions(root / L.CONTAINER_HOME.lstrip('/') / '.claude' / 'sessions',
+                                                   root / 'proc')
+        except Exception as error:
+            log(f'agents {container}', error)
+            claude[container] = {}
+        probe = [pane for (owner, _socket), sessions in sessions_by_server.items() if owner == container
+                 for pane in sessions.values()
+                 if str(pane.get('pane_pid') or '').isdigit() and AS.parse_codex_title(pane.get('pane_title'))
+                 and AS._shell_foreground(pane)
+                 and f"{pane.get('session_name')}:{pane.get('window_id')}.{pane.get('pane_id')}" not in claude[container]]
+        if not probe:
+            continue
+        try:
+            live = AS.child_liveness(root / 'proc', [pane['pane_pid'] for pane in probe])
+        except Exception as error:
+            log(f'liveness {container}', error)
+            continue
+        for pane in probe:
+            known = live.get(int(pane['pane_pid']))
+            if known is not None:
+                pane['pane_has_child'] = known
+    return claude
+
+
 def probe_server(info, socket, live):
     if not info.get('pid'):
         # Only a docker inspect that ANSWERED "pid 0" says the container is down. No record at all, or one that
@@ -301,7 +353,8 @@ def observe(registry, containers, live, previous=None):
     # servers and servers with no registered lane. Never start a server to ask whether it exists.
     for key in discovered_sockets(containers, live):
         wanted.setdefault(key, [])
-    for (container, socket), members in wanted.items():
+    probed = {}
+    for container, socket in wanted:
         info = containers.get(container) or {}
         rows_by_session = {}
         # One server (or one odd row) must not cost the other servers their cycle: whatever goes wrong in here
@@ -309,15 +362,24 @@ def observe(registry, containers, live, previous=None):
         try:
             outcome, text = probe_server(info, socket, live)
             for row in text.splitlines() if outcome == 'ok' else []:
-                values = dict(zip(FIELDS, row.split('\t')))
+                values = dict(zip(FIELDS, row.split('\t', len(FIELDS) - 1)))
                 rows_by_session.setdefault(values['session_name'], []).append(values)
         except Exception as error:
             log(f'observe {container}/{socket}', error)
             outcome, rows_by_session = 'error', {}
         # A4a: every session is read through its ACTIVE pane and its NEWEST window activity, the same two
         # readings the Host makes, so `dead`/`active` cannot mean one thing per surface on a multi-window lane.
-        sessions = {name: session_row(rows) for name, rows in rows_by_session.items()}
-        activities = {name: newest_activity(rows) for name, rows in rows_by_session.items()}
+        probed[(container, socket)] = (outcome, {name: session_row(rows) for name, rows in rows_by_session.items()},
+                                       {name: newest_activity(rows) for name, rows in rows_by_session.items()})
+    # Task 5: the agent signals of every container, read once per cycle over all of its servers' sessions.
+    try:
+        claude = agent_signals(containers, {key: sessions for key, (_o, sessions, _a) in probed.items()})
+    except Exception as error:
+        log('agents', error)
+        claude = {}
+    for (container, socket), members in wanted.items():
+        info = containers.get(container) or {}
+        outcome, sessions, activities = probed[(container, socket)]
         # ... and an UNDECLARED session grouped onto another live session is that session's viewer, not a lane.
         registered = {lane['tmux']['session'] for lane in members}
         own_sessions, viewers = split_viewers(sessions, registered)
@@ -330,7 +392,8 @@ def observe(registry, containers, live, previous=None):
             # The sessions nobody registered stay visible as well while their server does not answer.
             for workspace_id, entries in (previous.get('unregistered') or {}).items():
                 for entry in entries:
-                    if entry.get('container') == container and (entry.get('tmux') or {}).get('socket') == socket:
+                    if (entry.get('container') == container and (entry.get('tmux') or {}).get('socket') == socket
+                            and not any(A.session_key(entry) == A.session_key(lane) for lane in members)):
                         unregistered.setdefault(workspace_id, []).append(entry)
                         lanes[entry['id']] = keep(previous, entry['id'], outcome)
         if own_sessions:
@@ -380,7 +443,8 @@ def observe(registry, containers, live, previous=None):
                     # RUNBOOK nor the design doc may promise that it does.
                     if not L.TMUX_SESSION.match(name):
                         entry['note'] = 'session name outside the lane declaration grammar'
-                    found = lane_entry(pane, now, activities.get(name), viewers.get(name, []))
+                    found = lane_entry(pane, now, activities.get(name), viewers.get(name, []),
+                                       AS.merge(pane, claude.get(container, {}), None))
                 except Exception as error:
                     log(f'observe {container}/{socket}/{name}', error)
                     continue
@@ -398,7 +462,9 @@ def observe(registry, containers, live, previous=None):
                 lanes[lane['id']] = {'state': 'absent' if info.get('running') else 'missing'}
             else:
                 try:
-                    lanes[lane['id']] = lane_entry(pane, now, activities.get(session), viewers.get(session, []))
+                    # The hook sidecar (Task 8) is the third argument; until it lands nothing is passed.
+                    lanes[lane['id']] = lane_entry(pane, now, activities.get(session), viewers.get(session, []),
+                                                   AS.merge(pane, claude.get(container, {}), None))
                 except Exception as error:   # a torn row: the session is there, its details are not readable
                     log(f"observe {lane['id']}", error)
                     lanes[lane['id']] = keep(previous, lane['id'], 'error')
@@ -591,7 +657,7 @@ def update_containers(ctx, registry, level):
     5-minute safety net on a host that is not busy — and at most every CONTAINER_RETRY seconds. NEVER because a
     probe failed: `docker inspect` (2 spawns, 20 s timeouts) every 3 s is a load generator on a host that is
     already too slow to answer it."""
-    names = {lane['container'] for w in registry['workspaces'] for lane in w['lanes'] + w['extras']}
+    names = {lane['container'] for w in registry['workspaces'] for lane in w['lanes'] + w['extras'] if lane.get('container')}
     known = ctx['containers']
     age = time.time() - ctx['containers_at']
     unsettled = set(known) != names or any(not pid_alive(c.get('pid')) for c in known.values())
@@ -713,42 +779,69 @@ def pause(level, elapsed):
     return max(0.5, INTERVAL * SLOWDOWN.get(level, 1) - elapsed)
 
 
-def _registry_sources(registry):
-    """All terminals.json paths referenced by the current registry (unique, extant)."""
-    seen = set()
+def registry_source_paths(registry, containers):
+    """(container path, HOST path) for every terminals.json the registry references. The daemon runs on the
+    host: a lane's `source` is spelled as the container sees it and only exists under the container's home
+    volume (`L.host_path`). A container with no record is skipped — nobody can stat its files anyway.
+
+    Deduplicated by the HOST path, never by `source` alone: the same spelling in two containers (one repository
+    cloned in two workspace boxes) is two distinct files, and each must be stat'ed on its own."""
+    seen, out = set(), []
     for w in (registry or {}).get('workspaces', []):
         for lane in w.get('lanes', []):
             src = lane.get('source')
-            if src and src not in seen:
-                seen.add(src)
-                yield src
+            if not src:
+                continue
+            info = (containers or {}).get(lane.get('container') or '') or {}
+            try:
+                path = L.host_path(info, src)
+            except L.LanesError:
+                continue
+            if path in seen:
+                continue
+            seen.add(path)
+            out.append((src, path))
+    return out
+
+
+def hot_sync(ctx, source_mtimes):
+    """One hot-reload check: start ONE `lanes sync` when a referenced terminals.json changed since the last
+    check (read through the host volume). Returns True when a sync was started. The new mtime is recorded
+    once the sync is started, so one edit costs one sync — not one every rate-limit window forever. Keyed by the
+    host path: a `source` spelling is shared by every container that clones the same repository."""
+    for _src, path in registry_source_paths(ctx['registry'], ctx.get('containers') or {}):
+        key = str(path)
+        try:
+            mtime = path.stat().st_mtime_ns
+        except OSError:
+            continue
+        if key in source_mtimes and mtime != source_mtimes[key]:
+            try:
+                proc = subprocess.Popen([str(L.REPO / 'bin' / 'lanes'), 'sync'],
+                                        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            except Exception as sync_err:
+                log('hot-sync', sync_err)
+                return False
+            ctx.setdefault('children', []).append(proc)
+            source_mtimes[key] = mtime
+            return True
+        source_mtimes[key] = mtime
+    return False
 
 
 def main():
     ctx = new_context()
     last_triggered_sync = 0.0
-    source_mtimes = {}   # path -> mtime_ns at last check
+    source_mtimes = {}   # host path of a terminals.json -> its mtime_ns at last check
     while True:
         started = time.time()
         level, _payload = cycle(ctx)
         # Hot-reload: check if any terminals.json changed since we last synced.
         # Rate-limited to at most one triggered sync per 10 s to avoid thrashing.
         if time.time() - last_triggered_sync > 10 and ctx['registry']:
-            for src in _registry_sources(ctx['registry']):
-                try:
-                    mtime = os.stat(src).st_mtime_ns
-                except OSError:
-                    continue
-                if src in source_mtimes and mtime != source_mtimes[src]:
-                    try:
-                        import subprocess as _sp
-                        lanes_bin = str(L.REPO / 'bin' / 'lanes')
-                        _sp.Popen([lanes_bin, 'sync'], stdout=_sp.DEVNULL, stderr=_sp.DEVNULL)
-                        last_triggered_sync = time.time()
-                    except Exception as sync_err:
-                        log('hot-sync', sync_err)
-                    break
-                source_mtimes[src] = mtime
+            if hot_sync(ctx, source_mtimes):
+                last_triggered_sync = time.time()
+        ctx['children'] = [p for p in ctx.get('children', []) if p.poll() is None]   # reap finished syncs
         time.sleep(pause(level, time.time() - started))
 
 

package/payload/lanes/libexec/tokens.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""The Lanes design tokens: ONE table, rendered four ways. The sidebar imports `sgr_table`; `--kdl`, `--css`, `--sh`
+and `--md` write the Zellij theme, the phone CSS, the viewer's shell variables and the docs table between markers;
+`--check` fails when any committed block differs. Spec: docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md.
+No third-party code; importable with no side effects."""
+import difflib
+import os
+import sys
+from pathlib import Path
+
+ROLES = ('surface', 'surface-raised', 'line', 'accent-wash', 'accent-line', 'press', 'chip',
+         'ink', 'ink-dim', 'ink-faint', 'accent', 'on-accent', 'on-accent-urgent',
+         'tone-urgent', 'tone-attention', 'tone-working', 'tone-done', 'scrim', 'shadow')
+TOKENS = {
+    'dark': {'surface': '#101318', 'surface-raised': '#191e25', 'line': '#2c333d', 'accent-wash': '#1a2721',
+             'accent-line': '#4b6955', 'press': '#26332c', 'chip': '#ffffff0f', 'ink': '#edf1f5', 'ink-dim': '#9ca7b5',
+             'ink-faint': '#6b7683', 'accent': '#b4e3bf', 'on-accent': '#101318', 'on-accent-urgent': '#7a1a12',
+             'tone-urgent': '#f28b7d', 'tone-attention': '#e5b84a', 'tone-working': '#7fb3f2', 'tone-done': '#6fd39a',
+             'scrim': '#000000a6', 'shadow': '0 -16px 80px #0007'},
+    'light': {'surface': '#f3f5f2', 'surface-raised': '#ffffff', 'line': '#d5ded6', 'accent-wash': '#e5f0e6',
+              'accent-line': '#acc9b4', 'press': '#d8e9db', 'chip': '#edf3ec', 'ink': '#17241b', 'ink-dim': '#56616d',
+              'ink-faint': '#7f8a96', 'accent': '#2f6b45', 'on-accent': '#ffffff', 'on-accent-urgent': '#ffd3cc',
+              'tone-urgent': '#b7322a', 'tone-attention': '#8a5a00', 'tone-working': '#2456a8', 'tone-done': '#1b7142',
+              'scrim': '#1a222b80', 'shadow': '0 -16px 80px #0003'},
+}
+# 16-colour fallback: the user's own palette resolves these. Selection is achromatic (bold) there, dim is bright-black.
+ANSI16 = {'ink': '39', 'ink-dim': '90', 'ink-faint': '90', 'accent': '1;39',
+          'tone-urgent': '31', 'tone-attention': '33', 'tone-working': '34', 'tone-done': '32'}
+# Lane-identity palette for the two places that DEFINE a palette: Zellij's `web_client { theme {} }` (the phone's
+# xterm.js; dark only, see _web_client) and the optional Ghostty file. A Zellij theme's legacy `black…white` keys are
+# NOT one of them (DEF-1413). The TUI itself keeps 38;5;N. Slots 1-4 are the four tones. Every slot >= 4.5:1.
+PALETTE16 = {
+    'dark': ['#7d8896', '#f28b7d', '#6fd39a', '#e5b84a', '#7fb3f2', '#c9a6ff', '#6fd6d0', '#9ca7b5',
+             '#8a95a3', '#ff9d96', '#8fe0a3', '#f7cf7f', '#a5cbff', '#dcc6ff', '#9ae6e0', '#edf1f5'],
+    'light': ['#3b4a42', '#b7322a', '#1b7142', '#8a5a00', '#2456a8', '#7a3fb8', '#0f7b7b', '#56616d',
+              '#5f6d66', '#c2332a', '#1b7a38', '#8f5a00', '#2860c4', '#8a4dc8', '#0f7272', '#17241b'],
+}
+# key -> (unicode, ascii twin, tone). Position disambiguates: agent glyphs in column 2, stream glyphs in column 33.
+AGENT_GLYPHS = {'needs_approval': ('◆', '!', 'tone-urgent'), 'needs_input': ('◇', '?', 'tone-attention'),
+                'working': ('▸', '>', 'tone-working'), 'done': ('✓', 'v', 'tone-done'),
+                'errored': ('✗', 'X', 'tone-urgent'), 'shell': ('_', '_', 'ink-dim'), 'idle': ('·', '.', 'ink-dim')}
+GLYPHS = {'active': ('●', '*', 'tone-done'), 'quiet': ('○', 'o', 'ink-dim'), 'missing': ('✗', 'x', 'tone-urgent'),
+          'absent': ('–', '-', 'ink-dim'), 'dead': ('!', '!', 'tone-urgent'), 'helper': ('·', '.', 'ink-dim'),
+          'unknown': ('?', '?', 'ink-dim')}
+MARKS = {'cursor': ('▌', '|', 'accent'), 'viewing': ('›', '=', 'accent'), 'viewport-b': ('²', '2', 'accent'),
+         'viewport-c': ('³', '3', 'accent'), 'viewer': ('·', '.', 'ink-dim'), 'truncation': ('…', '~', 'ink'),
+         'close': ('×', 'x', 'tone-urgent'), 'new': ('+', '+', 'tone-done'), 'rule': ('─', '-', 'ink-faint'),
+         'more': ('⋮', ':', 'ink-dim'), 'warning': ('⚠', '!', 'tone-attention'), 'upload': ('↑', '^', 'ink-dim'),
+         'armed': ('↓', 'v', 'tone-done'), 'enter': ('⏎', 'Enter', 'ink-dim'), 'caret': ('█', '_', 'tone-working'),
+         'stale': ('?', '?', 'ink-dim'), 'lead': ('›', '>', 'ink'),
+         # Tone-less punctuation (spec §3 completeness rule): every ` · ` and every quote the sidebar draws is a lookup, so
+         # LANES_GLYPHS=ascii yields a seven-bit frame. `sep` shares `-` with `rule` on purpose: neither carries state.
+         'sep': ('·', '-', 'ink-dim'), 'quote-open': ('‘', "'", 'ink'), 'quote-close': ('’', "'", 'ink'),
+         'ok': ('✓', 'OK', 'tone-done'), 'fail': ('✗', 'X', 'tone-urgent')}
+ECONOMY_TAIL = {'starving': ('⚠', '!', 'tone-attention'), 'downgraded': ('↓', 'v', 'tone-attention'), 'paid': ('$', '$', 'ink-dim')}
+MOBILE_AGENT_LABELS = {'needs_approval': 'Needs approval', 'needs_input': 'Needs you', 'working': 'Working',
+                       'done': 'Done', 'errored': 'Error', 'shell': 'Shell', 'idle': 'Idle'}
+PAINTED = tuple(ANSI16)   # the roles the TUI ever emits
+
+
+def luminance(hexval):
+    r, g, b = (int(hexval[i:i + 2], 16) / 255 for i in (1, 3, 5))
+    lin = [c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4 for c in (r, g, b)]
+    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+
+
+def contrast(fg, bg):
+    hi, lo = sorted((luminance(fg), luminance(bg)), reverse=True)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def rgb(hexval):
+    return tuple(int(hexval[i:i + 2], 16) for i in (1, 3, 5))
+
+
+def sgr_table(mode, variant):
+    """Complete escape per painted role. `mode` truecolor|16|none; `variant` dark|light. Resolved ONCE per process."""
+    table = {'bold': '\033[1m', 'reset': '\033[0m'}
+    dim16 = '\033[2m' if os.environ.get('LANES_DIM') == '2' else '\033[90m'
+    for role in PAINTED:
+        if mode == 'none':
+            table[role] = '\033[1m' if role == 'accent' else ''
+        elif mode == '16':
+            table[role] = dim16 if role in ('ink-dim', 'ink-faint') else f'\033[{ANSI16[role]}m'
+        else:
+            table[role] = ('\033[1m' if role == 'accent' else '') + '\033[38;2;%d;%d;%dm' % rgb(TOKENS[variant][role])
+    return table
+
+
+def glyph_set(mode):
+    """mode unicode|ascii|emoji -> {table name: {key: glyph}}; emoji differs from unicode only in the icon column."""
+    index = 1 if mode == 'ascii' else 0
+    return {name: {k: v[index] for k, v in table.items()}
+            for name, table in (('agent', AGENT_GLYPHS), ('stream', GLYPHS), ('marks', MARKS), ('economy', ECONOMY_TAIL))}
+
+
+def tone_of(table, key):
+    return table[key][2]
+
+
+# ------------------------------------------------------------------ renderers
+COMPONENTS = ('text_unselected', 'text_selected', 'ribbon_selected', 'ribbon_unselected', 'table_title', 'table_cell_selected',
+              'table_cell_unselected', 'list_selected', 'list_unselected', 'frame_selected', 'frame_highlight',
+              'exit_code_success', 'exit_code_error')
+
+
+def _component(t, base, background, emphasis):
+    e = emphasis
+    return f'base "{t[base]}"; background "{t[background]}"; emphasis_0 "{t[e[0]]}"; emphasis_1 "{t[e[1]]}"; emphasis_2 "{t[e[2]]}"; emphasis_3 "{t[e[3]]}";'
+
+
+def _theme(name, variant):
+    t, p = TOKENS[variant], PALETTE16[variant]
+    text = ('tone-attention', 'tone-done', 'accent', 'tone-working')
+    comps = {
+        'text_unselected': ('ink', 'surface', text), 'text_selected': ('ink', 'accent-wash', text),
+        'ribbon_selected': ('on-accent', 'accent', ('on-accent-urgent', 'on-accent', 'on-accent', 'on-accent')),
+        'ribbon_unselected': ('ink-dim', 'surface-raised', ('tone-urgent', 'ink', 'tone-attention', 'tone-working')),
+        'table_title': ('accent', 'surface', text), 'table_cell_selected': ('ink', 'accent-wash', text),
+        'table_cell_unselected': ('ink', 'surface', text), 'list_selected': ('ink', 'accent-wash', text),
+        'list_unselected': ('ink', 'surface', text),
+        'frame_selected': ('accent', 'surface', ('tone-attention', 'tone-done', 'tone-working', 'tone-urgent')),
+        'frame_highlight': ('tone-attention', 'surface', ('tone-urgent', 'tone-done', 'accent', 'tone-working')),
+        'exit_code_success': ('tone-done', 'surface', ('tone-done',) * 4),
+        'exit_code_error': ('tone-urgent', 'surface', ('tone-urgent',) * 4),
+    }
+    lines = [f'    {name} {{']
+    for comp in COMPONENTS:
+        base, background, emphasis = comps[comp]
+        lines.append(f'        {comp} {{ {_component(t, base, background, emphasis)} }}')
+    players = [t['tone-working'], t['tone-attention'], t['tone-done'], t['tone-urgent'], t['accent'], p[5], p[6], p[11], p[10], p[9]]
+    lines.append('        multiplayer_user_colors { ' + ' '.join(f'player_{i + 1} "{c}";' for i, c in enumerate(players)) + ' }')
+    # No legacy `fg bg black … orange` line: in a component-format theme Zellij 0.45.1 neither reads nor validates
+    # those keys, and none of a theme's colours reach the browser's xterm.js palette (DEF-1413; _web_client does).
+    lines.append('    }')
+    return lines
+
+
+ANSI_NAMES = ('black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white')
+
+
+def _web_client():
+    """The phone's terminal palette. Zellij 0.45.1 sends `web_client.theme` to every browser as `SetConfig.theme`,
+    which the web client assigns to xterm.js `options.theme` (zellij-client `control_message.rs` / `app.js`
+    `terminalConfigOptions`). Without this block only background, foreground and selection fall back to a theme's
+    components and the sixteen ANSI slots stay xterm.js's built-in defaults. The block is server-wide and holds ONE
+    palette: the dark variant, the phone's default. It reaches the browser in the HTTP boot config at connect (the
+    xterm.js `Terminal` constructor) and in a `SetConfig` on every config-file reload, which the client assigns
+    wholesale before repainting `<body>`/`#terminal` inline, so the phone's light toggle needs a client-side
+    `term.options.theme` override applied on attach and re-applied after each `SetConfig`, plus a CSS background rule,
+    not set once (spec §6.3, Task 28; DEF-1413). Zellij validates every colour here (an unparseable one fails
+    `setup --check`), so `test_tokens` can prove the block is read."""
+    t, p = TOKENS['dark'], PALETTE16['dark']
+    lines = ['web_client {', '    font "monospace"', '    theme {',
+             f'        background "{t["surface"]}"', f'        foreground "{t["ink"]}"']
+    lines += [f'        {n} "{p[i]}"' for i, n in enumerate(ANSI_NAMES)]
+    lines += [f'        bright_{n} "{p[i + 8]}"' for i, n in enumerate(ANSI_NAMES)]
+    lines += [f'        selection_background "{t["accent-wash"]}"', f'        selection_foreground "{t["ink"]}"']
+    lines += ['    }', '}']
+    return lines
+
+
+def render_kdl():
+    lines = ['// BEGIN lanes tokens (generated by libexec/tokens.py --kdl; do not edit by hand)', 'themes {']
+    lines += _theme('lanes-dark', 'dark') + _theme('lanes-light', 'light')
+    lines += ['}', 'theme_dark "lanes-dark"', 'theme_light "lanes-light"']
+    lines += _web_client() + ['// END lanes tokens']
+    return '\n'.join(lines) + '\n'
+
+
+ALIASES = {'bg': 'surface', 'panel': 'surface-raised', 'border': 'line', 'text': 'ink', 'muted': 'ink-dim',
+           'current': 'accent-wash', 'current-border': 'accent-line'}
+ZJ = {'bg': 'surface', 'surface': 'surface-raised', 'border': 'line', 'text': 'ink', 'text-dim': 'ink-dim',
+      'green': 'tone-done', 'blue': 'tone-working', 'red': 'tone-urgent', 'yellow': 'tone-attention'}
+
+
+def render_css():
+    """Values per variant; every `var()` indirection (legacy aliases, upstream `--zj-*`) ONCE. All three selectors
+    match the same <html> element and a custom property's var() resolves against that element's winning value, so a
+    single alias follows the light override exactly like a per-variant copy did — 289 B less of the phone's mobile.css
+    growth allowance (spec §8; DEF-1414)."""
+    out = ['/* BEGIN lanes tokens (generated by libexec/tokens.py --css; do not edit by hand) */']
+    for selector, variant, scheme in (('html.lanes-mobile', 'dark', 'dark'), ('html.lanes-mobile:root[data-zj-theme="light"]', 'light', 'light')):
+        out.append(selector + ' {')
+        out += [f'  --lanes-{role}: {TOKENS[variant][role]};' for role in ROLES]
+        out.append(f'  color-scheme: {scheme};')
+        out.append('}')
+    out.append('html.lanes-mobile:root {')
+    out += [f'  --lanes-{old}: var(--lanes-{new});' for old, new in ALIASES.items()]
+    out += [f'  --zj-{k}: var(--lanes-{v});' for k, v in ZJ.items()]
+    out.append('}')
+    out.append('/* END lanes tokens */')
+    return '\n'.join(out) + '\n'
+
+
+def render_sh():
+    return ('# BEGIN lanes tokens (generated by libexec/tokens.py --sh; do not edit by hand)\n'
+            "LZ_BOLD='\\033[1m'\nLZ_DIM='\\033[90m'\n"
+            f"LZ_URGENT='\\033[{ANSI16['tone-urgent']}m'\nLZ_ATTENTION='\\033[{ANSI16['tone-attention']}m'\n"
+            f"LZ_WORKING='\\033[{ANSI16['tone-working']}m'\nLZ_DONE='\\033[{ANSI16['tone-done']}m'\nLZ_RESET='\\033[0m'\n"
+            '# END lanes tokens\n')
+
+
+def render_md():
+    rows = ['<!-- BEGIN lanes tokens (generated by libexec/tokens.py --md; do not edit by hand) -->',
+            '| Role | Dark | Light | ANSI-16 | CSS variable |', '|---|---|---|---|---|']
+    rows += [f'| {r} | `{TOKENS["dark"][r]}` | `{TOKENS["light"][r]}` | `{ANSI16.get(r, "—")}` | `--lanes-{r}` |' for r in ROLES]
+    rows += ['', '| Glyph | Codepoint | ASCII | Tone | Meaning |', '|---|---|---|---|---|']
+    for name, table in (('agent', AGENT_GLYPHS), ('stream', GLYPHS), ('mark', MARKS), ('economy', ECONOMY_TAIL)):
+        for key, (glyph, ascii_twin, tone) in table.items():
+            cp = ' '.join(f'U+{ord(c):04X}' for c in glyph)
+            cell = ascii_twin.replace('|', '\\|')   # a bare pipe splits a GFM table cell even inside backticks
+            rows.append(f'| `{glyph}` | {cp} | `{cell}` | {tone} | {name} `{key}` |')
+    rows.append('<!-- END lanes tokens -->')
+    return '\n'.join(rows) + '\n'
+
+
+RENDERERS = {'kdl': render_kdl, 'css': render_css, 'sh': render_sh, 'md': render_md}
+TARGETS = {'kdl': 'zellij/config.kdl', 'css': 'web/mobile.css', 'sh': 'libexec/tokens.sh', 'md': 'docs/DESIGN.md'}
+MARKERS = {'kdl': ('// BEGIN lanes tokens', '// END lanes tokens'), 'css': ('/* BEGIN lanes tokens', '/* END lanes tokens */'),
+           'sh': ('# BEGIN lanes tokens', '# END lanes tokens'), 'md': ('<!-- BEGIN lanes tokens', '<!-- END lanes tokens -->')}
+
+
+def render(kind):
+    return RENDERERS[kind]()
+
+
+def _splice(text, kind):
+    """Replace the marker block in `text` with the renderer's output; append when no block exists yet."""
+    begin, end = MARKERS[kind]
+    block = render(kind)
+    start = text.find(begin)
+    if start < 0:
+        return text + ('' if text.endswith('\n') or not text else '\n') + block
+    stop = text.find(end, start)
+    stop = text.find('\n', stop) + 1 if stop >= 0 else len(text)
+    return text[:start] + block + text[stop:]
+
+
+def check(repo):
+    """Paths (relative to `repo`) whose committed marker block is not what the renderer emits. A target that is
+    missing or has no block yet is reported too: an unadopted surface is drift, not a skip."""
+    drifted = []
+    for kind, rel in TARGETS.items():
+        path = Path(repo) / rel
+        try:
+            text = path.read_text()
+        except OSError:
+            drifted.append(rel)
+            continue
+        if _splice(text, kind) != text:
+            drifted.append(rel)
+    return drifted
+
+
+def main(argv):
+    repo = Path(__file__).resolve().parents[1]
+    if argv[:1] == ['--check']:
+        drifted = check(repo)
+        for rel in drifted:
+            kind = next(k for k, r in TARGETS.items() if r == rel)
+            current = (repo / rel).read_text() if (repo / rel).exists() else ''
+            sys.stdout.writelines(difflib.unified_diff(current.splitlines(True), _splice(current, kind).splitlines(True), rel, rel + ' (generated)'))
+        return 1 if drifted else 0
+    if argv[:1] == ['--write']:
+        for kind, rel in TARGETS.items():
+            path = repo / rel
+            current = path.read_text() if path.exists() else ''
+            path.write_text(_splice(current, kind))
+        return 0
+    kind = argv[0].lstrip('-') if argv else ''
+    if kind not in RENDERERS:
+        sys.exit('usage: tokens.py --kdl|--css|--sh|--md|--check|--write')
+    sys.stdout.write(render(kind))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))

package/payload/lanes/libexec/tokens.sh

@@ -0,0 +1,11 @@
+# Lanes 16-colour SGR literals for view.sh status screens. Sourced, never executed.
+# The block below is generated: edit libexec/tokens.py and run `python3 libexec/tokens.py --write`.
+# BEGIN lanes tokens (generated by libexec/tokens.py --sh; do not edit by hand)
+LZ_BOLD='\033[1m'
+LZ_DIM='\033[90m'
+LZ_URGENT='\033[31m'
+LZ_ATTENTION='\033[33m'
+LZ_WORKING='\033[34m'
+LZ_DONE='\033[32m'
+LZ_RESET='\033[0m'
+# END lanes tokens

package/payload/lanes/libexec/view.sh

@@ -103,7 +103,7 @@ while :; do
     # A background-created zellij session has no real size yet: idle until a client has attached once.
     while [ ! -e "$state/clients/$device.ready" ] || { [ "$mobile" = 1 ] && [ ! -e "$dir/$ws.$slot.shown" ]; }; do
         status_screen "$ws" 'waiting for the first client…' ''
-        run sleep 2 || :
+        run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 2 || :
     done
 
     # zellij sizes a tab only once some client has looked at it; until then the pane has a made-up size
@@ -115,7 +115,7 @@ while :; do
         [ "$mobile" != 1 ] || { min_cols=20; min_rows=4; }
         if [ "${cols:-0}" -ge "$min_cols" ] 2>/dev/null && [ "${rows:-0}" -ge "$min_rows" ] 2>/dev/null; then break; fi
         status_screen "$ws" 'waiting to be shown…' ''
-        sizing=1; run sleep 3 || :; sizing=0
+        sizing=1; run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 3 || :; sizing=0
     done
 
     lane=$(head -n 1 "$target_file" 2>/dev/null || :)
@@ -126,13 +126,13 @@ while :; do
             if [ "$slot" = main ]; then hint='Pick one in the sidebar (Ctrl-Alt-/ to find a lane).'
             else hint='In the sidebar, move to a lane and press 2 (or 3) to show it here.'; fi
             status_screen "$ws" 'No lane selected.' "$hint"
-            switching=0; run sleep 5 || :; continue ;;
+            switching=0; run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 5 --preserve-screen || :; continue ;;
     esac
     resolve=$state/resolve/$lane
     if [ ! -r "$resolve" ]; then resolve=$state/resolve.dynamic/$lane; fi
     if [ ! -r "$resolve" ]; then
         status_screen "$lane" 'This lane is no longer in the registry.' 'Pick another lane in the sidebar.'
-        switching=0; run sleep 5 || :; continue
+        switching=0; run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 5 --preserve-screen || :; continue
     fi
     { IFS= read -r holder; IFS= read -r f2; IFS= read -r f3; IFS= read -r f4; IFS= read -r title; } < "$resolve"
 
@@ -140,9 +140,10 @@ while :; do
     switching=0
     started=$(date +%s)
     case "$holder" in
-        tmux) run "$repo/holders/tmux.sh" "$f2" "$f3" "$f4" || : ;;
-        zmx)  run "$repo/holders/zmx.sh" "$f2" "$f3" "$f4" || : ;;
-        exec) run "$repo/holders/exec.sh" "$f2" "$f3" "$f4" || : ;;
+        tmux) run python3 "$repo/libexec/connection.py" --title "${title:-$lane}" -- "$repo/holders/tmux.sh" "$f2" "$f3" "$f4" || : ;;
+        ssh)  run "$repo/holders/ssh.sh" "$f2" "$f3" "$f4" || : ;;
+        zmx)  run python3 "$repo/libexec/connection.py" --title "${title:-$lane}" -- "$repo/holders/zmx.sh" "$f2" "$f3" "$f4" || : ;;
+        exec) run python3 "$repo/libexec/connection.py" --title "${title:-$lane}" -- "$repo/holders/exec.sh" "$f2" "$f3" "$f4" || : ;;
         *)    rc=64 ;;
     esac
     if [ "$switching" = 1 ]; then delay=1; continue; fi
@@ -173,7 +174,7 @@ while :; do
     health_hint "$ended"
     status_screen "${title:-$lane}" "${reason:-viewer detached (exit $rc)}${untouched}; retrying in ${delay}s.${host_hint:+
   $host_hint}" "$holder · $f2 · $f3 · $f4" "$lead"
-    run sleep "$delay" || :
+    run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait "$delay" --preserve-screen || :
     delay=$((delay * 2))
     if [ "$delay" -gt 15 ]; then delay=15; fi
 done

package/payload/lanes/web/README.md

@@ -5,6 +5,21 @@ The Lanes shell enhances the pinned Zellij 0.45.1 web client on phones. It uses
 There is no separate auth system or command API. Workspace names are rendered as text, and navigation
 uses Zellij's authenticated `FocusPane` messages. Desktop browsers keep the upstream interface.
 
+`laneShellMode` (in `mobile.js`) chooses the mode once at load and records it on `<html data-lanes-shell>`:
+phones get this shell; tablets (other touch screens) get the same shell with the dock in the top bar and the
+workspace sheet as a left panel, and set `zellij:mobile-ui` to `on` when it is unset (iPad Safari reports a desktop
+user agent). Desktop browsers (fine pointer) get only a **Lanes** chip and an overlay bar with workspace and lane
+pickers (`laneBarModel`, from the `MobileState` sent to every web client). The laptop/tablet code and styles live in
+`browser.js`/`browser.css`, which `mobile.js` appends only on a tablet or desktop (a phone never downloads them), so
+the phone's `mobile.js`/`mobile.css` budget (spec §8) stays with the phone. The chip cancels `mousedown` and
+refocuses the terminal, so the keys stay the terminal's. On a tablet, `browser.js` also undoes the client's per-load single-pane start once
+(`laneFullRender`, the client's own `SetMobileRenderPreferences {single_pane: false, fit: true}`), so a desktop
+view's sidebar shows beside its lanes. `tests/web/activation.test.mjs` (`node --test`) pins the activation matrix,
+the picker model and that render preference; `tests/unit/test_web_view.py` pins the size budgets and runs that
+suite when node is installed. After an upgrade,
+check that `__zjMobileUi`, `__zjSendControl`, `__zjSoftKbdCapture`, `__zjSyncInactiveCursorStyle` and `window.term`
+still exist in the served `app.js`.
+
 The phone keyboard opens through a native tap on an input field. The bottom **Type here** field contains
 Zellij's original capture input in its closed shadow root, preserving its keyboard/IME handling. The client
 blocks programmatic focus on text editors and keeps `__zjSoftKbdEnabled` false, so upstream touch handlers,