@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/docs/ARCHITECTURE.md

@@ -8,21 +8,117 @@ terminal. Installing or closing a view does not end a lane.
 
 1. The deployment's `catalog.json` orders workspaces and selects their manifests.
 2. Each manifest identifies container names and repository `.vscode/terminals.json` paths.
-3. `lanes sync` reads those files through the container's mounted home and emits the host registry,
-   exact socket/session resolve files, and the container's `.lz/registry.json` projection.
+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. 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.
 
+   Beside the six-word `state` (never changed by it), each live tmux lane, declared or unregistered, may carry
+   an additive `agent{}` key: `{harness, status, name, session_id?, pid?, since, source}` with `status` one of
+   `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 > 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
+   wins over the bell). A Codex title over a bare-shell foreground whose shell has no child process
+   (`pane_has_child`, read from `/proc/<pid>/task/*/children`) is `shell`: the harness ended and tmux kept its
+   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 (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
 `lanes` block. Automatic sync never commits or pushes those edits. `cursor-commit --push` is an opt-in workflow.
 
+Lane identity is an environment contract: `LANE_ID` (`<ws>--<slug>`), `LANE_WS` (`<ws>`), and the Throttle trace
+`lanes/<ws>/<id>` as `THROTTLE_TRACE` and as `ANTHROPIC_CUSTOM_HEADERS='x-throttle-trace: lanes/<ws>/<id>'` (Claude
+Code sends it on every request; the proxy's trace charset is `[A-Za-z0-9._-/]`, at most 256 characters, and a
+trace outside it is never emitted). A tmux lane gets it in exactly one way: the `-e` flags of
+`lanes_lib.canonical_recipe()` — `tmux -L <socket> new -ADs <session> -c <folder> -e … <cmd>` — which set the
+SESSION environment of that one lane on a real create (`-A` ignores them on an attach). Never through `tmux
+set-environment` and never through a client's environment, because of a tmux rule MEASURED on tmux 3.4 (the
+container's version) with a throwaway socket: the client that STARTS a socket's server hands its whole environment
+to the server's GLOBAL environment (`show-environment -g`), and every later session on that socket inherits it
+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-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`), 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
+`createPrevious`; a recipe whose paths cannot be checked (outside the home volume) is never counted as broken.
+zmx lanes get `LANE_ID` (only) from `lane-run`, unchanged.
+
+The trace is also a FAIRNESS key, not only an attribution key: the proxy uses `x-throttle-trace` when present and
+synthesizes `cc-session/<session>[/<agent>]` only when it is absent (`src/proxy.rs`, `synthesize_flow_key`), and the
+pool's parking queue is round-robin across trace keys at slot handoff (`src/pressure.rs`, `acquire_fair`). A lane
+stamped `lanes/<ws>/<id>` therefore puts its main session, every subagent and any workflow fan-out started in it
+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-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`.
+
 ## Views and panes
 
 `lanes attach DEVICE` creates or reattaches the device's Zellij view. Layouts have one tab per workspace,
 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;
@@ -39,20 +135,59 @@ manifest `discoveryRoots` extends those roots. A discovered assignment remains s
 a session no single board can claim is listed by EVERY owner of its socket rather than dropped, and ambiguity is
 logged rather than resolved by guess.
 
+**+** beside an unregistered tmux session opens **Add to workspace**. It offers workspaces using the session's
+container, with the current workspace first. Registration verifies the observed session ID/creation time and
+saves its existing lane ID, name and exact binding in the version-1 `registered-sessions.json` site file.
+It publishes the registered lane immediately without signaling viewers or processes. Sync, registration and
+explicit close share a bounded registry lock; close also consults saved registrations if projection publication
+failed. Stale observations cannot put a registered session back in Unregistered.
+
+These registrations have no create recipe and do not change repository terminal lists. Repository declarations
+win if they later declare the same binding. Unknown versions or malformed registration files refuse mutation;
+registrations for removed workspaces are retained on disk and ignored until the workspace returns. Removing a
+record and syncing unregisters it, including when a repository registry is temporarily invalid. Keep this site
+file in operator backups; deleting derived state does not delete registrations.
+
 Explicit **New +** starts a detached tmux shell inside the workspace container on its dedicated
 `lanes-shells-<workspace>` socket. Reopening only attaches. Explicit **×** closes an unregistered session after
 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
@@ -77,6 +212,23 @@ The phone shell uses the pinned client's window hooks for workspaces, panes, inp
 swipe, refresh or server message cannot summon the keyboard. Native taps on input fields still work.
 Safe-area insets and the visual viewport handle the Home indicator, rotation and keyboard.
 
+`web/mobile.js` chooses one of three modes once at load, by capability (`laneShellMode`), and records it on
+`<html data-lanes-shell>`. A **phone** (mobile user agent, or a touch screen at most 600 px wide or 500 px tall)
+gets the shell above unchanged. A **tablet** (any other touch screen) gets the same shell with its dock in the top
+bar and the workspace sheet as a left panel. It also asks the pinned client for its mobile UI, because iPad Safari
+reports a desktop user agent. That UI opens in single pane on every load; `web/browser.js` then sends the client's
+own full-view preference once, so a desktop layout's sidebar shows beside the lanes. A **desktop** browser (fine
+pointer, any width) keeps the plain client. Only a **Lanes** chip is added; it toggles an overlay bar with
+workspace and lane pickers. The bar reads the `MobileState` that Zellij sends to every web client and sends the
+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: 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
 
 `install/services.py` renders the service templates against the actual checkout and installed binary paths.

package/payload/lanes/docs/DESIGN.md

@@ -0,0 +1,250 @@
+# Lanes design system
+
+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 |
+|---|---|---|---|---|
+| surface | `#101318` | `#f3f5f2` | `—` | `--lanes-surface` |
+| surface-raised | `#191e25` | `#ffffff` | `—` | `--lanes-surface-raised` |
+| line | `#2c333d` | `#d5ded6` | `—` | `--lanes-line` |
+| accent-wash | `#1a2721` | `#e5f0e6` | `—` | `--lanes-accent-wash` |
+| accent-line | `#4b6955` | `#acc9b4` | `—` | `--lanes-accent-line` |
+| press | `#26332c` | `#d8e9db` | `—` | `--lanes-press` |
+| chip | `#ffffff0f` | `#edf3ec` | `—` | `--lanes-chip` |
+| ink | `#edf1f5` | `#17241b` | `39` | `--lanes-ink` |
+| ink-dim | `#9ca7b5` | `#56616d` | `90` | `--lanes-ink-dim` |
+| ink-faint | `#6b7683` | `#7f8a96` | `90` | `--lanes-ink-faint` |
+| accent | `#b4e3bf` | `#2f6b45` | `1;39` | `--lanes-accent` |
+| on-accent | `#101318` | `#ffffff` | `—` | `--lanes-on-accent` |
+| on-accent-urgent | `#7a1a12` | `#ffd3cc` | `—` | `--lanes-on-accent-urgent` |
+| tone-urgent | `#f28b7d` | `#b7322a` | `31` | `--lanes-tone-urgent` |
+| tone-attention | `#e5b84a` | `#8a5a00` | `33` | `--lanes-tone-attention` |
+| tone-working | `#7fb3f2` | `#2456a8` | `34` | `--lanes-tone-working` |
+| tone-done | `#6fd39a` | `#1b7142` | `32` | `--lanes-tone-done` |
+| scrim | `#000000a6` | `#1a222b80` | `—` | `--lanes-scrim` |
+| shadow | `0 -16px 80px #0007` | `0 -16px 80px #0003` | `—` | `--lanes-shadow` |
+
+| Glyph | Codepoint | ASCII | Tone | Meaning |
+|---|---|---|---|---|
+| `◆` | U+25C6 | `!` | tone-urgent | agent `needs_approval` |
+| `◇` | U+25C7 | `?` | tone-attention | agent `needs_input` |
+| `▸` | U+25B8 | `>` | tone-working | agent `working` |
+| `✓` | U+2713 | `v` | tone-done | agent `done` |
+| `✗` | U+2717 | `X` | tone-urgent | agent `errored` |
+| `_` | U+005F | `_` | ink-dim | agent `shell` |
+| `·` | U+00B7 | `.` | ink-dim | agent `idle` |
+| `●` | U+25CF | `*` | tone-done | stream `active` |
+| `○` | U+25CB | `o` | ink-dim | stream `quiet` |
+| `✗` | U+2717 | `x` | tone-urgent | stream `missing` |
+| `–` | U+2013 | `-` | ink-dim | stream `absent` |
+| `!` | U+0021 | `!` | tone-urgent | stream `dead` |
+| `·` | U+00B7 | `.` | ink-dim | stream `helper` |
+| `?` | U+003F | `?` | ink-dim | stream `unknown` |
+| `▌` | U+258C | `\|` | accent | mark `cursor` |
+| `›` | U+203A | `=` | accent | mark `viewing` |
+| `²` | U+00B2 | `2` | accent | mark `viewport-b` |
+| `³` | U+00B3 | `3` | accent | mark `viewport-c` |
+| `·` | U+00B7 | `.` | ink-dim | mark `viewer` |
+| `…` | U+2026 | `~` | ink | mark `truncation` |
+| `×` | U+00D7 | `x` | tone-urgent | mark `close` |
+| `+` | U+002B | `+` | tone-done | mark `new` |
+| `─` | U+2500 | `-` | ink-faint | mark `rule` |
+| `⋮` | U+22EE | `:` | ink-dim | mark `more` |
+| `⚠` | U+26A0 | `!` | tone-attention | mark `warning` |
+| `↑` | U+2191 | `^` | ink-dim | mark `upload` |
+| `↓` | U+2193 | `v` | tone-done | mark `armed` |
+| `⏎` | U+23CE | `Enter` | ink-dim | mark `enter` |
+| `█` | U+2588 | `_` | tone-working | mark `caret` |
+| `?` | U+003F | `?` | ink-dim | mark `stale` |
+| `›` | U+203A | `>` | ink | mark `lead` |
+| `·` | U+00B7 | `-` | ink-dim | mark `sep` |
+| `‘` | U+2018 | `'` | ink | mark `quote-open` |
+| `’` | U+2019 | `'` | ink | mark `quote-close` |
+| `✓` | U+2713 | `OK` | tone-done | mark `ok` |
+| `✗` | U+2717 | `X` | tone-urgent | mark `fail` |
+| `⚠` | U+26A0 | `!` | tone-attention | economy `starving` |
+| `↓` | 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).

package/payload/lanes/docs/INSTALL.md

@@ -155,6 +155,45 @@ Connect Tailscale on the phone, open the printed URL in Safari, paste only the t
 `sh install/enable-web.sh` starts only the loopback services and prints no token. The frontend and services
 run on the workspace host; a Mac does not need to stay awake for the phone to work.
 
+### Laptop and tablet browser
+
+The same private frontend serves every browser and chooses its controls once, when the page loads:
+
+- **Laptop or desktop** (mouse or trackpad): the plain Zellij web client, unchanged, plus a small **Lanes**
+  chip in the top-right corner. The chip opens a thin overlay bar with a workspace picker and a lane picker;
+  the terminal keeps its size and all of its keys.
+- **Tablet** (touch screen wider than 600 px): the phone controls arranged for the larger screen — Workspaces,
+  Lanes, Panes and **Type here** in the top bar, and the workspace list as a left panel. The terminal shows the
+  whole tab, so a desktop view's lane sidebar sits beside its lanes (**More → Single pane** shows one pane).
+- **Phone**: the phone shell described above.
+
+Give each browser its own view. On the server, one command prepares it, enables the loopback web services and
+prints its private URL:
+
+```sh
+lanes web ipad --desktop           # desktop sidebar layout (a new device's default); --mobile: phone lane pickers
+lanes web ipad --desktop --token   # the same, then a fresh login token in this terminal
+lanes web ipad --print-only        # shows the exact prepare call and URL; changes nothing
+```
+
+From an installed client, `sh install/enable-phone.sh --host lanes --desktop ipad` does the same over the
+selected SSH key; without a name, `--desktop` uses the device `browser`. The server needs this version of Lanes
+for `--desktop`. A device keeps the layout it was created with: `lanes web <device>` without a flag reuses it
+(so `lanes web phone` reuses the phone's view), and an explicit request for the other layout is refused; choose
+another device name. `lanes web` reads the node's Tailscale name. Tailscale Serve itself is set up once
+by `enable-phone.sh`, as described above.
+
+On a network with a captive portal (hotel, train or aircraft Wi-Fi), connect in this order:
+
+1. Complete the portal's sign-in page in the browser. Tailscale cannot connect until the portal lets traffic out.
+2. Connect Tailscale on the laptop or tablet and wait until it reports connected.
+3. Open the printed `https://<server>.<tailnet>.ts.net:8443/<device>` URL.
+4. Paste only the token value into the sign-in screen. Existing tokens remain valid; revoke one as shown above.
+
+There is no public fallback by design: views are reachable only through the tailnet. On a host without a
+Tailscale name, `lanes web` prints the loopback URL `http://127.0.0.1:8083/<device>` and says that it opens only
+on the host itself.
+
 ## 5. Updates, optional operations and removal
 
 A server installed with `npx @vibelord/lanes --server` runs from the staged tree `~/.local/share/lanes/pkg/<version>/`; updating is `npx @vibelord/lanes@latest --server`, and the previous versions a service may still run from are kept.