@vibelord/lanes 1.1.1 → 1.2.0

package/payload/lanes/libexec/statusd.py

@@ -6,7 +6,8 @@ dead sockets are never probed), run one read-only `list-panes -a` per live serve
 at most PROBE_WORKERS at once, the whole round cut at PROBE_TIMEOUT + PROBE_GRACE seconds, the servers the last
 round cut started first — and publish ~/.local/state/lanes/status.json
 atomically, plus the one-line ~/.local/state/lanes/health. The sidebar, `lanes status`, `lanes doctor` and the
-future Throttle web harness all read those files.
+future Throttle web harness all read those files. Each workspace container that has the lane contract also gets its
+own slice as ~/.lz/status.json (LNS-32, `write_container_status`), for readers inside it.
 
 It never INVENTS a state. "No answer" (a tmux, cgroup, docker or zmx read that timed out or failed on an overloaded
 host) is not an observation: the lane keeps its last published state, marked stale, for at most STALE_MAX seconds
@@ -39,6 +40,7 @@ PROBE_WORKERS = 8
 PROBE_GRACE = 2
 CONTAINER_REFRESH = 300  # docker is asked again this often as a safety net; liveness itself comes from /proc/<pid>
 CONTAINER_RETRY = 30     # ... and at most this often while a container is down or docker did not answer
+HOT_SYNC_EVERY_S = 10    # hot_sync starts at most one `lanes sync` per this many seconds (the sidebar's PENDING_S)
 ACTIVE_WINDOW = 20  # seconds since last output for a lane to count as active
 STALE_MAX = 300     # a lane nobody could observe for this long is published as 'unknown', no longer as last seen
 FIELDS = ['session_name', 'pane_pid', 'pane_dead', 'window_activity', 'pane_current_command',
@@ -236,8 +238,9 @@ def keep(previous, lane_id, outcome):
 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. `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."""
+    default to "this pane alone", which is what a caller with a single row has. `agent` is the lane's settled
+    agent{} (`settled`: `agent_state.merge`'s verdict debounced by `agent_state.settle`): published as the additive
+    `agent` key, absent when no signal names an agent."""
     if activity is None:
         try:
             activity = int(pane['window_activity'])
@@ -267,6 +270,15 @@ def lane_entry(pane, now, activity=None, viewing=(), agent=None):
     return entry
 
 
+def settled(previous, lane_id, now, raw):
+    """What a live lane publishes as its agent{} this cycle: `merge`'s verdict `raw` debounced against the agent{} the
+    PREVIOUS payload published for the same lane id (`agent_state.settle`, cockpit v3 S1). `previous` is the last
+    published payload — `new_context()` seeds it from status.json, so a restarted daemon keeps every lane's
+    `stable_since`. Called at both merge sites in `observe`: declared lanes and undeclared sessions alike."""
+    old = ((previous.get('lanes') or {}).get(lane_id) or {}) if isinstance(previous, dict) else {}
+    return AS.settle(old.get('agent') if isinstance(old, dict) else None, raw, now)
+
+
 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
@@ -546,6 +558,11 @@ def observe(registry, containers, live, previous=None, report=None):
                 try:
                     pane = own_sessions[name]
                     old_ws, old = prior.get((container, socket, name), (None, None))
+                    if old is None:
+                        # Listed for the first time: maybe a session `registrations.unregister` just released. It had
+                        # no listing to carry its id over (it was a lane), and its directory may name another board
+                        # now — the hand-back keeps the board and id it was registered under (S7 fix, DEF-1826).
+                        old_ws, old = A.handed_back(container, socket, name, pane)
                     board_ids = {w['id'] for w in registry['workspaces']}
                     workspace_id = A.workspace_for(registry, container, socket, pane['pane_current_path'],
                                                    owners.get((container, socket), set()),
@@ -586,8 +603,9 @@ def observe(registry, containers, live, previous=None, report=None):
                     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, []),
-                                       AS.merge(pane, claude.get(container, {}),
-                                                sidecars.get(container, {}).get(entry['id'])))
+                                       settled(previous, entry['id'], now,
+                                               AS.merge(pane, claude.get(container, {}),
+                                                        sidecars.get(container, {}).get(entry['id']))))
                 except Exception as error:
                     log(f'observe {container}/{socket}/{name}', error)
                     continue
@@ -606,8 +624,9 @@ def observe(registry, containers, live, previous=None, report=None):
             else:
                 try:
                     lanes[lane['id']] = lane_entry(pane, now, activities.get(session), viewers.get(session, []),
-                                                   AS.merge(pane, claude.get(container, {}),
-                                                            sidecars.get(container, {}).get(lane['id'])))
+                                                   settled(previous, lane['id'], now,
+                                                           AS.merge(pane, claude.get(container, {}),
+                                                                    sidecars.get(container, {}).get(lane['id']))))
                 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')
@@ -909,7 +928,110 @@ def new_context():
     for entry in (seed.get('lanes') or {}).values():
         entry.setdefault('stale_since', int(written))
     return {'registry': None, 'stamp': 0, 'containers': {}, 'containers_at': 0.0,
-            'payload': seed, 'published': None, 'status_at': written, 'cut': 0, 'unwalkable': []}
+            'payload': seed, 'published': None, 'status_at': written, 'cut': 0, 'unwalkable': [],
+            'container_status': {}, 'container_status_errors': {}}
+
+
+# ------------------------------------------- the in-container projection (LNS-32)
+# `~/.lz/status.json` in each workspace container: that container's slice of the payload, for the in-container Agent
+# API (`lane-mcp`, plan Track M), which cannot read the host's status.json. v1 = {v, at, lanes{<id>: {state, agent?,
+# attached?, viewers?, activity?, size?, stale?}}, unregistered[{id, name, workspace, boards, tmux, identity}]}.
+CONTAINER_STATUS_FIELDS = ('state', 'agent', 'attached', 'viewers', 'activity', 'size', 'stale')
+CONTAINER_STATUS_DIR = tuple(L.CONTAINER_HOME.strip('/').split('/')) + ('.lz',)
+CONTAINER_STATUS_FILE = 'status.json'
+
+
+def container_status(registry, payload):
+    """{container: {'lanes': …, 'unregistered': […]}} — what each workspace container may read about ITS OWN lanes
+    (pure). `lanes` holds every lane the registry places in the container (declared and registered: the ids its
+    `~/.lz/registry.json` holds) and every unregistered session statusd found there, each reduced to the fields a
+    reader in the container needs; a row a cycle has not observed yet is `unknown`, never invented. The host-side
+    details (cwd, pid, tty, command, where an unanswered probe failed) stay on the host, and `stale` is carried so a
+    kept row is never read as a fresh one. A session listed under several boards is ONE `unregistered` row naming
+    them all in `boards`. zmx lanes are not projected: the container's own `lane ls`/`lane status` read them from
+    zmx and lane-run directly, and their `agent` is lane-run's phase record, not an `agent_state` verdict."""
+    rows = (payload or {}).get('lanes') or {}
+    ids = {}
+    for workspace in (registry or {}).get('workspaces') or []:
+        for lane in workspace.get('lanes') or []:
+            if lane.get('container') and lane.get('id'):
+                ids.setdefault(lane['container'], []).append(lane['id'])
+    ghosts = {}
+    for board, entries in sorted(((payload or {}).get('unregistered') or {}).items()):
+        for entry in entries or []:
+            if not isinstance(entry, dict) or not entry.get('container') or not entry.get('id'):
+                continue
+            ghost = ghosts.setdefault(entry['container'], {}).setdefault(entry['id'], {
+                'id': entry['id'], 'name': entry.get('name'), 'workspace': entry.get('workspace') or board,
+                'boards': [], 'tmux': entry.get('tmux'), 'identity': entry.get('identity')})
+            if board not in ghost['boards']:
+                ghost['boards'].append(board)
+    out = {}
+    for container in sorted(set(ids) | set(ghosts)):
+        found = ghosts.get(container, {})
+        lanes = {}
+        for lane_id in ids.get(container, []) + sorted(found):
+            row = rows.get(lane_id) if isinstance(rows.get(lane_id), dict) else {}
+            lanes[lane_id] = {key: row[key] for key in CONTAINER_STATUS_FIELDS if key in row}
+            lanes[lane_id].setdefault('state', 'unknown')
+        out[container] = {'lanes': lanes, 'unregistered': [found[lane_id] for lane_id in sorted(found)]}
+    return out
+
+
+def write_container_status(ctx, payload, now=None):
+    """Write `container_status` into each running workspace container that has the lane contract (`~/.lz/bin/lane`,
+    the rule `lanes_lib.export_container_registries` follows) -> the containers whose file was written.
+
+    At most one small write per container per cycle, and none while that container's slice is unchanged: `at` is
+    the time of the last write, renewed on a change or once HEARTBEAT has passed, so an unchanged slice renders the
+    same bytes and `atomic_write_if_changed_at` skips it, while a reader can still tell a live statusd from a dead
+    one by the age of `at`. Written through /proc/<init pid>/root like every other read of the container here, into
+    a directory the container owns: `lanes_lib.open_real_dir` refuses a symlinked component and the write replaces
+    whatever is at the name without following or reading it (a planted link or FIFO). A container without the
+    contract is skipped silently; any other failure is logged once per distinct error and costs only that container."""
+    now = time.time() if now is None else now
+    last, errors = ctx.setdefault('container_status', {}), ctx.setdefault('container_status_errors', {})
+    written = []
+    slices = container_status(ctx.get('registry'), payload)
+    for gone in set(last) - set(slices):
+        del last[gone]
+    for container, content in slices.items():
+        info = (ctx.get('containers') or {}).get(container) or {}
+        if not info.get('pid') or not info.get('running'):
+            continue
+        before = last.get(container)
+        fresh = before and before['content'] == content and now - before['at'] <= HEARTBEAT
+        at = before['at'] if fresh else now
+        text = json.dumps({'v': 1, 'at': at, **content}, ensure_ascii=False, indent=1) + '\n'
+        try:
+            fd = L.open_real_dir(Path(L.proc_root()) / str(info['pid']) / 'root', CONTAINER_STATUS_DIR)
+        except FileNotFoundError:
+            continue                              # no ~/.lz: the lane contract is not installed there
+        except (OSError, L.LanesError) as error:
+            _container_status_error(errors, container, error)
+            continue
+        try:
+            try:
+                os.stat('bin/lane', dir_fd=fd)
+            except FileNotFoundError:
+                continue                          # a ~/.lz without `lane`: not installed either
+            if L.atomic_write_if_changed_at(fd, CONTAINER_STATUS_FILE, text, mode=0o644):
+                written.append(container)
+            last[container] = {'content': content, 'at': at}
+            errors.pop(container, None)
+        except (OSError, L.LanesError) as error:
+            _container_status_error(errors, container, error)
+        finally:
+            os.close(fd)
+    return written
+
+
+def _container_status_error(errors, container, error):
+    """Log a container's projection failure once per distinct error, not every INTERVAL."""
+    message = f'{type(error).__name__}: {error}'
+    if errors.get(container) != message:
+        errors[container] = message
+        log(f'container status {container}', error)
 
 
 def cycle(ctx, reconcile=True):
@@ -938,6 +1060,10 @@ def cycle(ctx, reconcile=True):
                 ctx['published'], ctx['status_at'] = payload, written
             except Exception as error:
                 log('status.json', error)
+        try:   # LNS-32: each container's own slice, into its ~/.lz (one small write per container at most)
+            write_container_status(ctx, payload)
+        except Exception as error:
+            log('container status', error)
     try:   # "servers alive, sockets deleted" as a flag file: view.sh, the sidebar and doctor read it without parsing
         lost = sorted(key for key, server in ((payload or {}).get('servers') or {}).items() if server.get('outcome') == 'nosocket')
         flag = L.STATE / 'flags' / 'sockets-lost'
@@ -1014,6 +1140,7 @@ def hot_sync(ctx, source_mtimes):
 
 
 def main():
+    L.record_tree('statusd')   # W9 U0: the tree this daemon runs from (`lanes version`, doctor); --once never records
     ctx = new_context()
     last_triggered_sync = 0.0
     source_mtimes = {}   # host path of a terminals.json -> its mtime_ns at last check
@@ -1021,8 +1148,8 @@ def main():
         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']:
+        # Rate-limited to at most one triggered sync per HOT_SYNC_EVERY_S to avoid thrashing.
+        if time.time() - last_triggered_sync > HOT_SYNC_EVERY_S and ctx['registry']:
             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

package/payload/lanes/libexec/studio_host.py

@@ -39,6 +39,9 @@ import tempfile
 import time
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lanes_lib as L  # noqa: E402
+
 UNIT = 'lanes-studio-host.service'
 ENROL_SERVICE = 'lanes-studio-host-enrol.service'
 ENROL_TIMER = 'lanes-studio-host-enrol.timer'
@@ -1040,7 +1043,10 @@ def _enrol(layout, options, plan, record, receipt, key_file):
 
 
 def _units(layout, plan):
-    """Step 6: render every lanes unit for this checkout (services.py), then enable the Host and its retry timer."""
+    """Step 6: render every lanes unit (services.py), then enable the Host and its retry timer. A re-render, never an
+    install: services.register(install=False) renders the release `current` names and moves no link, so this step run
+    from a tree an update has moved past cannot put the old release back (DEF-1835); it links `current` to this tree
+    only where it names none yet."""
     repo = Path(__file__).resolve().parent.parent
 
     def render():
@@ -1169,6 +1175,7 @@ def enable(argv, layout=None):
     backup = _ensure_config(layout, options, plan)
     if not options['dry_run']:
         _remember_paths(layout, options, record)
+        L.record_tree('studio_host', layout.state)   # W9 U0: the enrol unit's tree, past every static refusal
     replaced = []   # set once the hand-built unit is saved, disabled and stopped
 
     def give_back():

package/payload/lanes/libexec/tokens.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
-"""The Lanes design tokens: ONE table, rendered seven ways. The sidebar imports `sgr_table`; `--kdl`, `--css`, `--sh`,
-`--md`, `--js` and `--ghostty-dark|--ghostty-light` write the Zellij theme, the phone CSS, the viewer's shell variables,
-the docs table, the phone's terminal palette and the optional Ghostty palette files between markers; `--check` fails
-when any committed block differs. Spec: docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md.
+"""The Lanes design tokens: ONE table, rendered seven ways. The sidebar imports `sgr_table` (truecolor, 256, 16 or
+none); `--kdl`, `--css`, `--sh`, `--md`, `--js` and `--ghostty-dark|--ghostty-light` write the Zellij theme, the phone
+CSS, the viewer's shell colour sets, the docs tables, the phone's terminal palette and the optional Ghostty palette
+files between markers; `--check` fails when any committed block differs. Spec:
+docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md; palette v2 + the 256-colour set: cockpit v3 P1 (LNS-69).
 No third-party code; importable with no side effects."""
 import difflib
 import os
@@ -12,30 +13,54 @@ 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')
+# Palette v2 (cockpit v3 P1, 2026-10-06): vivid, high-contrast roles in both variants. v1 had darkened the light tones
+# until they passed (amber #8a5a00 read olive-brown). Surfaces are v1's but for the dark accent-wash, the cursor row.
 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',
+    'dark': {'surface': '#101318', 'surface-raised': '#191e25', 'line': '#2c333d', 'accent-wash': '#1c3326',
+             'accent-line': '#4b6955', 'press': '#26332c', 'chip': '#ffffff0f', 'ink': '#f2f5f8', 'ink-dim': '#a6b1be',
+             'ink-faint': '#6f7a87', 'accent': '#8fe3a6', 'on-accent': '#101318', 'on-accent-urgent': '#7a1a12',
+             'tone-urgent': '#ff7b6e', 'tone-attention': '#ffc233', 'tone-working': '#6fb6ff', 'tone-done': '#5fdc8a',
              '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',
+              'accent-line': '#acc9b4', 'press': '#d8e9db', 'chip': '#edf3ec', 'ink': '#111a14', 'ink-dim': '#4a5661',
+              'ink-faint': '#6f7b87', 'accent': '#1f6f3f', 'on-accent': '#ffffff', 'on-accent-urgent': '#ffd3cc',
+              'tone-urgent': '#c41c1c', 'tone-attention': '#a04d00', 'tone-working': '#1a56c4', 'tone-done': '#0d7338',
               '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'}
+# Painted roles that are a BACKGROUND, by the token they take their colour from. `selected` is the cursor row (cockpit
+# v3 P2 paints it): the accent-wash the Zellij themes' *_selected components and the phone's current row
+# (--lanes-accent-wash) already use, with ink on it. Not a CSS variable of its own: the phone needs none, and a copy
+# per variant would cost 58 B of the 37 B mobile.css still has under spec §8's cap.
+BACKGROUNDS = {'selected': 'accent-wash'}
+PAINTED = tuple(ANSI16) + tuple(BACKGROUNDS)   # the roles the TUI ever emits
+# The colour modes whose colours Lanes defines (cockpit v3 P2/P3): the sidebar spends the palette in them, and view.sh
+# (`LZ_VIVID`) the warning tone on its lead. 16 is the user's own palette and none has no colour: both keep v1's bytes.
+VIVID = ('truecolor', '256')
+# The 256-colour set: one xterm index per painted role, always from 16-255 (fixed RGB; 0-15 are the user's palette).
+# Each is the nearest entry (RGB distance) in its token's hue family — greys for the inks — that keeps every text role
+# >= 4.2:1 on surface, surface-raised and the 256 `selected` band; `selected` is the nearest entry to the wash. The
+# floor is 4.2, not 4.5, for the cube's six levels alone (test_tokens.Xterm256 re-derives every index). Light accent
+# and done share 22 (#005f00): the nearest passing entry, 23, is a teal.
+XTERM256 = {
+    'dark': {'ink': 255, 'ink-dim': 249, 'ink-faint': 243, 'accent': 115, 'tone-urgent': 209, 'tone-attention': 215,
+             'tone-working': 75, 'tone-done': 78, 'selected': 235},
+    'light': {'ink': 233, 'ink-dim': 240, 'ink-faint': 243, 'accent': 22, 'tone-urgent': 160, 'tone-attention': 94,
+              'tone-working': 26, 'tone-done': 22, 'selected': 254},
+}
 # 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.
+# NOT one of them (DEF-1413). The TUI itself keeps 38;5;N. Slots 1-4 are the four tones and 7 / 15 the ink pair
+# (PALETTE16_ROLES); v2 re-saturates the rest (more chroma than v1 in every chromatic slot). 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'],
+    'dark': ['#8792a0', '#ff7b6e', '#5fdc8a', '#ffc233', '#6fb6ff', '#c58bff', '#3fd9cf', '#a6b1be',
+             '#97a3b1', '#ff9a8e', '#86f0ad', '#ffd866', '#98cbff', '#dcb2ff', '#7deee6', '#f2f5f8'],
+    'light': ['#2f3b34', '#c41c1c', '#0d7338', '#a04d00', '#1a56c4', '#8228c4', '#006f73', '#4a5661',
+              '#55625b', '#d0221a', '#0e7a3a', '#a85200', '#1f5fd8', '#9133d0', '#00797c', '#111a14'],
 }
+PALETTE16_ROLES = {1: 'tone-urgent', 2: 'tone-done', 3: 'tone-attention', 4: 'tone-working', 7: 'ink-dim', 15: 'ink'}
 # 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'),
@@ -52,11 +77,27 @@ MARKS = {'cursor': ('▌', '|', 'accent'), 'viewing': ('›', '=', 'accent'), 'v
          # 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'),
+         # The confirmation's dash (` › close ‘sh’ — y⏎ confirm · Esc cancel`, cockpit v3 S3/S6); `-` like `sep`.
+         'dash': ('—', '-', 'ink-dim'),
+         # The focus legend's arrow (` ▌ keys go to sidebar · Esc → lane`, cockpit v3 S4).
+         'arrow': ('→', '->', 'accent'),
+         # Column 3 of a row whose registration is on its way (`P`, cockpit v3 S8): the session stays listed, dimmed
+         # mark, until the registry lists its lane. The truncation pair on purpose — position disambiguates (column 3,
+         # never the end of a name) — and seven-bit `~` is free in column 3 (`=` `2` `3` are the other marks there).
+         'pending': ('…', '~', 'ink-dim'),
+         # Column 3 of a lane its owner pinned (`p`, cockpit v3 R5): it leads its section and never falls below `⋮ N
+         # more`. The lowest of column 3's marks: pending, the viewports and the viewing mark win over it. Seven-bit
+         # `^` is free in column 3 (`=` `2` `3` `~` are the others; the upload strip's `^` is no column-3 mark).
+         'pinned': ('▲', '^', 'accent'),
          '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 hex_of(variant, role):
+    """The colour a role paints: its own token, or for a background role the token it takes (`selected` -> wash)."""
+    return TOKENS[variant][BACKGROUNDS.get(role, role)]
 
 
 def luminance(hexval):
@@ -74,17 +115,24 @@ 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."""
+def sgr_table(mode, variant, dim16=None):
+    """Complete escape per painted role. `mode` truecolor|256|16|none; `variant` dark|light. Resolved ONCE per process.
+    Foreground roles are `38;…`, `selected` (the cursor row) `48;…`; in 16/none it is empty — the palette there is the
+    user's, and the cursor stays the bold bar. `dim16` overrides the 16-colour dim (default: `LANES_DIM=2` -> SGR 2,
+    else 90); the shell renderer pins 90 so the committed block never depends on the generator's environment."""
     table = {'bold': '\033[1m', 'reset': '\033[0m'}
-    dim16 = '\033[2m' if os.environ.get('LANES_DIM') == '2' else '\033[90m'
+    if dim16 is None:
+        dim16 = '\033[2m' if os.environ.get('LANES_DIM') == '2' else '\033[90m'
     for role in PAINTED:
+        bold, layer = '\033[1m' if role == 'accent' else '', 48 if role in BACKGROUNDS else 38
         if mode == 'none':
-            table[role] = '\033[1m' if role == 'accent' else ''
+            table[role] = bold
         elif mode == '16':
-            table[role] = dim16 if role in ('ink-dim', 'ink-faint') else f'\033[{ANSI16[role]}m'
+            table[role] = '' if role in BACKGROUNDS else dim16 if role in ('ink-dim', 'ink-faint') else f'\033[{ANSI16[role]}m'
+        elif mode == '256':
+            table[role] = bold + '\033[%d;5;%dm' % (layer, XTERM256[variant][role])
         else:
-            table[role] = ('\033[1m' if role == 'accent' else '') + '\033[38;2;%d;%d;%dm' % rgb(TOKENS[variant][role])
+            table[role] = bold + '\033[%d;2;%d;%d;%dm' % ((layer,) + rgb(hex_of(variant, role)))
     return table
 
 
@@ -194,18 +242,61 @@ def render_css():
     return '\n'.join(out) + '\n'
 
 
+# The painted roles as the viewer's shell variables (`tokens.sh`), in PAINTED order. LZ_DIM kept its v1 name.
+SH_NAMES = {'ink': 'LZ_INK', 'ink-dim': 'LZ_DIM', 'ink-faint': 'LZ_FAINT', 'accent': 'LZ_ACCENT',
+            'tone-urgent': 'LZ_URGENT', 'tone-attention': 'LZ_ATTENTION', 'tone-working': 'LZ_WORKING',
+            'tone-done': 'LZ_DONE', 'selected': 'LZ_SELECTED'}
+SH_SETS = (('256', 'dark'), ('256', 'light'), ('truecolor', 'dark'), ('truecolor', 'light'))
+
+
+def _sh_set(mode, variant, indent):
+    """One set's assignments: every painted role, then `LZ_VIVID` (`1` in a VIVID mode, else empty) — what view.sh asks
+    instead of re-matching the mode words itself (cockpit v3 P3)."""
+    table = sgr_table(mode, variant, dim16='\033[90m')
+    lines = [indent + "%s='%s'" % (SH_NAMES[role], table[role].replace('\033', '\\033')) for role in PAINTED]
+    return lines + [indent + "LZ_VIVID='%s'" % ('1' if mode in VIVID else '')]
+
+
 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')
+    """The viewer's colour sets as POSIX-shell literals holding `\\033` as text (they go into printf's FORMAT). A plain
+    `. tokens.sh` assigns the 16-colour set — the user's own palette; `lz_tones MODE VARIANT` re-points every LZ_* tone
+    variable to the 256 / truecolor set of dark / light, `lz_tones none` (one argument) to none, and anything else —
+    `lz_tones 16`, no argument, an unknown mode or variant — back to 16 colours. Every set also says `LZ_VIVID` (`1`
+    in truecolor and 256). The `case` word reads `${1:-}:${2:-}`: view.sh runs `set -u`, where a bare `$2` aborts the
+    shell on a one-argument call (DEF-1772). Assignments and one `case` only: sourcing or calling it forks nothing
+    (cockpit v3 P1). view.sh calls `lz_tones "$color" "$theme"` with its device's `.color`/`.theme` stamps on every
+    status screen (cockpit v3 P3)."""
+    lines = ['# BEGIN lanes tokens (generated by libexec/tokens.py --sh; do not edit by hand)',
+             "LZ_BOLD='\\033[1m'", "LZ_RESET='\\033[0m'"]
+    lines += _sh_set('16', 'dark', '')
+    lines += ['lz_tones() {', '    case "${1:-}:${2:-}" in']
+    for mode, variant in SH_SETS:
+        lines += [f'    {mode}:{variant})'] + _sh_set(mode, variant, '        ') + ['        ;;']
+    lines += ['    none:*)'] + _sh_set('none', 'dark', '        ') + ['        ;;']
+    lines += ['    *)'] + _sh_set('16', 'dark', '        ') + ['        ;;']
+    lines += ['    esac', '}', '# END lanes tokens']
+    return '\n'.join(lines) + '\n'
+
+
+def _md_role(role):
+    """One row of the role table: hex per variant, the 256 index per variant, the 16-colour SGR, the CSS variable."""
+    painted = role in PAINTED
+    x256 = [f'`{XTERM256[v][role]}`' if painted else '`—`' for v in ('dark', 'light')]
+    ansi = '—' if role in BACKGROUNDS else ANSI16.get(role, '—')
+    return (f'| {role} | `{hex_of("dark", role)}` | `{hex_of("light", role)}` | {x256[0]} | {x256[1]} | `{ansi}` | '
+            f'`--lanes-{BACKGROUNDS.get(role, role)}` |')
 
 
 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]
+            '| Role | Dark | Light | 256 dark | 256 light | ANSI-16 | CSS variable |', '|---|---|---|---|---|---|---|']
+    for role in ROLES:
+        rows.append(_md_role(role))
+        rows += [_md_role(bg) for bg, source in BACKGROUNDS.items() if source == role]   # `selected` under its wash
+    rows += ['', '| Slot | ANSI | Dark | Light | Role |', '|---|---|---|---|---|']
+    names = ANSI_NAMES + tuple('bright ' + n for n in ANSI_NAMES)
+    rows += [f'| {i} | {names[i]} | `{PALETTE16["dark"][i]}` | `{PALETTE16["light"][i]}` | {PALETTE16_ROLES.get(i, "—")} |'
+             for i in range(16)]
     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():

package/payload/lanes/libexec/tokens.sh

@@ -1,11 +1,95 @@
-# Lanes 16-colour SGR literals for view.sh status screens. Sourced, never executed.
+# Lanes SGR literals for view.sh status screens: the 16-colour set on sourcing, and `lz_tones MODE VARIANT` for the
+# 256-colour, truecolor and none sets (`lz_tones none` takes one argument; safe under view.sh's `set -u`). view.sh calls
+# `lz_tones "$color" "$theme"` with its device's clients/<device>.color and .theme stamps on every status screen; every
+# set also says LZ_VIVID (`1` in truecolor and 256, the colours Lanes defines). 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_RESET='\033[0m'
+LZ_INK='\033[39m'
 LZ_DIM='\033[90m'
+LZ_FAINT='\033[90m'
+LZ_ACCENT='\033[1;39m'
 LZ_URGENT='\033[31m'
 LZ_ATTENTION='\033[33m'
 LZ_WORKING='\033[34m'
 LZ_DONE='\033[32m'
-LZ_RESET='\033[0m'
+LZ_SELECTED=''
+LZ_VIVID=''
+lz_tones() {
+    case "${1:-}:${2:-}" in
+    256:dark)
+        LZ_INK='\033[38;5;255m'
+        LZ_DIM='\033[38;5;249m'
+        LZ_FAINT='\033[38;5;243m'
+        LZ_ACCENT='\033[1m\033[38;5;115m'
+        LZ_URGENT='\033[38;5;209m'
+        LZ_ATTENTION='\033[38;5;215m'
+        LZ_WORKING='\033[38;5;75m'
+        LZ_DONE='\033[38;5;78m'
+        LZ_SELECTED='\033[48;5;235m'
+        LZ_VIVID='1'
+        ;;
+    256:light)
+        LZ_INK='\033[38;5;233m'
+        LZ_DIM='\033[38;5;240m'
+        LZ_FAINT='\033[38;5;243m'
+        LZ_ACCENT='\033[1m\033[38;5;22m'
+        LZ_URGENT='\033[38;5;160m'
+        LZ_ATTENTION='\033[38;5;94m'
+        LZ_WORKING='\033[38;5;26m'
+        LZ_DONE='\033[38;5;22m'
+        LZ_SELECTED='\033[48;5;254m'
+        LZ_VIVID='1'
+        ;;
+    truecolor:dark)
+        LZ_INK='\033[38;2;242;245;248m'
+        LZ_DIM='\033[38;2;166;177;190m'
+        LZ_FAINT='\033[38;2;111;122;135m'
+        LZ_ACCENT='\033[1m\033[38;2;143;227;166m'
+        LZ_URGENT='\033[38;2;255;123;110m'
+        LZ_ATTENTION='\033[38;2;255;194;51m'
+        LZ_WORKING='\033[38;2;111;182;255m'
+        LZ_DONE='\033[38;2;95;220;138m'
+        LZ_SELECTED='\033[48;2;28;51;38m'
+        LZ_VIVID='1'
+        ;;
+    truecolor:light)
+        LZ_INK='\033[38;2;17;26;20m'
+        LZ_DIM='\033[38;2;74;86;97m'
+        LZ_FAINT='\033[38;2;111;123;135m'
+        LZ_ACCENT='\033[1m\033[38;2;31;111;63m'
+        LZ_URGENT='\033[38;2;196;28;28m'
+        LZ_ATTENTION='\033[38;2;160;77;0m'
+        LZ_WORKING='\033[38;2;26;86;196m'
+        LZ_DONE='\033[38;2;13;115;56m'
+        LZ_SELECTED='\033[48;2;229;240;230m'
+        LZ_VIVID='1'
+        ;;
+    none:*)
+        LZ_INK=''
+        LZ_DIM=''
+        LZ_FAINT=''
+        LZ_ACCENT='\033[1m'
+        LZ_URGENT=''
+        LZ_ATTENTION=''
+        LZ_WORKING=''
+        LZ_DONE=''
+        LZ_SELECTED=''
+        LZ_VIVID=''
+        ;;
+    *)
+        LZ_INK='\033[39m'
+        LZ_DIM='\033[90m'
+        LZ_FAINT='\033[90m'
+        LZ_ACCENT='\033[1;39m'
+        LZ_URGENT='\033[31m'
+        LZ_ATTENTION='\033[33m'
+        LZ_WORKING='\033[34m'
+        LZ_DONE='\033[32m'
+        LZ_SELECTED=''
+        LZ_VIVID=''
+        ;;
+    esac
+}
 # END lanes tokens