@vibelord/lanes 1.0.0 → 1.0.1

package/payload/lanes/client/lanes-launch

@@ -67,6 +67,8 @@ log() {
 # Run ssh as an async child so HUP/TERM (window closed, logout) end it immediately; a foreground child
 # would defer the trap until ssh returned. Keep the terminal on fd 9: dash gives async jobs /dev/null.
 child=
+dog=
+dog_ready=
 reader=
 holding=
 now=
@@ -76,6 +78,7 @@ stop() {
     trap - HUP TERM INT
     exec 2>/dev/null        # bash reports every child it sees die of a signal: noise in a terminal that stays open
     if [ -n "$child" ]; then kill -TERM "$child" 2>/dev/null || :; fi
+    cancel_watchdog
     if [ -n "$reader" ]; then kill -TERM "$reader" 2>/dev/null || :; fi
     end_helper
     log 'stopped: window closed, or a signal'
@@ -89,17 +92,56 @@ end_helper() {
 # INT too: in a plain terminal Ctrl-C is the way out, now that nothing else ends the client.
 trap stop HUP TERM INT
 # With $limit set, a watchdog ends a child that the server leaves hanging (macOS has no timeout(1)).
+cancel_watchdog() {
+    if [ -n "$dog" ]; then
+        # A very fast probe may finish before the forked shell has installed
+        # its trap. Wait for that handshake before sending cancellation.
+        while [ ! -s "$dog_ready" ] && kill -0 "$dog" 2>/dev/null; do sleep .01; done
+        kill -TERM "$dog" 2>/dev/null || :
+        wait "$dog" 2>/dev/null || :
+        dog=
+    fi
+    if [ -n "$dog_ready" ]; then rm -f "$dog_ready"; dog_ready=; fi
+}
 run() {
     exec 9<&0
     "$@" <&9 9<&- &
     child=$!
     exec 9<&-
     dog=
-    if [ -n "$limit" ]; then ( sleep "$limit"; kill -TERM "$child" ) >/dev/null 2>&1 & dog=$!; fi
+    dog_ready=
+    if [ -n "$limit" ]; then
+        if ! dog_ready=$(mktemp "${TMPDIR:-/tmp}/lanes-watchdog.XXXXXXXX"); then
+            kill -TERM "$child" 2>/dev/null || :
+            wait "$child" 2>/dev/null || :
+            child=; rc=1; return "$rc"
+        fi
+        (
+            # A foreground sleep can defer the shell's TERM handler, and
+            # killing only that shell leaves its sleep behind. An async
+            # timer lets wait handle cancellation and reap the owned child.
+            timer=; cancelled=
+            # The timer has no cleanup. KILL also covers its fork-to-exec
+            # window, before sleep has acquired its default signal handlers.
+            trap 'cancelled=1; [ -z "$timer" ] || kill -KILL "$timer" 2>/dev/null || :' HUP TERM INT
+            sleep "$limit" &
+            timer=$!
+            printf 'ready\n' > "$dog_ready"
+            # TERM can arrive between spawning the timer and assigning $!.
+            if [ -n "$cancelled" ]; then kill -KILL "$timer" 2>/dev/null || :; fi
+            wait "$timer" 2>/dev/null || :
+            if [ -n "$cancelled" ]; then
+                wait "$timer" 2>/dev/null || :
+            else
+                kill -TERM "$child" 2>/dev/null || :
+            fi
+        ) >/dev/null 2>&1 &
+        dog=$!
+    fi
     rc=0
     wait "$child" || rc=$?
     child=
-    if [ -n "$dog" ]; then kill -TERM "$dog" 2>/dev/null || :; wait "$dog" 2>/dev/null || :; fi
+    cancel_watchdog
     return "$rc"
 }
 # hold <seconds> [jitter]: wait, but Enter continues at once. No raw mode, so there is no terminal state to restore

package/payload/lanes/container/env.sh

@@ -8,6 +8,14 @@
 #   * tmux is NOT affected: it honours TMUX_TMPDIR only, so lane sockets stay in /tmp/tmux-<uid>.
 #   * Nothing is created here: no directory (or a read-only one) = no change. Opt out per shell or for good with
 #     LANES_TMP_OPTOUT=1 (any value, even empty, counts). LANES_TMP_DIR names another directory.
+#
+# Lane identity is NOT set here (this file is shared by every shell in the container). A tmux lane's shell gets it
+# ONLY from the `-e` flags of its create recipe (`lanes_lib.canonical_recipe`, `tmux new -e …`): LANE_ID
+# (<ws>--<slug>), LANE_WS (<ws>), THROTTLE_TRACE and ANTHROPIC_CUSTOM_HEADERS ('x-throttle-trace: lanes/<ws>/<id>';
+# trace charset [A-Za-z0-9._-/], at most 256). Never export them from a profile or a client: the client that starts
+# a shared board socket's tmux server copies its env into the server's GLOBAL env, which every later session there
+# without its own -e inherits (DEF-1422) — so `lane open` strips them. A running lane gains its identity only when it
+# is next created by a recipe carrying -e; a legacy recipe without -e gives none (`lanes cursor-sync --identity`).
 if [ -z "${LANES_TMP_OPTOUT+set}" ] && [ -d "${LANES_TMP_DIR:-/home/coder/.tmp}" ] \
         && [ -w "${LANES_TMP_DIR:-/home/coder/.tmp}" ] && [ -x "${LANES_TMP_DIR:-/home/coder/.tmp}" ]; then
     TMPDIR=${LANES_TMP_DIR:-/home/coder/.tmp}

package/payload/lanes/container/lane

@@ -148,8 +148,22 @@ def registry_entry(lane):
     return lanes[lane]
 
 
+IDENTITY = ('LANE_ID', 'LANE_WS', 'THROTTLE_TRACE')   # + a lanes/ ANTHROPIC_CUSTOM_HEADERS (identity_free)
+
+
+def identity_free(environ, drop=('TMUX',)):
+    """`environ` without any lane identity (lanes/docs/ARCHITECTURE.md "Lane identity"). Whatever tmux client STARTS
+    a socket's server hands its whole environment to the server's GLOBAL environment, and every later session on
+    that socket created without its own `-e` inherits it (MEASURED, tmux 3.4: DEF-1422). Board sockets are shared by
+    many lanes, so a lane identity in the env of anything that may start one would be stamped on unrelated lanes.
+    Identity therefore reaches a lane's shell ONLY through `-e` in its create recipe (lanes_lib.canonical_recipe).
+    An operator's own ANTHROPIC_CUSTOM_HEADERS that is not a lane trace is theirs and stays."""
+    return {k: v for k, v in environ.items() if k not in drop and k not in IDENTITY
+            and not (k == 'ANTHROPIC_CUSTOM_HEADERS' and v.startswith('x-throttle-trace: lanes/'))}
+
+
 def tmux_cmd(socket, *args):
-    env = {k: v for k, v in os.environ.items() if k != 'TMUX'}
+    env = identity_free(os.environ)
     return subprocess.run(['tmux', '-L', socket, *args], capture_output=True, text=True, timeout=15, env=env)
 
 
@@ -159,7 +173,10 @@ def cmd_open(args):
     entry = registry_entry(args[0])
     if os.environ.get('TMUX') and '--force' not in args:
         sys.exit(f"lane open: already inside tmux — refusing to nest. The lane is: {json.dumps(entry.get('tmux') or entry.get('zmx'))}")
-    env = {k: v for k, v in os.environ.items() if k not in ('TMUX', 'TMUX_PANE')}
+    # Nothing `lane open` execs carries a lane identity — neither this lane's nor one inherited from ANOTHER lane (an
+    # editor terminal started inside a lane): the recipe may be the first client on a shared board socket and would
+    # hand it to every later session there (DEF-1422). The canonical recipe's own `-e` flags give the identity.
+    env = identity_free(os.environ, drop=('TMUX', 'TMUX_PANE'))
     if entry.get('holder') == 'zmx':
         name = entry['zmx']['name']
         if alive(name):

package/payload/lanes/docs/ARCHITECTURE.md

@@ -8,15 +8,72 @@ 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,
+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.
 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 (planned, not read yet) > 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.
+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.
+
 `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-1422);
+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
+`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-1423); 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,
@@ -39,6 +96,19 @@ 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.
@@ -77,6 +147,21 @@ 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 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.
+
 ## 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,72 @@
+# 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.
+
+<!-- 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 -->

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.

package/payload/lanes/docs/RUNBOOK.md

@@ -30,6 +30,16 @@ other ghost: the grammar governs what may be DECLARED, never what may be SEEN. (
 on such a row saying why it cannot be declared; no surface draws it yet.) A session on a socket SEVERAL boards
 declare, whose name claims no board and whose directory is under nobody's roots, is listed by EVERY owner of
 that socket rather than dropped — one id, one row, several sidebars.
+Agent glyphs (column 2, beside the cursor bar; from `status.json`'s additive `agent{}`, never from `state`): `◆`
+approval prompt blocking · `✗` errored · `◇` turn finished, waiting for your prompt · `▸` working · `✓` done, until
+you open the lane from this device (`clients/<device>.seen.json`) · `_` harness ended into a shell · `·` harness up,
+no turn · blank = a plain shell. With an agent the stream glyph after the age is dimmed (`▸` + `○` is a long tool
+call, not a stuck lane); a stale lane's agent glyph is dimmed too. Sections: **Needs you** (◆, ✗, ◇ — oldest first),
+**Working** (oldest first), **Done** (newest first), then the workspace's other lanes under its own header — only
+when an agent section exists; a filter flattens them. Header: `◆1 ◇2 ▸6 ✓1` (zeros omitted; `N lanes` without
+agents; dimmed while the footer warns that status is old). Every row ends with an age: the agent's `since`, else
+the last output (`45s`, ` 3m`, ` 2h`, ` 4d`). `x` / `×` asks ` › close ‘name’? y/n` first; `y` closes, any other
+key cancels. Design of record: `docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md` §3–§4.
 A `·` after a lane's name (up to three) = other sessions VIEW that lane: any session GROUPED onto it, a Throttle
 Studio browser attach (`view-<studio>-<ch>`) included — counted in the lane's `attached`/`viewers` in `status.json`,
 never listed as unregistered (`statusd.viewer_of`; a ghost carries its viewers too, so a browser on an undeclared
@@ -52,6 +62,19 @@ process running under the survivor, which returns next cycle as a new `👻` (DE
 have no close control. `+` creates a shell from the keyboard. New and Close are explicit user actions; discovery,
 reattachment, and reconnects never create or close a session.
 
+To keep an unregistered tmux session in a workspace's regular lane list, click/tap **+** beside it (or select it
+and press `a`), then choose a workspace. Only workspaces using its container are offered. **Cancel** or Esc leaves
+it unregistered. This preserves its name, running programs, scrollback and active views. It appears immediately
+and survives sync and reconnects. Registered lanes have no close control. Legacy Docker shells cannot be registered.
+
+From the server CLI, use `lanes ls --unregistered` to find the ID, then
+`lanes register <lane-id> [workspace-id]`; omitting the workspace keeps the current assignment.
+The site's version-1 `registered-sessions.json` is durable configuration: back it up with the catalog.
+To undo registration, remove its record from `sessions` and run `lanes sync`; the terminal keeps running.
+If publication fails after saving, `lanes sync` finishes it. Invalid/newer file versions are refused without
+overwriting the file. These registrations have no restart recipe: an ended session stays absent until the operator
+starts it. Add a repository terminal declaration when editor integration and a saved create recipe are wanted.
+
 Old plain Docker shells recovered during the transition are labelled **Legacy**. They remain tracked,
 including their existing running jobs. A still-connected viewer continues working; after leaving it, the old
 Docker connection has no normal reattach operation. Selecting that entry explains its status, and × ends the
@@ -70,6 +93,15 @@ systemctl --user status lanes-statusd lanes-sync.timer lanes-ensure.timer lanes-
 - **A view looks wrong / stuck:** `lanes rebuild mac`. Views are disposable; agents are untouched; the client reconnects.
 - **A lane was added/renamed/removed in a repo's `.vscode/terminals.json`:** nothing to do. `lanes-sync.timer`
   re-reads registries every 2 minutes and the sidebar follows. The zellij layout is never edited live.
+- **Give a registered lane a different display name:** sidebar `R`, or `lanes rename <lane-id> <name>`. It writes
+  `repositories[i].displayNames` in the board's `workspaces.<board>.json` (a `.bak-<UTC>` copy is kept on the first
+  write) and syncs; the lane id, its resolve file and Cursor's `lane open <id>` stay the same. Renaming back to the
+  terminal's own title removes the override. A session added through Add to workspace / `lanes register` is renamed
+  in its `registered-sessions.json` record instead (same id, same binding); an unregistered session in its
+  `user-sessions/<id>.json`.
+- **Promote (`P`) vs Add to workspace (`a`):** `P` declares an UNREGISTERED tmux session in the board's single
+  repository `terminals.json` (it then gets a repository lane id, `<ws>--<slug>`); `a` keeps the session's id. `P` is
+  refused on any lane that is already registered — a repository lane or an added session.
 - **A newer layout added a tab (e.g. `Throttle`):** `lanes upgrade-session` adds it to the live sessions without a
   rebuild and leaves you on the tab you were on.
 - **A new workspace:** add it to `~/.config/lanes/workspaces/catalog.json` + a manifest, `lanes sync`, then
@@ -236,7 +268,8 @@ Cursor terminals need a reopen. Never `rm -rf /tmp/*` in a workspace container;
 ## Cursor / VS Code terminals = the same lanes
 
 Cursor uses the Terminals Manager extension, which opens what `<folder>/.vscode/terminals.json` lists. Those files
-stay the source of truth for WHICH lanes a board has (the lanes registry is built from them). `lanes cursor-sync`
+stay the source of truth for editor-defined lanes; sidebar registrations supplement the Lanes view without
+changing the editor's terminal list. `lanes cursor-sync`
 only normalizes HOW a terminal reaches its lane:
 
 - every `command` becomes `exec /home/coder/.lz/bin/lane open <lane-id>` — attach; if the lane is missing, run its
@@ -247,6 +280,16 @@ only normalizes HOW a terminal reaches its lane:
   `lanes cursor-sync <ws> --write` applies (backup under `~/.local/state/lanes/cursor-sync-backups/`). The repo then
   shows an ordinary git diff to review and commit. Boards that keep their registry outside a repository
   are additionally projected into the file Cursor reads (`"cursor"` in `workspaces/*.json`).
+- `lanes cursor-sync <ws> --canonicalize` (dry run; add `--write` to apply) replaces every tmux lane's recorded
+  create recipe that cannot create the lane — none, attach-only, or a script missing in the container — with the
+  canonical `tmux new -ADs … -e LANE_ID=… -e LANE_WS=… bash -l` recipe (old value kept as `createPrevious`).
+  `--identity` adds the same `-e` flags to a working plain `tmux -L S new -ADs N [-c D] CMD` recipe, keeping CMD's
+  argv; any other working recipe is left alone and its lane carries no identity. These `-e` flags are the ONLY way a
+  tmux lane gets `LANE_ID`/the trace: `lane open` deliberately exports none (DEF-1422 — the first client on a shared
+  board socket would otherwise hand its identity to every later lane there). Both change the file only: a RUNNING
+  lane keeps its environment and gains the identity when it is next created. Before enabling it on a live board,
+  read DEF-1423: a `lanes/<ws>/<id>` trace makes the whole lane — main session, subagents, fan-out — one proxy
+  fairness bucket.
 - Size policy "the lanes view wins": lanes-view tmux clients run with `TERM=xterm-lanesview` (a user-level terminfo
   alias of xterm-256color). While such a client shows a lane, every other client of that lane (Cursor terminals,
   ad-hoc attaches) is in tmux `ignore-size`; `lanes-statusd` reconciles every few seconds and gives editors the size
@@ -365,6 +408,23 @@ a real client before attaching; visible views accept 20 columns / 4 rows for the
 Revoke a named token with `~/.local/share/lanes/bin/zellij-0.45.1 web --revoke-token NAME`.
 An SSH-only phone client can run `lanes attach phone --mobile` instead.
 
+Laptop and tablet browsers: see the [installation guide](INSTALL.md#laptop-and-tablet-browser). Troubleshooting:
+
+- **A tablet landed on the lane-picker layout** (the device was made for a phone, for example by
+  `enable-phone.sh`'s default): give the tablet its own desktop-layout view with `lanes web <device> --desktop`
+  under a new device name. The old view stays as it is; a running view is never rebuilt into the other layout,
+  and an explicit `--desktop` against it is refused instead. Without a flag, `lanes web <device>` reuses
+  whatever layout that device already has. A tablet shows the whole tab (sidebar beside the lanes): the pinned
+  client opens its mobile UI in single pane on every load, and `web/browser.js` asks once per load for the full
+  view with the client's own preference. **More → Single pane** still switches to one pane for that load.
+- **A laptop shows no Lanes chip**: the chip appears after sign-in, when the first workspace state arrives. A
+  reload after an upgrade picks up the new `mobile.js` and `browser.js` (both served with `no-cache`; `mobile.js`
+  appends `browser.js`/`browser.css` only on a tablet or desktop, so a phone's network panel never lists them).
+  The chip keeps the keyboard focus in the terminal; if typing stops after using a picker, Escape in the bar or a
+  click in the terminal returns it.
+- **`lanes web` printed a `127.0.0.1` URL**: the host has no Tailscale name. Connect Tailscale on the host;
+  there is no public fallback.
+
 ## Safety rules baked into the code (do not remove)
 
 - tmux is always called with `-N` (`attach-session`, `new-session` and `start-server` on a missing socket start
@@ -383,3 +443,36 @@ An SSH-only phone client can run `lanes attach phone --mobile` instead.
   `tests/smoke_real.py` (read-only, real lanes), `tests/latency.py` (from a client). All use disposable lanes except
   the explicitly read-only smoke test; every one refuses to start on a busy host (exit 75) and removes its lanes and
   sessions when it is killed with SIGTERM / SIGHUP.
+
+## Workspace catalog propagation
+
+Register and rename workspaces in the host site catalog. Device-local copies are
+not a second authority. `lanes sync` publishes the registry and reconciles all
+known live devices; `lanes upgrade-session mac anarchy phone` performs only the
+view reconciliation. Device metadata chooses desktop or mobile layout. Missing
+sessions are recreated by `lanes ensure` with that same catalog.
+For an existing session with no attached client, additions wait until a client
+connects and the next ensure tick. Zellij 0.45.1 otherwise acknowledges a new
+background tab without spawning its panes. Names and ordering can still sync.
+
+Reconciliation identifies managed tabs by the workspace IDs in their launched
+sidebar/view commands, then adds or renames tabs and orders them using Zellij's
+stable tab IDs. It never closes tabs, restarts agents or changes client focus.
+An unknown session/pane response or an ambiguous identity refuses changes for that
+device and reports an error. Another device can still be updated. An unmanaged
+name collision is preserved for explicit inspection; it is never adopted by title.
+Per-device file locks serialize a sync with the ensure timer.
+SSH split tabs match the host, absolute helper and declared pane ID together.
+Different pane IDs may share one helper; overlapping endpoint identities refuse
+before tab mutations and require an unambiguous catalog assignment.
+
+For a connection wait, the Syncing screen owns and drains terminal input until
+the attach client produces output. Terminal modes and sizes are restored when a
+viewer ends; TERM/HUP stop only that attach process group. The persistent lane
+continues independently. Connection diagnostics remain in the view's `.err` file.
+Existing views pick up the connection helper on their next attach; restart only
+the relevant view panes when activating a changed supervisor, never the lane.
+
+Catalog fields are additive to site schema 1. Back up the catalog and running
+checkout before updating the server. Restore those files to roll back; do not
+rebuild device sessions as a rollback shortcut. Previously added tabs remain open.

package/payload/lanes/holders/ssh.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# Reconnecting viewer for an existing persistent session on another host.
+# The remote command is an attach-only helper: disconnecting never stops its agent.
+set -u
+host=${1:-} command=${2:-} pane=${3:-}
+# View sessions can be created by a clean server environment with no TERM.  ssh
+# then starts the remote tmux client without a terminal type and the helper
+# exits immediately with “open terminal failed”.  Keep the viewer attach-only,
+# but give the remote terminal a conservative type when the caller omitted it.
+export TERM=${TERM:-xterm-256color}
+case "$host" in ''|-*|*@*@*|*[!A-Za-z0-9_.@-]*) echo 'invalid SSH host' >&2; exit 64 ;; esac
+case "$command" in /*) ;; *) echo 'SSH command must be absolute' >&2; exit 64 ;; esac
+case "$command" in *[!A-Za-z0-9_./-]*|*/../*|*/..) echo 'invalid SSH command' >&2; exit 64 ;; esac
+case "$pane" in ''|-*|*[!A-Za-z0-9_.-]*) echo 'invalid pane' >&2; exit 64 ;; esac
+repo=$(cd "$(dirname "$0")/.." && pwd)
+exec python3 "$repo/libexec/connection.py" --title "$pane on $host" --retry -- \
+    ssh -tt -o BatchMode=yes -o ConnectTimeout=8 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 \
+    "$host" "exec $command $pane"

package/payload/lanes/install/enable-phone.sh

@@ -2,20 +2,27 @@
 # Key-authenticated client entry point and local server setup. Tokens stay in the caller's terminal.
 set -eu
 repo=$(cd "$(dirname "$0")/.." && pwd)
-host= device=phone local=0 named=0
+host= device= local=0 named=0 layout=
 while [ "$#" -gt 0 ]; do
     case "$1" in
         --host) host=${2:?--host SSH_ALIAS}; shift ;;
         --local) local=1 ;;
+        --desktop|--mobile)
+            [ -z "$layout" ] || [ "$layout" = "$1" ] || { echo '--desktop and --mobile are exclusive' >&2; exit 2; }
+            layout=$1 ;;
         -h|--help)
-            echo 'usage: enable-phone.sh [--host SSH_ALIAS | --local] [device]'
+            echo 'usage: enable-phone.sh [--host SSH_ALIAS | --local] [--desktop|--mobile] [device]'
             echo 'Client: --host lanes uses the SSH key from ./install.sh. Server: --local.'
+            echo 'Mobile (phone lane pickers, device phone) is the default; --desktop serves the desktop sidebar layout'
+            echo '(device browser) for a laptop or tablet browser. A running view of the other layout is refused.'
             exit 0 ;;
         -*) echo "unknown option: $1" >&2; exit 2 ;;
         *) [ "$named" = 0 ] || { echo 'only one device name is allowed' >&2; exit 2; }; device=$1; named=1 ;;
     esac
     shift
 done
+# Mobile stays the default (and sends no flag to an older server); --desktop names its own default device.
+if [ "$layout" = --desktop ]; then device=${device:-browser} suffix=' --desktop'; else layout=--mobile device=${device:-phone} suffix=; fi
 case "$device" in ''|-*|*[!A-Za-z0-9_.-]*) echo 'invalid device name' >&2; exit 2 ;; esac
 case "$host" in -*|*[!A-Za-z0-9_.@:-]*) echo 'invalid SSH host' >&2; exit 2 ;; esac
 [ "$local" = 0 ] || [ -z "$host" ] || { echo '--local and --host are mutually exclusive' >&2; exit 2; }
@@ -23,10 +30,10 @@ if [ "$local" = 0 ] && [ "$(uname -s)" = Darwin ] && [ -z "$host" ]; then host=l
 [ -t 0 ] && [ -t 1 ] || { echo 'Run enable-phone.sh in your own terminal; it displays a private login token.' >&2; exit 64; }
 if [ -n "$host" ]; then
     exec ssh -t -o BatchMode=yes -o PreferredAuthentications=publickey -o ForwardAgent=no "$host" \
-        "exec sh \"\$HOME/.local/share/lanes/current/install/enable-phone.sh\" --local '$device'"
+        "exec sh \"\$HOME/.local/share/lanes/current/install/enable-phone.sh\" --local '$device'$suffix"
 fi
 command -v tailscale >/dev/null 2>&1 || { echo 'Install and connect Tailscale on the server first.' >&2; exit 1; }
-sh "$repo/install/enable-web.sh" "$device"
+sh "$repo/install/enable-web.sh" "$device" "$layout"
 if ! tailscale serve --bg --https=8443 http://127.0.0.1:8083; then
     echo 'The server admin must allow this account to manage Tailscale Serve:' >&2
     printf '  sudo tailscale set --operator=%s\n' "$(id -un)" >&2
@@ -35,9 +42,11 @@ if ! tailscale serve --bg --https=8443 http://127.0.0.1:8083; then
 fi
 dns=$(tailscale status --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["Self"]["DNSName"].rstrip("."))')
 [ -n "$dns" ] || { echo 'This node needs Tailscale MagicDNS and HTTPS enabled.' >&2; exit 1; }
-printf '\nOn your phone, connect Tailscale and open:\n\n  https://%s:8443/%s\n\n' "$dns" "$device"
+if [ -n "$suffix" ]; then where='In a browser on your laptop or tablet'; else where='On your phone'; fi
+printf '\n%s, connect Tailscale and open:\n\n  https://%s:8443/%s\n\n' "$where" "$dns" "$device"
 printf 'The last line is NAME: TOKEN. Paste only TOKEN into the sign-in screen.\n'
-printf 'In Safari, Share > Add to Home Screen installs the app.\n\n'
+[ -n "$suffix" ] || printf 'In Safari, Share > Add to Home Screen installs the app.\n'
+printf '\n'
 # Zellij 0.45.1 requires --create-token by itself; --token-name cannot accompany it.
 exec "${LANES_SHARE:-$HOME/.local/share/lanes}/bin/zellij-0.45.1" \
     --config-dir "$repo/zellij" --config "$repo/zellij/config.kdl" web --create-token

package/payload/lanes/install/enable-web.sh

@@ -1,16 +1,29 @@
 #!/bin/sh
 # Enable loopback web services as the installed workspace user. Does not print a token.
+# The view is mobile (the phone's lane pickers, default device `phone`) unless --desktop asks for the desktop
+# sidebar layout (default device `browser`); a running view of the other layout is refused, never rebuilt.
 set -eu
 repo=$(cd "$(dirname "$0")/.." && pwd)
-device=${1:-phone}
-[ "$#" -le 1 ] || { echo 'usage: enable-web.sh [device]' >&2; exit 2; }
-case "$device" in ''|-*|*[!A-Za-z0-9_.-]*) echo 'invalid device name' >&2; exit 2 ;; esac
+usage='usage: enable-web.sh [device] [--desktop|--mobile]'
+device= layout=
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --desktop|--mobile)
+            [ -z "$layout" ] || [ "$layout" = "$1" ] || { echo '--desktop and --mobile are exclusive' >&2; exit 2; }
+            layout=$1 ;;
+        -*) echo "$usage" >&2; exit 2 ;;
+        *) [ -z "$device" ] || { echo "$usage" >&2; exit 2; }; device=$1 ;;
+    esac
+    shift
+done
+if [ "$layout" = --desktop ]; then device=${device:-browser} suffix=' --desktop'; else layout=--mobile device=${device:-phone} suffix=; fi
+case "$device" in -*|*[!A-Za-z0-9_.-]*) echo 'invalid device name' >&2; exit 2 ;; esac
 command -v caddy >/dev/null 2>&1 || { echo 'Install Caddy first (see docs/INSTALL.md).' >&2; exit 1; }
 export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
-"$repo/bin/lanes" prepare "$device" --mobile
+"$repo/bin/lanes" prepare "$device" "$layout"
 python3 "$repo/install/services.py"
 systemctl --user daemon-reload
 systemctl --user enable --now lanes-web.service lanes-mobile.service
 systemctl --user is-active --quiet lanes-web.service lanes-mobile.service
-printf '\nPhone frontend: 127.0.0.1:8083; Zellij: 127.0.0.1:8082 (loopback only).\n'
-printf 'For private HTTPS and a login token, run in your terminal:\n  sh "%s/install/enable-phone.sh" --local %s\n' "$repo" "$device"
+printf '\nWeb frontend: 127.0.0.1:8083; Zellij: 127.0.0.1:8082 (loopback only).\n'
+printf 'For private HTTPS and a login token, run in your terminal:\n  sh "%s/install/enable-phone.sh" --local %s%s\n' "$repo" "$device" "$suffix"