@vibelord/lanes 1.0.1 → 1.0.2

package/payload/lanes/container/lane-signal

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""lane-signal <status> [--event NAME] [--harness claude|codex] [PAYLOAD] — the hook target of Claude Code and Codex
+inside a workspace container. Writes ~/.lz/state/hooks/<lane id>.json (atomic replace), which the host's
+lanes-statusd reads through /proc/<container init pid>/root and publishes as the lane's `agent{}` (source `hook`).
+
+The sidecar has its own directory because `lane-run`, the root process of every zmx-held lane, writes its
+`{phase, exit, at, pid}` record to ~/.lz/state/<zmx name>.json and exports LANE_ID=<zmx name> to the agent: a
+sidecar at state/<lane id>.json would overwrite that record for the agent's whole life (DEF-1436). Nothing but
+this script writes state/hooks/, and lane-run never writes there.
+
+    {"v":1, "lane":"<id>", "harness":"claude|codex", "status":"<agent{} vocabulary>", "since":<epoch the status
+     began>, "at":<epoch of this event>, "event":"<hook event>", "pid":<agent pid>, "start":"<its starttime>",
+     "session":"<session/thread id or ''>"}
+
+It never fails the agent and never speaks: every path exits 0 and nothing reaches stdout or stderr (a Claude Code
+UserPromptSubmit/SessionStart hook's stdout becomes model context). An unresolvable lane, a status outside the
+vocabulary or an unwritable state directory are silent no-ops.
+
+Lane id: $LANE_ID — exported in a tmux lane only by a canonical/`--identity` recipe's `-e` flags (Task 7, DEF-1478;
+`lane open` never exports it), and in a zmx-held lane by `lane-run` as the zmx session name (which is NOT the
+`<ws>--z-<name>` id lanes-statusd publishes for it, so statusd does not join that sidecar to the zmx lane yet:
+DEF-1437) — else the pane's tmux session (`tmux -S ${TMUX%%,*} display -p -t $TMUX_PANE '#S'`) looked up by (socket
+name, session) in ~/.lz/registry.json, the projection `lanes sync` writes.
+
+Agent pid: the parent process, or that parent's parent when the parent is a shell (Claude Code runs a hook command
+through a shell, which may fork it rather than exec it; a pid that dies with the shell would read as a dead agent).
+Session id: `session_id` of the hook's JSON on stdin, `thread-id` of a JSON PAYLOAD argument (Codex `notify` passes
+its JSON as the last argument), else $CLAUDE_SESSION_ID / $CODEX_THREAD_ID. Stdin is read only when it is not a
+terminal and for at most STDIN_WAIT seconds: a stdin that never closes cannot hang the hook.
+
+Same status as the file already holds (same session) keeps `since` and advances `at`; a new status starts `since`.
+"""
+import json
+import os
+import re
+import select
+import subprocess
+import sys
+import time
+
+STATUSES = ('working', 'needs_input', 'needs_approval', 'done', 'errored', 'shell', 'idle')   # agent_state.STATUSES
+LANE_ID = re.compile(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}')
+SHELLS = {'sh', 'dash', 'bash', 'zsh', 'ksh', 'fish'}
+STDIN_WAIT = 0.5
+STDIN_MAX = 1 << 20
+
+
+def options(argv):
+    status, event, harness, payload = (argv[0] if argv else ''), '', '', ''
+    rest = argv[1:]
+    while rest:
+        word = rest.pop(0)
+        if word == '--event' and rest:
+            event = rest.pop(0)
+        elif word == '--harness' and rest:
+            harness = rest.pop(0)
+        elif word.startswith('{'):
+            payload = word
+    return status, event[:64], harness[:16], payload
+
+
+def lane_id(root):
+    found = os.environ.get('LANE_ID', '')
+    if not found and os.environ.get('TMUX') and os.environ.get('TMUX_PANE'):
+        sock = os.environ['TMUX'].split(',', 1)[0]
+        try:
+            done = subprocess.run(['tmux', '-S', sock, 'display', '-p', '-t', os.environ['TMUX_PANE'], '#S'],
+                                  stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=1)
+            session = done.stdout.strip() if done.returncode == 0 else ''
+            lanes = json.load(open(os.path.join(root, 'registry.json'))).get('lanes') or {}
+        except (OSError, ValueError, subprocess.SubprocessError, AttributeError):
+            return ''
+        name = os.path.basename(sock)
+        for key, lane in lanes.items():
+            tmux = (lane or {}).get('tmux') or {}
+            if session and tmux.get('socket') == name and tmux.get('session') == session:
+                found = key
+                break
+    return found if LANE_ID.fullmatch(found or '') else ''
+
+
+def stat_fields(pid):
+    """Fields after `comm` of /proc/<pid>/stat (state is [0], ppid [1], starttime [19]) and the comm itself."""
+    with open(f'/proc/{pid}/stat') as handle:
+        text = handle.read()
+    comm = text[text.index('(') + 1:text.rindex(')')]
+    return comm, text.rsplit(')', 1)[1].split()
+
+
+def agent():
+    pid = os.getppid()
+    try:
+        comm, fields = stat_fields(pid)
+        if comm in SHELLS and int(fields[1]) > 1:
+            pid = int(fields[1])
+            comm, fields = stat_fields(pid)
+        return pid, fields[19]
+    except (OSError, ValueError, IndexError):
+        return pid, None
+
+
+def stdin_session():
+    try:
+        if os.isatty(0):
+            return ''
+    except OSError:
+        return ''
+    data, deadline = b'', time.monotonic() + STDIN_WAIT
+    try:
+        while len(data) < STDIN_MAX:
+            left = deadline - time.monotonic()
+            if left <= 0 or not select.select([0], [], [], left)[0]:
+                break
+            chunk = os.read(0, 65536)
+            if not chunk:
+                break
+            data += chunk
+        doc = json.loads(data.decode('utf-8', 'replace')) if data.strip() else {}
+    except (OSError, ValueError):
+        return ''
+    return str(doc.get('session_id') or '') if isinstance(doc, dict) else ''
+
+
+def main(argv):
+    status, event, harness, payload = options(argv)
+    if status not in STATUSES:
+        return
+    root = os.environ.get('LANE_ROOT') or os.path.join(os.path.expanduser('~'), '.lz')
+    lane = lane_id(root)
+    if not lane:
+        return
+    session = stdin_session()
+    if not session and payload:
+        try:
+            doc = json.loads(payload)
+            session = str(doc.get('thread-id') or doc.get('session_id') or '') if isinstance(doc, dict) else ''
+        except ValueError:
+            session = ''
+    session = session or os.environ.get('CLAUDE_SESSION_ID') or os.environ.get('CODEX_THREAD_ID') or ''
+    harness = harness or os.environ.get('LANE_HARNESS') or ('claude' if os.environ.get('CLAUDE_CODE_ENTRYPOINT')
+                                                            else 'codex')
+    pid, start = agent()
+    now = int(time.time())
+    state = os.path.join(root, 'state', 'hooks')   # never state/<id>.json: lane-run's phase record (DEF-1436)
+    path = os.path.join(state, f'{lane}.json')
+    try:
+        old = json.load(open(path))
+    except (OSError, ValueError):
+        old = None
+    session, since = session[:128], now
+    if (isinstance(old, dict) and old.get('v') == 1 and old.get('status') == status
+            and (not session or old.get('session') == session) and isinstance(old.get('since'), int)):
+        since, session = old['since'], session or str(old.get('session') or '')
+    doc = {'v': 1, 'lane': lane, 'harness': harness, 'status': status, 'since': since, 'at': now, 'event': event,
+           'pid': pid, 'start': start, 'session': session}
+    os.makedirs(state, exist_ok=True)
+    tmp = os.path.join(state, f'.{lane}.json.{os.getpid()}.tmp')
+    try:
+        with open(tmp, 'w') as handle:
+            handle.write(json.dumps(doc, separators=(',', ':')) + '\n')
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+if __name__ == '__main__':
+    try:
+        sys.stdout = sys.stderr = open(os.devnull, 'w')
+        main(sys.argv[1:])
+    except BaseException:   # noqa: BLE001 - a hook must never fail the agent: every outcome is exit 0
+        pass
+    os._exit(0)

package/payload/lanes/docs/ARCHITECTURE.md

@@ -10,7 +10,10 @@ terminal. Installing or closing a view does not end a lane.
 2. Each manifest identifies container names and repository `.vscode/terminals.json` paths.
 3. `lanes sync` reads those files through the container's mounted home, includes the site's optional
    `registered-sessions.json`, and emits the host registry,
-   exact socket/session resolve files, and the container's `.lz/registry.json` projection.
+   exact socket/session resolve files, and the container's `.lz/registry.json` projection. It asks docker about
+   every board container in ONE `docker inspect` and rewrites a projection only when its content changed
+   (`atomic_write_if_changed`; the two registry documents compare without `generated_at`), so a timer sync with
+   nothing new wakes no reader that watches an mtime. The sync time itself is kept in `registry.synced`.
 4. The status daemon observes tmux sessions and publishes status/health snapshots. Failed or timed-out
    probes mean unknown; they do not prove a missing session. A bad terminal registry retains the last good board.
 
@@ -19,7 +22,7 @@ terminal. Installing or closing a view does not end a lane.
    `working | needs_input | needs_approval | done | errored | shell | idle`. An absent key means no signal names
    an agent there. `statusd` builds it with `agent_state.merge` from signals the harnesses already emit, read once
    per container per cycle through `/proc/<container init pid>/root` without spawning anything. Precedence: a
-   hook sidecar (planned, not read yet) > a Claude `~/.claude/sessions/<pid>.json` naming the pane
+   hook sidecar > a Claude `~/.claude/sessions/<pid>.json` naming the pane
    `<session>:@<win>.%<pane>` (live pids only, checked in the container's pid namespace, recycled pids rejected
    by `procStart`) > the Codex pane title (`[ ! ] Action Required` → `needs_approval`, braille spinner →
    `working`, a task title → `idle`) > the window bell (an idle title plus a bell is `done`; an approval title
@@ -28,11 +31,29 @@ terminal. Installing or closing a view does not end a lane.
    title. Unknown liveness leaves that key unset and never demotes. The tmux columns this needs
    (`window_bell_flag`, `window_id`, `pane_id`, `pane_title`) are appended to the listing format, the free-text
    title last so a tab inside it cannot shift another column.
+
+   The hook sidecar is `~/.lz/state/hooks/<lane id>.json` in the container, written by `~/.lz/bin/lane-signal`
+   (Python 3 stdlib, installed by `lanes install-container`) when an opt-in Claude Code or Codex hook fires:
+   `{v: 1, lane, harness, status, since, at, event, pid, start, session}` — `since` when the status began (kept
+   while the same status is re-signalled), `at` the last event, `pid`/`start` the agent process and its
+   starttime. The lane id is `$LANE_ID` (in a tmux lane only through a canonical recipe's `-e` flags; in a zmx lane
+   `lane-run` exports it as the zmx session name) or the pane's tmux session looked up in `~/.lz/registry.json`; an unresolvable lane, a word outside the vocabulary or an
+   unwritable directory is a silent exit 0, and nothing is ever printed (a Claude prompt/session hook's stdout
+   becomes model context). `statusd` lists each container's `state/hooks/` once per cycle (`agent_sidecars`) and
+   `agent_state.read_sidecar_dict` drops a sidecar whose last event is older than `SIDECAR_MAX_AGE` (3600 s) or
+   whose agent pid is dead or recycled in the container's pid namespace. The sidecar has its own directory because
+   `lane-run` writes each zmx lane's `{phase, exit, at, pid}` record to `~/.lz/state/<zmx name>.json` and exports
+   that same name as `LANE_ID`: one shared file name would let a hook overwrite the record the zmx observer and the
+   container `lane ls` read (DEF-1436). A zmx lane's sidecar is therefore named by its zmx session, not by the
+   `<ws>--z-<name>` id statusd publishes, and does not reach that lane's `agent{}` yet — the zmx lane's `agent` key
+   stays lane-run's record (DEF-1437). A published sidecar adds `event` to `agent{}` and has `source: hook`. Hooks are
+   never installed implicitly: `lanes hooks install --agent claude|codex --container <name>` prints the merge and
+   writes only with `--write` (RUNBOOK "Installing agent hooks").
 5. A lane's `source` is the container's spelling of its `terminals.json`. Every host-side reader of that file
    maps it to the container's home volume first (`statusd.registry_source_paths`, deduplicated by that host path:
    one repository cloned in two containers is two files): the status daemon's hot-sync
    starts one `lanes sync` per edit (at most one per 10 s), `lanes doctor` reports "registry up to date" from the
-   same host-side mtimes, and promoting an unregistered session writes the binding through the volume.
+   same host-side mtimes (against the later of `generated_at` and `registry.synced`), and promoting an unregistered session writes the binding through the volume.
 
 `lanes cursor-sync` is a separate, explicit writer. Its default is a diff; `--write` takes backups and changes
 editor commands to `lane open <id>`. The original create recipe and exact tmux binding remain in the registry's
@@ -50,12 +71,14 @@ to the server's GLOBAL environment (`show-environment -g`), and every later sess
 unless its own `-e` overrides each key — a session created by a client carrying `LANE_ID=b` but no `-e` still got
 the server starter's `LANE_ID=a`, and one created with `-e LANE_ID=c` alone kept `a`'s `THROTTLE_TRACE`. Board
 sockets are shared (9 of the 10 bw-tools fixture lanes are on one socket), so `lane open` execs nothing — attach or
-recipe — that carries a lane identity, this lane's or one inherited from another lane's editor terminal (DEF-1422);
+recipe — that carries a lane identity, this lane's or one inherited from another lane's editor terminal (DEF-1478);
 a recipe run by it may start the server with an identity-free global environment only. An attach cannot change a
 running session's env, so a running lane gains its identity only when it is next CREATED by a recipe carrying `-e`.
 A legacy recipe without `-e` gives its lane no identity. `lanes cursor-sync --canonicalize` (dry-run unless
 `--write`) gives every tmux lane whose recorded `create` cannot create it — null, attach-only (`attach-session`
-without `new`), or naming an absolute `.sh`/`.py`/… script missing in the container — the canonical recipe with
+without `new`), naming the retired in-container `~/.config/coder-launch` path (these three are
+`lanes_lib.classify_recipe`'s classes, the ones `lanes doctor` warns about), or naming an absolute `.sh`/`.py`/…
+script missing in the container — the canonical recipe with
 `bash -l`; `--identity` gives a WORKING recipe of the plain shape `[exec] tmux -L <socket> new -ADs <session> [-c
 <dir>] <command…>` the same `-e` flags, re-quoting the command's words one for one so tmux receives the same argv
 (any expansion, glob, operator or other shape is left alone and stays identity-less). Both keep the old value as
@@ -69,7 +92,7 @@ stamped `lanes/<ws>/<id>` therefore puts its main session, every subagent and an
 into ONE fairness bucket where today each Claude session/agent is its own. `max_in_flight_per_trace` is configured
 and reported but no enforcement site exists in `src/` (MEASURED by search; `pressure.rs` documents fairness as "not a
 hard cap"). Whether a lane should be one bucket is an open decision for the plan owner before any live enablement
-(DEF-1423); this tree does not change the header shape. Unit-proven only (`test_lib_probe` `LaneOpenIdentity`,
+(DEF-1479); this tree does not change the header shape. Unit-proven only (`test_lib_probe` `LaneOpenIdentity`,
 `CursorSyncCanonicalize`, `CursorSyncIdentity`, stopping at the exec boundary); the disposable-lane
 `tests/cursor_lane.py` exercises the installed `/home/coder/.lz/bin/lane`, so it proves this only after `lanes
 install-container`.
@@ -80,6 +103,22 @@ install-container`.
 a lane sidebar, and one to three viewports. The mobile layout uses separate picker and full-width view tabs.
 Its hidden viewports do not attach at placeholder dimensions; they wait until a real client displays them.
 
+**Visual system:** one token table (`libexec/tokens.py`) is rendered into the sidebar's escapes, the Zellij themes,
+the phone CSS (and its xterm.js palette in `mobile.js`), the viewer's shell (`libexec/tokens.sh`), the optional Ghostty
+palette files and the docs table; `tokens.py --check` fails on drift in any of them. `docs/DESIGN.md` is the legend:
+glyphs with their ASCII twins, modes (`LANES_COLOR`, `LANES_THEME`, `LANES_GLYPHS`, `LANES_DIM`, `LANES_NOTIFY`), row
+anatomy, mockups and budgets; `tests/unit/test_docs.py` keeps the README legend complete against the glyph tables.
+
+Frames and bars take their colours from the `lanes-dark`/`lanes-light` themes generated by `libexec/tokens.py`; the
+compact bar is the only plugin; the mobile picker's sidebar pane has no layout name so its own title (attention
+counts) reaches the phone. `zellij/config.kdl` adds, after the generated token block, one `ui` block whose
+`pane_frames` set `rounded_corners false` and `hide_session_name true` (straight frames to match the sidebar's `─`
+rules, no session name in the bar) and `simplified_ui true` (no Private-Use-Area chevrons, so no Nerd Font is needed);
+`load_plugins` stays empty. The desktop sidebar keeps `pane size=36 borderless=true name="Lanes"` (Throttle Studio's view rule reads
+that name); the view pane is borderless at one viewport and framed at two or three. `tests/unit/test_layout.py` pins
+the generated layout and `test_keybinds.Chrome` the config; `zellij --config zellij/config.kdl setup --check` is the
+parse check (0.45.1).
+
 The tmux holder reaches the container's socket through `/proc/<init-pid>/root`, scrubs the viewer environment,
 and uses `tmux -N` so an attach cannot create a server accidentally. Guarded geometry and client identification
 keep the visible view and editor attachments coordinated. Zmx is a separately pinned alternative holder;
@@ -114,15 +153,41 @@ Explicit **New +** starts a detached tmux shell inside the workspace container o
 rechecking its session ID and creation time and refusing registered lanes; affected viewers become empty.
 The tmux close condition is checked inside the server, protecting a replacement created between observation
 and the action. `user-sessions/` stores display metadata; `status.json` and `resolve.dynamic/` are projections.
-Legacy Docker shells imported into `legacy-sessions/` are observed by PID/start identity. Closing rechecks the
-owner, preserves that root identity through the process-family scan, and requires a verified root pidfd before
-signaling the original process family. Failed verification keeps the recovery record. These older connections cannot be recreated; their
-metadata is local recovery state, never a recipe to start replacement jobs. See [state contracts](../../docs/master-datamodel.md).
+The pre-persistence Docker-shell tracker (`legacy-sessions/`, `legacy_sessions.py`, `lanes verify-legacy`) was
+retired by plan Task 19: statusd no longer reads that directory (a record still there is inert — kept on disk,
+never observed, never closed), and a `legacy` row from an older status.json is refused by close. See
+[state contracts](../../docs/master-datamodel.md).
 
 The `lane` command lives in `/home/coder/.lz/bin`. `open` attaches or creates using its saved recipe;
 `attach` never creates; `send`, `capture`, `ls` and `status` are explicit operations. Only `kill` ends a lane.
 These commands operate inside the container, independently of the Zellij viewer's lifetime.
 
+Every verb dispatches on the lane's holder. An id that `~/.lz/registry.json` holds as `holder: tmux` is driven
+through its exact socket and session, by a tmux client that carries no lane identity (`identity_free`, as `open`):
+`send` types the text literally and then Enter in one client (`send-keys -t =<session>: -l -- TEXT ; send-keys
+Enter`; `--no-enter` omits it), `capture` is `capture-pane -p -J -S -N|- -t =<session>:` (`--vt` adds `-e`) trimmed
+to the last N non-blank lines, `status` prints `{id, holder, ws, title, tmux, alive, agent}` from `has-session` and
+the lane's `lane-signal` hook sidecar (exit 1 when not alive), `attach` refuses to nest and never creates, and
+`kill` is `kill-session`. Two tmux 3.4 facts shape these argv (MEASURED on a disposable `lanes_test` server): a bare
+`-t =<session>` is refused by `send-keys` and `capture-pane` ("can't find pane") while `=<session>:` resolves, and
+tmux's argv parser ends a command at a trailing `;` of ANY argument, so `echo a;` would type `echo a` — `send`
+writes that last `;` as `\;`. Any other id is a zmx lane (a registry `holder: zmx` entry maps to its `zmx.name`) and
+keeps the zmx path; zmx `send` still writes the bytes as given, never an Enter of its own. `kill` now needs `--yes`
+on both holders and refuses while the lane's hook sidecar says `working` unless `--force`; the container sees only
+that sidecar (Claude session files and pane titles are judged on the host by `lanes-statusd`), so on a lane without
+installed hooks the refusal cannot fire (DEF-1439). `ls --json` stays the zmx-only listing Throttle Studio reads —
+its zmx holder takes EVERY row as a zmx lane, so tmux rows there would publish each tmux lane twice; `ls --all` adds
+the registry's tmux lanes with `alive` from one `list-sessions` per socket (and still lists them in a root without the zmx binary, where the default listing keeps failing as before). zmx rows gain `alive`, and `status` of a
+zmx lane gains `hook` (its sidecar); `agent` stays lane-run's phase record (DEF-1436).
+
+The bw-tools agent launchers (`.bw-tools/bin/claude`, `codex`) exec the agent binary (shell `exec` → `agent.py`
+`os.execvpe`), so a lane started through them shows the agent as the pane's foreground command. The operator's
+`~/.local/bin/eval-claude` runs Claude as a child instead (it appends `session_end` to its trace file after the
+exit), so a pane started through it keeps `bash` as its foreground command (DEF-1440); on the launcher path the end
+of a session is the `SessionEnd` hook's `lane-signal shell`, when hooks are installed. `.bw-tools/bin/claude` runs
+`$EVAL_CLAUDE_REAL_BIN` when it is set (the binary eval-claude would run) and skips it when it names a `.bw-tools`
+shim, so `EVAL_CLAUDE_REAL_BIN=<checkout>/.bw-tools/bin/claude eval-claude` composes the two without a loop.
+
 ## Desktop and uploads
 
 The client installer creates an SSH alias and dedicated terminal configuration, using the selected profile's
@@ -158,9 +223,11 @@ workspace and lane pickers. The bar reads the `MobileState` that Zellij sends to
 phone picker's `FocusPane`. It overlays the terminal, so the terminal's columns and rows do not change, and a
 click on the chip leaves the keyboard focus in the terminal. The tablet and desktop code and styles live in
 `web/browser.js` and `web/browser.css`, which `mobile.js` appends only in those two modes, so a phone never
-downloads them and the phone's `mobile.js`/`mobile.css` budget (spec §8) stays with the phone. `lanes web <device> [--desktop|--mobile]`
-prepares a browser view, enables the services through `install/enable-web.sh` and prints the private URL; without
-a flag a known device keeps its layout.
+downloads them: a phone fetches only the two files spec §8 budgets, MEASURED 2026-10-04 after the fan-in with
+plan Tasks 13/28 at 21 964 B of 22 174 B (`mobile.js`, whose explanations live in `web/README.md`, Code notes)
+and 18 945 B of 18 982 B (`mobile.css`). `lanes web <device> [--desktop|--mobile]` prepares a browser view,
+enables the services through `install/enable-web.sh` and prints the private URL; without a flag a known device
+keeps its layout.
 
 ## Installed files and services
 

package/payload/lanes/docs/DESIGN.md

@@ -1,9 +1,56 @@
 # Lanes design system
 
-The operator-facing legend for the Lanes cockpit. The tables below are generated from `libexec/tokens.py`
-(`python3 libexec/tokens.py --write`; `--check` fails on drift); the design of record is
-`docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md` at the repository root. Prose, modes, row anatomy and
-mockups land with the docs task of the cockpit v2 plan.
+The operator-facing legend for the Lanes cockpit: what every glyph, colour and switch means, how a sidebar row is
+laid out, and the budgets each surface is held to. The token and glyph tables below are generated from
+`libexec/tokens.py` (`python3 libexec/tokens.py --write`; `--check` fails on drift), the one source the sidebar's
+escapes, the Zellij themes, the phone CSS, the viewer's shell (`libexec/tokens.sh`), the optional Ghostty palette and
+this page are projected from. The design of record is
+[`docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md`](../../docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md)
+at the repository root; this page condenses it for daily use and never overrides it.
+
+## Principles
+
+1. **Attention before identity before telemetry:** column 2 says who needs you, columns 4–27 which lane, columns
+   29–34 how long and doing what.
+2. **Never colour alone:** every state has a glyph, a tone and an ASCII twin, and a fixed column; `LANES_COLOR=none`
+   leaves a fully readable sidebar.
+3. **One token set, many renderers:** `libexec/tokens.py` is the only place a colour or glyph is defined; every
+   other surface is a generated projection pinned by a drift test.
+4. **Theme-agnostic by construction:** the sidebar paints foreground only, learns dark/light once (OSC 11), falls
+   back to dark, and keeps lane identity colours in your own 16-colour palette.
+5. **Dim is a colour, not an attribute:** no SGR 2 in any frame; ink-dim in truecolor, bright black (`90`) in
+   16-colour mode.
+6. **Restraint:** one accent, for selection, viewing marks and the brand only; no emoji in rows, one upload line, a
+   one-line legend plus the `?` key sheet.
+7. **Every row says how long:** a 3-cell age on every row — the agent's `since`, else the last output.
+8. **Marks never lose to names:** viewer dots and viewport marks are reserved first; the name is clipped and ends
+   in `…`.
+9. **The cursor follows the lane, not the index:** re-sorts never move your focus in a list that scrolls.
+10. **Performance is a design property:** cached row bytes, one width walk per name, frames written only when dirty,
+    OSC 2/9/11 in the same write; budgets below.
+11. **Pinned bytes change deliberately:** a moved byte assertion is rewritten with a role name, never loosened.
+12. **The phone is a list, not a terminal:** the system-font shell carries identity, counts and actions.
+13. **Docs are the fourth surface:** this page, the README legend and the RUNBOOK column table are kept with the
+    code; the screenshots are user-supplied and never regenerated.
+
+## Modes
+
+Four switches pick the look; `devices/<device>.json` (written by `lanes attach DEVICE --ascii|--theme|--glyphs|--color`
+and by `lanes-window --ascii|--light|--dark`) wins over the environment and reaches a running sidebar within one tick.
+
+| Switch | Values | Default | Where read |
+|---|---|---|---|
+| `LANES_COLOR` | `truecolor` · `16` · `none` | `truecolor` when `COLORTERM` ∈ {`truecolor`, `24bit`} (config.kdl's `env` block forces it for every pane), else `16`; `NO_COLOR` set ⇒ `none` | `sidebar.py` at start **and on every tick**: `devices/<device>.json` is part of `reload()`'s mtime stamp (one `stat()`), its `color` key wins over env, and a changed file re-runs `resolve_modes()` → `sgr_table()`/`glyph_set()` and clears the row cache (`apply_look()`). Zellij panes inherit the *server's* environment at session creation, so an environment variable can never reach a running sidebar; the device file is the one channel that does |
+| `LANES_THEME` | `dark` · `light` · `auto` | `auto`: one OSC 11 query `\033]11;?\033\\` written at start; the reply (`\033]11;rgb:RRRR/GGGG/BBBB\033\\` or BEL-terminated, 8- or 16-bit components) is parsed in `handle()` and **swallowed** — it never cancels a filter or prompt; relative luminance < 0.5 ⇒ dark; no reply within 300 ms ⇒ dark; no re-ask | same; `devices/<device>.json` key `theme` (per tick, as above); `STATE/clients/<device>.theme` is written (`dark`/`light`, only on change) for `glow` |
+| `LANES_GLYPHS` | `unicode` · `ascii` · `emoji` | `unicode`; `ascii` automatically when none of `LC_ALL`/`LC_CTYPE`/`LANG` contains `UTF-8` | same; `devices/<device>.json` key `glyphs` (per tick, as above); `lanes attach DEVICE --ascii` / `--theme light` write them and every running sidebar of that device picks them up within one tick; `lanes-window --ascii`/`--light`/`--dark` pass them through. The sidebar publishes the resolved mode as `STATE/clients/<device>.glyphs` (`unicode`/`ascii`/`emoji` + newline, written on change or when absent) — the file `view.sh` reads with a builtin `read` for its status screens (§7) |
+| `LANES_DIM` | `90` · `2` | `90` | 16-colour mode only: `2` is the documented escape hatch for palettes whose colour 8 is near the background (classic Solarized dark) |
+| `LANES_NOTIFY` | `1` · `0` | `1` on desktop devices, `0` on mobile | OSC 9 emission (§4.9) |
+
+## Tokens and glyphs
+
+Every glyph table is `key -> (unicode, ascii, tone)`: agent glyphs are drawn only in column 2, stream glyphs only in
+column 33, marks only where the row anatomy puts them. `LANES_GLYPHS=ascii` swaps in the ASCII column, so an ASCII
+frame is seven-bit. The `ANSI-16` column is what `LANES_COLOR=16` emits; truecolor uses the Dark or Light value.
 
 <!-- BEGIN lanes tokens (generated by libexec/tokens.py --md; do not edit by hand) -->
 | Role | Dark | Light | ANSI-16 | CSS variable |
@@ -70,3 +117,134 @@ mockups land with the docs task of the cockpit v2 plan.
 | `↓` | U+2193 | `v` | tone-attention | economy `downgraded` |
 | `$` | U+0024 | `$` | ink-dim | economy `paid` |
 <!-- END lanes tokens -->
+
+## Row anatomy
+
+1-based columns; every lane row is exactly 36 cells by `cell_width`, and column 36 is never written.
+
+| col | content | tone |
+|---|---|---|
+| 1 | ▌ cursor or space | accent |
+| 2 | `AGENT_GLYPHS[agent.status]`; blank without `agent{}`; ink-dim when stale | its tone |
+| 3 | › viewing (not on the cursor row) · ² / ³ another viewport shows it · else space | accent |
+| 4–27 | name (24 cells) in `38;5;N` or ink, **bold when viewing**; viewer dots reserved first, name clipped to `24 − len(dots)` and ending in `…` when clipped; truncation detected by `len(clipped) < len(name)` (no second width walk) | identity colour |
+| 28 | `+` register control on an unregistered row that can be added to a workspace (closable and `R.eligible`; CHA-positioned at `cols − 8`; hit box `cols − 8 ≤ x < cols − 4`), else space — amended by Task 23 (§10, DEF-1428) | tone-done |
+| 29–31 | age, right-aligned: `NNs` < 60 s, `NNm` < 60 min, `NNh` < 24 h, `NNd` ≤ 99 d; blank when nothing is known; source `agent.since` else `activity` | ink-dim; attention inside Needs you |
+| 32 | space | |
+| 33 | `GLYPHS[state]` — full tone without an agent, ink-dim with one (▸ + ○ is the long-tool-call case and stays readable) | its tone |
+| 34 | tail: stale `?` > starving ⚠ > downgraded ↓ > paid `$` > space | ink-dim / attention |
+| 35 | × on closable rows, else space | urgent |
+| 36 | never written | |
+
+Budget: 3 + 24 + 1 + 3 + 1 + 1 + 1 + 1 + 1 = 36. The close hit box stays `x ≥ cols − 4` (a click at `cols − 2` closes,
+at `x = 5` opens — the pinned test keeps both). The `×` moved from `cols − 2` to `cols − 1`.
+
+## Mockups
+
+Desktop, a 35-lane workspace at 36 × 40 in `unicode` and truecolor (spec §4.8). Every line is exactly 36 cells; the
+real list scrolls where `⋮` is:
+
+```
+ Sakio                  ◆1 ◇2 ▸6 ✓1 
+── ◆ Needs you (3) ─────────────────
+▌◆ Compiler - Orchestrator  25m ○   
+ ◇›Runtime: supervisor      12m ○   
+ ◇ granite_games             4m ○ × 
+── ▸ Working (6) ───────────────────
+ ▸²Runtime - Orchestrator··  3m ●$  
+ ▸ Runtime: rendering       41s ●   
+ ▸ Runtime: contracts        2m ●   
+ ▸ Runtime: rules           18m ○$  
+ ▸ Runtime: events           9m ●   
+ ▸ Runtime: value-hunter-r…  1h ○↓  
+── ✓ Done (1) ──────────────────────
+ ✓ Sakio CLI                 7m ○   
+── Sakio (25) ──────────────────────
+   Granite                   2h ○   
+   Sakio rename              3d –   
+ _ Runtime: waits-effects   12h ○   
+ · Runtime: trace-replay     1d ○   
+   Runtime: source-assemb…·  5h !   
+   Runtime: conformance      2d ○   
+   Runtime: integration      6h ✗   
+   Runtime: wave-b-critic-…  9h ○   
+   Design review             3h ○?  
+   Docs                     11h ○   
+   Release                   4d –   
+   Bench                     2d ○   
+   Fixtures                  8h ○   
+   Harness                   1d ○   
+   Site                      5d –   
+   Infra                     9h ○   
+  ⋮ 9 more                          
+── Unregistered (5) ────────────────
+ +  New shell                       
+   granite_brand_migration   2h ○ × 
+   refinery-workblocks       6h ? × 
+ ↑ uploads · click, then drop  (U)  
+ $8.5k/16k 53% · spill 76% · free 3 
+────────────────────────────────────
+ ⏎ open · / find · x close · ? keys 
+```
+
+Row 3 is the cursor row (▌, no ›, bold name); row 4 is the viewing lane in this slot (›, bold); row 7 is shown in
+viewport b (²) with two viewers (··). The same frame in ASCII mode, first rows:
+
+```
+ Sakio                  !1 ?2 >6 v1 
+-- ! Needs you (3) -----------------
+|! Compiler - Orchestrator  25m o   
+ ?=Runtime: supervisor      12m o   
+ >2Runtime - Orchestrator..  3m *$  
+```
+
+Phone, the `render_mobile` picker at 48+ columns with three rows per lane (spec §4.10): row A is the viewing mark,
+the agent glyph and the name; row B the status word, age and harness; row C the agent's task.
+
+```
+ ◆1 need approval · ◇2 need you · ▸6 working    
+                                                
+── ◆ Needs you (3) ─────────────────────────────
+ ›◆ Compiler - Orchestrator                     
+     Needs approval · 25m · claude              
+     Fix buildctl bugs                          
+  ◇ Runtime: supervisor··                       
+     Needs you · 12m · codex                    
+     Verify fleet plan mapping                  
+  ◇ granite_games                            ×  
+     Needs you · 4m · claude                    
+     Port the brand migration                   
+── ▸ Working (6) ───────────────────────────────
+  ▸ Runtime: rendering                          
+     Working · 41s · claude                     
+     Renderer contracts wave B                  
+── Sakio (25) ──────────────────────────────────
+    Granite                                     
+     Quiet · 2h                                 
+                                                
+ Swipe to scroll · Tap to open                  
+```
+
+## Budgets
+
+Each budget is pinned by a test; a budget that is not met is an open defect row, never a raised number.
+
+| Budget | Pin |
+|---|---|
+| `render(35 lanes + 5 unregistered, 36×60)` median of 50 after 5 warm-ups ≤ 2.0 ms hard (CI, loose); design target ≤ 0.9× the same-run baseline cold (today 0.459 ms here, binary-safe read) and ≤ 0.10 ms warm (row cache) — MEASURED 2026-10-04 after Task 23: cold 0.64× met; warm 0.27–0.31 ms at load ~23–30, NOT met, DEF-1429 open; the target is not raised | `test_sidebar_budget.test_desktop_render_time_and_frame` (time) + bench numbers in the commit message of every task touching `render()` |
+| Frame ≤ 9216 B truecolor, ≤ 5632 B in `LANES_COLOR=16` at 36×60 (today 4330 B in both on the DEF-1417 fixture, 4297 B before it — `LANES_COLOR` is not read before Task 22; truecolor prefixes are the whole delta) | same test, `len(frame)` |
+| Exactly `viewports` `open()` calls of target files per render (12 over 6 renders at 2 viewports today); `subprocess.Popen`/`run` never called | `test_render_opens_only_target_files_and_never_forks` (open counter on the view dir, Popen/run patched to raise) |
+| Every emitted row ≤ 36 cells and column 36 blank on every row that is not made of the `rule` glyph alone. At Task 21 (before the one-row strip) the four upload-box rows are exempt as well — rows starting with `─ ┌ │ └`; Task 24 narrows the exemption to the rule when it removes the box | `test_no_row_exceeds_36_cells_and_column_36_is_blank` (ANSI- and OSC-stripped, binary-safe sink read, `cell_width`; and, because the strip hides positioned writes, every CHA/CUP column in the raw frame < 36 — today's maximum is 34; amendment 2026-10-04; and, because text positioned left of 36 can still run into it, every raw row walked cell by cell — `highest_cell` — writes no cell past 35, 36 on the exempt rows, over a fixture whose registrable ghosts carry both the `+` and the `×`; DEF-1417) with its detectors proven by `test_sidebar_budget_sabotage` |
+| Per tick ≤ 7 `stat()` at one viewport — registry, status, target, health, `flags/sockets-lost` (today's five), economy (Task 12), `devices/<device>.json` (Task 22) — plus one per extra viewport; zero timers added; the OSC 11 query is one write at start | `test_tick_stats_at_most_seven_files` (one viewport); `test_theme_query_is_written_once` |
+| Upload: select timeout stays 1.0 while uploading; `dirty` only on `.progress` mtime change | `test_upload_does_not_shorten_the_tick` (Task 24) |
+| `render_mobile(35, 48×60)` ≤ 2.0 ms hard, frame ≤ 6144 B; target ≤ 0.45 ms cold / ≤ 0.10 ms warm (today 0.352 ms / 1663 B) | `test_mobile_render_time_and_frame` |
+| `reload(force)` unchanged (0.14 ms at 35 / 0.39 ms at 183); fleet attention computed inside it from the loaded dict — NOT shown met: Task 24 measured 0.26–0.44 ms at 35 / 0.69–0.80 ms at 183 and Task 12 0.296 → 0.386 ms at 35 (load 30–62; the 0.14/0.39 figures are quiet-host figures), DEF-1483 open; the budget is not raised | bench in Task 24's and Task 12's commit messages; DEF-1483 |
+| Phone: exactly one `setInterval(`, zero `setTimeout(`, no `backdrop-filter`, a painted `box-shadow` only in `.lanes-sheet-panel` and `.zj-mobile-menu` (a `box-shadow: none` override, as on the security modal, is not paint work and is not counted); `fetch(` absent; mobile.css grows ≤ 2048 B over today's 16 934 B, mobile.js ≤ 3072 B over today's 19 102 B (measured 2026-10-03; the caps are baseline + allowance, quoted in the test); `index.html` keeps its 9 SRI-pinned upstream assets | `test_web.test_js_timers_unchanged`, `test_web.test_no_scroll_time_effects`, `test_web.test_bundle_growth`, `test_web.test_integrity_pins_untouched` |
+| Zellij: config.kdl grows by the theme + ui block only (~4 KB), `load_plugins {}` empty, no `rename-tab` from the sidebar | `test_keybinds.test_theme_block_and_plugin_free`, `test_tokens.test_generated_blocks_match_committed_files` |
+| Unit suite stays under 75 s wall (MEASURED 2026-10-04 after Task 21: 833 tests, 124–176 s at load ~30–60 — exceeded, DEF-1415 open; the budget is not raised); new pins are exact-string asserts, no sleeps; `tokens.py --check` ≤ 50 ms, contrast test ≤ 10 ms | observed in each task's run step |
+
+## Spec
+
+The full design system — token values and contrast, the glyph rules, header, sections, footer ladder, title and
+notification bytes, Zellij chrome, phone shell and client alignment, and the decisions log — is
+[`docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md`](../../docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md).