@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/docs/RUNBOOK.md

@@ -14,22 +14,63 @@ original names and measurements; substitute your account, containers and paths i
 | Wide view: 2 or 3 viewports side by side per workspace | `lanes-window w2` / `w3` (anarchy: `Super+Shift+Alt+L`). In the sidebar `Enter` opens in the first viewport, `2` / `3` open the lane under the cursor in the second / third; `²` `³` mark what they show |
 | One lane, no multiplexer, native Ghostty scrollback | `lanes-launch lane <lane-id>` (ids: `lanes-launch ls`) |
 | Switch workspace | `Ctrl-Alt-←/→` (zellij tabs) |
-| Next / previous lane | `Ctrl-Alt-↓` / `Ctrl-Alt-↑` (works from inside the lane, in a wide view from every viewport; they move the FIRST viewport and focus ends there) |
+| Next / previous lane | `Ctrl-Alt-↓` / `Ctrl-Alt-↑` (works from inside the lane: `lanes next\|prev --focused` in a floating pane that closes at once points the FOCUSED viewport — the first one when the sidebar has the focus — at the next / previous lane of its workspace in registry order, wrapping; nothing is typed and the focus stays where it was; on a tab without a workspace, e.g. Host, it does nothing). In the sidebar `J` / `K` still step through the list as it is drawn |
+| Lock the view | `Ctrl-Alt-g` locks (every key reaches the lane; the mode ribbon shows LOCKED in on-accent-urgent) and unlocks. `Ctrl-g` is never bound: it always reaches the lane |
 | Find a lane by name | `Ctrl-Alt-/`, type a few letters, `Enter` |
 | Browse the sidebar | click it (or `Ctrl-Alt-p` then `←`), `↑/↓` or `j/k`, `Enter`; selecting a lane focuses it again |
+| Go to the next lane that needs you | `Tab` in the sidebar opens the next lane in **Needs you** (`Shift-Tab` the previous), cycling from the lane this pane shows — or from the cursor lane when the shown one does not need you; ` nothing needs you` when the section is empty |
 | Scroll a lane | mouse wheel / tmux copy-mode as before (history lives in the lane, not in the viewer) |
 | Throttle monitor | its own full-size tab, `Throttle` (next to `Host`); it starts when you first open the tab and restarts itself if it exits. It is no longer an entry in every board's sidebar. |
 | Detach | `Ctrl-Alt-o` then `d` — or just close the window. Nothing on the server stops. |
 
-Sidebar glyphs: `●` output in the last 20 s · `○` quiet · `–` absent (no such session right now, e.g. a finished
-orchestrator turn) · `!` pane dead · `✖` container down · `?` / a dimmed glyph = not observed right now, last known
-state shown (see "When the host is overloaded") · `👻 unregistered` = an observed tmux session associated with this
-workspace but absent from its registry — nothing alive is ever hidden, and a session whose NAME could not be
-declared (parentheses, `/` and `,` are outside the lane grammar) is listed, opened and closed exactly like any
-other ghost: the grammar governs what may be DECLARED, never what may be SEEN. (`status.json` carries a `note`
-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.
+Sidebar glyphs: see the legend in [`docs/DESIGN.md`](DESIGN.md) (agent column `◆ ◇ ▸ ✓ ✗ _ ·`, terminal column
+`● ○ – ! ✗ · ?`, every glyph with its ASCII twin, the token table and the modes); a dimmed glyph with `?` in column 34
+means not observed right now, last known state shown (see "When the host is overloaded"). By row column (spec §4.2;
+every row is 36 cells and column 36 is never written):
+
+| Column | Shows |
+| --- | --- |
+| 1 | `▌` the cursor (no underline) |
+| 2 | the agent, 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; dimmed when the lane is stale |
+| 3 | `›` the lane this pane shows — never on the cursor row, where the bold name says it · `²` / `³` shown in pane 2 / 3 of a wide view |
+| 4–27 | the name in its identity colour, bold while this pane shows it; up to three `·` (other sessions view it) are reserved first, and a longer name ends in `…` |
+| 28 | `+` on an unregistered tmux session that can be added to a workspace (click it, or `a`) |
+| 29–31 | the age: the agent's `since`, else the last output — `45s`, ` 3m`, ` 2h`, ` 4d` (at most `99d`); blank when nothing is known; amber inside **Needs you** |
+| 33 | the stream: `●` output in the last 20 s · `○` quiet · `–` absent (no such session right now, e.g. a finished orchestrator turn) · `!` pane dead · `✗` container down · `·` helper · `?` never observed; dimmed when an agent glyph sits in column 2 (`▸` + `○` is a long tool call, not a stuck lane) or when stale |
+| 34 | one tail cell by priority: `?` not observed right now, last known state shown (see "When the host is overloaded") > `⚠` starving (the pane is `active` but the proxy saw no request from the lane for over 600 s, or a 429 in its recent-request ring) > `↓` downgraded in the last 5 min > `$` more than half its recent requests paid. The three economy cells come from `economy.json` ("Economy projection" below); a lane the poller has not joined — or no poller — has a blank cell |
+| 35 | `×` close, on unregistered sessions only: it asks ` › close ‘name’? y/n` first; `y` closes, any other key cancels |
+
+The cursor is a lane, not a row: when a lane changes section (it starts needing you, its turn finishes, you open a
+`done` lane) the cursor and the scroll position go with it. A list that fits the pane is never scrolled: its
+first rows stay on screen.
+
+Title and notifications (spec §4.9): the sidebar pane's title is `WORKSPACE · ◆1 ◇2` (the header counts, rewritten
+only when they change; a workspace without agents never sets one) — the phone is built to read its counts from it.
+Since plan Task 26 the phone's picker pane has no fixed layout name, so Zellij can report that title — but only in a
+session laid out after Task 26: an existing phone device keeps the old picker pane until `lanes rebuild <device>`
+(`upgrade-session` and `ensure` add missing tabs and rename titles, they never re-lay-out a tab; `lanes doctor` names
+such a device). Whether it
+reaches the phone is still unchecked in a browser (DEF-1450). A lane that
+STARTS needing you (`◆` `✗` `◇`) raises one desktop notification, `name: task`, through OSC 9 — once per transition,
+never for the lane this pane shows, never on a phone, and not at all under `LANES_NOTIFY=0`. A sidebar that starts
+(or restarts) while lanes already need you announces each of them once. Both are bytes in the frame the sidebar
+already writes: no process is started. Ghostty shows OSC 9 only while the lanes window is NOT focused
+(`desktop-notifications = true` in `client/ghostty/common.conf`); on a terminal or Zellij build that drops OSC 9 the
+notification is a silent no-op and nothing else changes. Mac check: not yet run (the plan's Task 25 step 4 asks for one
+on the Mac — record the Zellij and Ghostty versions and the outcome here).
+
+Header: the workspace title, then `◆1 ◇2 ▸6 ✓1` in the column-2 glyphs (zeros omitted; `N lanes` without agents;
+dimmed while the footer warns that status is old). 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 and keeps column 2. A list longer than the pane ends in `⋮ N more`; moving onto
+that row, or clicking it, scrolls instead of opening the lane behind it. **Unregistered** lists every observed tmux
+session associated with this workspace but absent from its registry — nothing alive is ever hidden, and a session
+whose NAME could not be declared (parentheses, `/` and `,` are outside the lane grammar) is listed, opened and closed
+exactly like any other ghost: the grammar governs what may be DECLARED, never what may be SEEN. (`status.json`
+carries a `note` 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. 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
@@ -37,7 +78,7 @@ lane is counted there). The `view-` NAME decides nothing: an ungrouped `view-not
 killed under it, are alive and ARE listed — but when a killed lane left SEVERAL grouped survivors, the oldest is
 the lane and the later ones are its viewers, the same choice the Studio makes (`statusd.group_leaders`,
 `inventory::group_leader`). A declared lane is always its own row, whatever it is grouped onto. A Studio lane the
-Studio itself started is `st_<board>_<slug>` on the board's socket and IS shown as `👻` until declared, on a
+Studio itself started is `st_<board>_<slug>` on the board's socket and IS listed under **Unregistered** until declared, on a
 socket some board declares or not: discovery probes every live socket in the container.
 
 **Unregistered terminals:** every workspace has an **Unregistered** section, including sessions on shared and
@@ -52,10 +93,23 @@ 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.
 
-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
-shell and its jobs. New + shells do not have this limitation.
+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.
+
+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.
+
+The tracker for plain Docker shells from before persistent terminals (**Legacy** rows) is retired (plan Task 19):
+statusd no longer reads `~/.local/state/lanes/legacy-sessions/` and the sidebar no longer lists or closes those
+shells. `lanes doctor` names any record still there (`⚠ legacy-sessions/ holds N records …`); end that shell
+inside its container by hand, then delete the record.
 
 ## Server (as the workspace account)
 
@@ -64,14 +118,64 @@ lanes doctor            full health check            lanes status        per-wor
 lanes sync              re-read registries now        lanes ls [--json]   lanes with live status
 lanes rebuild <device>  recreate a view session       lanes ensure        recreate missing view sessions
 lanes invariant save|check   prove no live pane changed (pid + window size)
+lanes device list       the devices ensure keeps    lanes device forget <name>   stop recreating one
 systemctl --user status lanes-statusd lanes-sync.timer lanes-ensure.timer lanes-web
 ```
 
+- **What `lanes doctor` says about the boards' recipes (plan Task 18):** one line counts the tmux lanes per create
+  recipe class — `idempotent` (a `tmux new -A…`: creates, or attaches when the session exists; the canonical recipe),
+  `attach-only` (`attach-session` and no `new`), `null` (no recipe), `external` (a script or anything else, run as
+  written) and `retired-path` (names the retired in-container `~/.config/coder-launch`). One line says how many of
+  them create with their identity (`-e LANE_ID=…`, DEF-1478). Warnings (`⚠`, never a `✗`, the exit code is
+  unchanged): lanes that `lane open` cannot recreate once they end (attach-only, null, retired-path — fix with
+  `lanes cursor-sync --canonicalize`), lanes bound to a numeric session name (tmux numbers unnamed sessions itself,
+  so a recreated one gets another number), more than 4 lanes on one container's tmux socket `default` (the server every
+  plain `tmux` typed in that container talks to), and tmux socket files in a container's `/tmp/tmux-1000` that no
+  running tmux server (read from the container's cgroup) owns. That last one is **report only**: the host never
+  removes a file in a container. Inside the container, `~/.lz/bin/lane gc --sockets` probes each socket file with
+  `tmux -N -S <path> list-sessions` and, where tmux fails, connects to the file once itself: only ECONNREFUSED (the
+  file is there, nobody listens) unlinks it, printing each path; a server that answers (even with no session), does
+  not answer within 5 s, or refuses for another reason (EACCES, …) keeps its file. The errno decides, never tmux's
+  wording: tmux 3.4 prints `no server running on <path>` for ECONNREFUSED and `error connecting to <path>
+  (<strerror>)` only for other errnos (DEF-1459).
+- **A device you no longer use (an old laptop, a phone you replaced):** `lanes device forget <name>` removes
+  `devices/<name>.json`, so `lanes ensure` (`lanes-ensure.timer`) stops recreating its view session and `sync` /
+  `upgrade-session` stop updating it. A view session that is running is left alone and says so; once it ends, nothing
+  brings it back. `lanes attach <name>` / `lanes prepare <name>` creates the device again. `lanes device list` shows
+  each device, phone or desktop (viewports), and whether its view session runs.
+
 - **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.
+  re-reads registries every 2 minutes and the sidebar follows. The zellij layout is never edited live. A sync that
+  finds nothing new leaves `registry.json` (and its `generated_at`) untouched and only records the time in
+  `registry.synced`; the unit is bounded at `TimeoutStartSec=120`.
+- **`lanes gc` (daily `lanes-gc.timer`):** truncates zmx logs over 5 MB and removes a `resolve.dynamic/<id>` file
+  only when that id is in none of `status.json`'s `lanes`, `unregistered` or `zmx` AND the file is over an hour old.
+  statusd lists every `unregistered` and `zmx` row id under `lanes` as well; reading the other two keys is a
+  defence, not a second source. The mtime alone is no liveness signal: an unregistered session's file is rewritten only when its target or name
+  changes, so a live one is as old as the session. `removed stale <id>` for a session you can see is a defect.
+- **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. It asks first, in the
+  footer's one prompt shape: ` › Register ‘name’? y/n`.
+- **The sidebar footer** (bottom-up: footer, rule, strip row, upload strip; spec §4.6) shows ONE line by priority: the
+  close confirm ` › close ‘name’? y/n` > ` › Rename: …█` > ` › Register ‘name’? y/n` > the filter ` /abc · 3 matches` >
+  the health banner > ` ⚠ registry: …` > the last message > the legend ` ⏎ open · / find · x close · ? keys`. `?` shows
+  every key in place of the list until the next key. A filter with no hits says ` no lane matches ‘abc’ · Esc`; a
+  workspace with no lanes says `  no lanes declared · + New shell`. Above the rule, when the pane has 18 rows or more,
+  the strip row is the fleet economy line when `economy.json` knows a fleet fact (` $8.5k/16k 53% · F2 S1 · spill 76%`,
+  see "Economy projection"); otherwise it names the OTHER workspaces whose agents need you (` ◆1 Worlds · ◇2 Code`,
+  from the status.json already read). Under `LANES_GLYPHS=ascii` every glyph, separator and quote has a seven-bit twin (` > close 'sh'? y/n`,
+  ` Enter open - / find - x close - ? keys`).
 - **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.
+  rebuild and leaves you on the tab you were on. It never changes an existing tab's panes: a changed pane (e.g. the
+  phone picker after plan Task 26, which `lanes doctor` flags) needs `lanes rebuild <device>`.
 - **A new workspace:** add it to `~/.config/lanes/workspaces/catalog.json` + a manifest, `lanes sync`, then
   `lanes rebuild <device>` (the only time a layout changes).
 - **Registry invalid:** the workspace keeps its previous lanes; the sidebar footer and `lanes doctor` show why.
@@ -93,7 +197,7 @@ fails first. A question that got no answer is never published as "the lane is go
 | Viewport: **THIS VIEWER DISCONNECTED — the lane's tmux server is still running** | The viewer's tmux client was dropped or could not attach in time; the lane's socket is still there. That is ALL this headline claims: the retry below it is what learns whether the session itself survived, and when the holder then answers `is not provisioned`, nothing says the lane is untouched (a lane killed elsewhere — a Throttle Studio `Stop`, an operator's `kill-session` — leaves the server up, and the old headline claimed the lane still ran, DEF-965). The reason and a health hint follow; it retries by itself. | Nothing, unless the retries keep saying `is not provisioned` — then the lane is gone: pick another in the sidebar. |
 | Viewport status screen WITHOUT that line | The lane's tmux socket is really gone. | "A dead lane, or a blind harness?" below. |
 | Client window: `connecting…`, later a hold screen with a countdown | `lanes-launch` never closes the window by itself. ssh failed, or the server dropped a slow client (zellij does that with exit 0), or the server refused (exit 64–78): it holds, re-attaches when the countdown ends, backs off up to 60 s. `Enter` = now; closing the window = quit. Log: `~/.local/state/lanes-client/launch-<target>.log`. | Leave it open. |
-| Upload box `no upload helper` while windows were closing | The helper is a per-machine service now (launchd `ai.beyondwork.lanes-helper` / `systemctl --user status lanes-helper`) and survives the window. It counts as serving while `~/.local/state/lanes-client/helper.alive` is younger than 90 s. | `./install.sh --check` on the client. |
+| Upload strip ` ✗ no upload helper` (the old upload box: `no upload helper`) while windows were closing | The helper is a per-machine service now (launchd `ai.beyondwork.lanes-helper` / `systemctl --user status lanes-helper`) and survives the window. It counts as serving while `~/.local/state/lanes-client/helper.alive` is younger than 90 s. | `./install.sh --check` on the client. |
 | A live test suite prints `SKIP  host is busy: …`, exit 75 | `tests/*.py` refuse to start above load 2 × cores or memory pressure (some avg10) 20 %: they add load and would fail for the wrong reason. | Run it later (`LANES_TESTS_FORCE=1` only on purpose). |
 
 ### Look, without adding load
@@ -103,6 +207,8 @@ lanes pressure             memory / io / cpu pressure, swap, load, per-container
                            shmem) and /tmp fill. Plain files + statvfs: safe on a thrashing host. Exit 1 unless level ok.
 cat ~/.local/state/lanes/health    what statusd wrote last; at= and status_at= are epochs — compare with `date +%s`
 lanes doctor               every external call is bounded; "N shown with their last known state" = blind, not dead
+                           `preview renderer:` pinned glow | system glow (<path>) | less -R — looked up on the view
+                           server's PATH, the one the Ctrl-Alt-m pane sees, never your shell's
 lanes invariant check      1 s: every live pane's pid and size against the last `invariant save`
 ```
 
@@ -165,6 +271,20 @@ refused. Everything removed is logged in `~/.local/state/lanes/tmpscan/deleted.l
    touch. Socket there and the server's pid alive = the lane lives and only the harness is blind.
 5. `health` older than 30 s (`at=` against `date +%s`) = statusd itself is starved: the sidebar shows history.
 
+How statusd looks, and why one wedged server cannot freeze the board: it finds the live tmux servers in each
+workspace container's OWN cgroup (`cgroup.procs` + `comm` + `cmdline` under `/proc`, the same walk as `lanes guard`;
+no `ps`, no fork), probes at most 8 servers at once, and stops waiting `PROBE_TIMEOUT + 2` = 7 s after the round
+began. A probe still running then is published as `"observed": "timeout"` (last state, `stale`), the other servers'
+answers go out on time, and the next round starts only once that probe's own bound has passed (another 7 s). A
+server the deadline cut carries `"cut": true` in `status.json` `servers` and is probed FIRST next round, so with more
+servers than 8 the same tail is not cut every cycle (and never drifts to `unknown` while it answers in time). A
+container whose recorded init pid cannot be walked (not a docker cgroup, a recycled pid) makes the round treat THAT
+container's socket files as possibly live — nothing of it is concluded gone; the other containers keep their real
+live sets. In `journalctl --user -u lanes-statusd`: `observe: … still running at the 7 s cycle deadline (first next
+round): <container>/<socket> …` names the abandoned probes, and `live servers <container>: pid <n>: …` names a
+container that became unwalkable (logged once, when it starts). `lanes invariant` stays all-or-nothing: one
+unwalkable container makes it refuse rather than save a partial pane list.
+
 A lane is dead only on a POSITIVE observation: its server answered without that session (`–`), its pane died (`!`),
 or its container is down (`✖`).
 
@@ -194,6 +314,11 @@ Coexistence mode can be turned back on at any time with `touch ~/.local/state/la
 - Terminal: Ghostty in a dedicated instance (`~/.config/lanes/ghostty.conf`, inherits `~/.config/ghostty/config`, so
   Omarchy theme switches follow). Foot stays the system default; without Ghostty the window falls back to Foot with
   the same class. Install Ghostty only: `omarchy-pkg-add ghostty` (`omarchy-default-terminal` is not touched).
+- Font: the Omarchy default font; a Nerd Font is not required by lanes — every glyph is plain Unicode
+  (`LANES_GLYPHS=ascii` for any font; the blocks a font needs are listed under "TUIs and the terminal's colours"
+  below). The Zellij bar runs with `simplified_ui true`, so it draws no Private-Use-Area chevrons either.
+- Look of the window: `lanes-window --ascii`, `--light`, `--dark` (combinable with a suffix: `lanes-window --ascii w2`)
+  — see "TUIs and the terminal's colours" below.
 - Hyprland: one line `require("hypr.lanes")` at the end of `~/.config/hypr/hyprland.lua` + `~/.config/hypr/lanes.lua`
   (validated with `hyprctl configerrors`; backup `hyprland.lua.pre-lanes.*`). Pin it to a workspace by uncommenting
   the `o.window` line in `lanes.lua`.
@@ -223,6 +348,67 @@ night sky of single-dot Braille "stars". Started with no client attached it pain
 - It stops recurring when the clients agree on brightness: the same light/dark choice in Cursor's terminal and in the
   lanes window (Ghostty `theme = light:…,dark:…` follows the OS and therefore flips twice a day).
 
+The sidebar's own colours and glyphs come from one token table (`libexec/tokens.py`; spec
+`docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md` §2.4) and three switches, resolved per device:
+
+| Switch | Values | Default |
+|---|---|---|
+| `LANES_COLOR` / `--color` | `truecolor` · `16` · `none` | `truecolor` when `COLORTERM` is `truecolor`/`24bit`, else `16` (your terminal's own palette); `NO_COLOR` set ⇒ `none` (glyphs only) |
+| `LANES_THEME` / `--theme` | `dark` · `light` · `auto` | `auto`: the sidebar asks the terminal's background once at start (OSC 11) and paints dark until the answer; no answer within 0.3 s ⇒ dark |
+| `LANES_GLYPHS` / `--ascii`, `--glyphs` | `unicode` · `ascii` · `emoji` | `unicode`; `ascii` when none of `LC_ALL`/`LC_CTYPE`/`LANG` names UTF-8 |
+| `LANES_DIM` | `90` · `2` | `90`; 16-colour mode only: `2` is the escape hatch for a palette whose colour 8 is near the background |
+
+- Set it per device, live: `lanes attach DEVICE --ascii` (or `--glyphs M`, `--theme T`, `--color C`) records the
+  choice in `~/.local/state/lanes/devices/<device>.json` (only for a device that already has that file; a bad value
+  refuses before anything is created). Every running sidebar of that device re-reads the file within one tick — no
+  restart. The choice survives a recreated session (`lanes ensure` after a reboot, `lanes rebuild`). Environment
+  variables never reach a running sidebar: Zellij panes keep the server's environment from the moment the session
+  was created. The device file wins over the environment.
+- The sidebar publishes what it resolved: `clients/<device>.theme` (`dark`/`light`, on change or when absent; for
+  `glow`) and `clients/<device>.glyphs` (`unicode`/`ascii`/`emoji`, on change or when absent; read by `view.sh`).
+- The terminal's answer to the OSC 11 question is taken out of the input before any key is read, also when it is
+  split across two reads, so it never cancels a filter or a prompt.
+- Dim text is SGR 90 in 16-colour mode (never SGR 2, which several terminals render as invisible). A palette whose
+  colour 8 is close to the background (classic Solarized dark) can set `LANES_DIM=2` as the escape hatch.
+- From the Mac or Omarchy window: `lanes-window --ascii`, `--light` or `--dark` (before an optional suffix:
+  `lanes-window --dark w2`) hands `--ascii` / `--theme light|dark` to `lanes-launch`, which passes them to
+  `lanes attach` — the same per-device record as above. `lanes-launch DEVICE --ascii|--theme T|--glyphs M|--color C`
+  takes them directly; a bad value refuses before any connection, an unknown option is named and dropped.
+- The viewport's own status screens (`view.sh`: "THIS VIEWER DISCONNECTED", "No lane selected", "retrying in …") use
+  the same tokens (`libexec/tokens.sh`, sourced once, no fork): a bold lead with `⚠` — `!` when
+  `clients/<device>.glyphs` says `ascii`, read on every screen, so `lanes attach DEVICE --ascii` reaches the next
+  status screen without a restart — and the hint line in SGR 90 instead of SGR 2.
+- Fonts: no Nerd Font is needed. Any monospace font with Latin-1, Box Drawing (U+2500 `─`), Geometric Shapes
+  (U+25A0–25FF `● ○ ◆ ◇ ▸ ▌ █`), Dingbats (`✓ ✗`), Arrows (`↑ ↓`) and `⋮ ⏎ ⚠ …` renders the cockpit (JetBrains Mono,
+  SF Mono, Menlo, Cascadia, DejaVu Sans Mono all do); `--ascii` is the complete remedy for any other font.
+- The lanes window inherits your everyday Ghostty look (fonts, theme, padding: `client/ghostty/common.conf` never sets
+  them). Opt in to the cockpit's own palette with `./install.sh --palette` (client install): it installs
+  `~/.config/lanes/ghostty-palette.conf` — generated from the token table (`client/ghostty/lanes-palette.conf` and
+  `lanes-palette-light.conf`, `libexec/tokens.py --ghostty-dark|--ghostty-light`; slots 1–4 are the four tones, so
+  16-colour mode under it equals truecolor mode) — and includes it last in `~/.config/lanes/ghostty.conf`. On Ghostty
+  1.1 or newer (`ghostty +version`) that file is `theme = light:…,dark:…` over two installed theme files, so the
+  window still flips with the OS; on an older or unknown Ghostty it is the dark palette alone (the light one is
+  installed next to it as `ghostty-palette-light.conf`). Ghostty lays a `theme` UNDER every colour key
+  (`background`, `foreground`, `palette = N=…`, cursor/selection colours) set explicitly anywhere in the loaded
+  configuration, whatever the file order — and the lanes window loads your everyday config first. So the installer
+  walks the everyday config and every file it reaches through `config-file`: if any sets a colour key (Omarchy does —
+  its config includes the current theme's `ghostty.conf`), a theme pair would silently keep your everyday colours, and
+  it installs the explicit dark palette instead and says which file forced that (`dark only: … sets colours
+  explicitly`). Ghostty also loads `config-file` includes breadth-first (one first-in-first-out list:
+  `Config.zig` `loadRecursiveFiles`), so a file two includes deep — Omarchy's theme `ghostty.conf` — loads after
+  every direct include of the lanes `ghostty.conf`, the palette's included. The installer therefore records the
+  everyday chain's deepest include and places the palette keys (or the theme pair) behind as many one-line hop files
+  (`ghostty-palette.1.conf`, …) as it takes to sit at that depth, where they load last; on Omarchy that is one hop,
+  and the `say` line names it. A plain `./install.sh` re-run without `--palette` removes the include and all palette
+  files: inherit-first is the default. NOT yet looked at on a real Ghostty (2026-10-04: no Mac or Omarchy client was
+  used; the installer was exercised against a fake `ghostty` that reports a version, fake everyday configs and a
+  model of Ghostty's load order read from its source). DEF-1466 stays open until that is seen: run `--palette` on a
+  Mac (Ghostty ≥ 1.1) and on Omarchy, and the window background must be `#101318` (the dark `surface` token).
+- OSC 11 on a real Ghostty view is NOT yet verified (2026-10-04: Task 22 ran on the server with no Mac client
+  attached, and no live session was touched). To check: with the Mac in light mode, `lanes attach mac` from the Mac,
+  then on the server `cat ~/.local/state/lanes/clients/mac.theme` — `light` means the answer arrived and was parsed;
+  `dark` means no answer within 0.3 s (the sidebar painted dark). Record the result here.
+
 ### "tmux server … is not running" on every lane at once (deleted sockets)
 
 Seen 2026-09-20 04:24: something emptied `coder-dev-work:/tmp`, and with it `/tmp/tmux-1000` — the directory of every
@@ -236,7 +422,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 +434,20 @@ 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, the retired `~/.config/coder-launch` path (the three
+  classes `lanes doctor` warns about, DEF-1460), 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-1478 — 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-1479: a `lanes/<ws>/<id>` trace makes the whole lane — main session, subagents, fan-out — one proxy
+  fairness bucket. Applying `--canonicalize --write` or `--identity --write` to a live workspace is an operator gate
+  (plan "Operator gates"): it rewrites operator-declared recipes in the repo's `.vscode/terminals.json` (old value kept
+  as `createPrevious`, file backup under `cursor-sync-backups/<ts>/` as above) and produces the first live `lanes/<ws>/<id>` trace — decide DEF-1479 lane-level
+  vs per-session fairness first.
 - 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
@@ -254,6 +455,207 @@ only normalizes HOW a terminal reaches its lane:
   included, and both halves apply there: an `ignore-size` an operator set by hand on such a socket is given
   back like any other once no view shows the lane (DEF-982).
 
+## Installing agent hooks (opt-in, per container, dry run first)
+
+Without hooks the sidebar's agent glyph comes from Claude's session files and Codex's pane title. Hooks make it
+event-driven: Claude Code or Codex runs `~/.lz/bin/lane-signal <status>` on a turn event, which writes
+`~/.lz/state/hooks/<lane id>.json` in the container, and `lanes-statusd` prefers that over the other signals while
+its agent runs and its last event is under an hour old. Nothing installs a hook for you. (`~/.lz/state/<name>.json`
+itself is `lane-run`'s phase record of a zmx lane; the hook never writes there. A hooked agent in a zmx lane writes
+its sidecar under the zmx session name, which the sidebar does not show yet — DEF-1437.)
+
+1. `lanes install-container <name>` — puts `lane-signal` in `~/.lz/bin/` and the definitions in `~/.lz/hooks/`.
+2. `lanes hooks install --agent claude --container <name>` — prints the unified diff it would make to that
+   container's `~/.claude/settings.json` (your own hooks and keys stay; an earlier lane-signal install is replaced,
+   not duplicated). Read it. Then add `--write` (the old file is kept as `settings.json.lanes-bak-<time>`).
+3. `lanes hooks install --agent codex --container <name>` — the same for `~/.codex/hooks.json`, plus a top-level
+   `notify = [".../lane-signal", "done", …]` in `~/.codex/config.toml` only when that file has no top-level
+   `notify` (an existing notifier is left alone). Codex asks you to review and trust new hooks before running
+   them (`[hooks.state]` in its config.toml); lanes never writes that trust.
+
+Expect a hook to reach only agent sessions started after the install (both harnesses read their hook
+configuration at start — INFERRED, not measured here). `--home <dir>` targets a home directory instead of a
+container (for trying the merge on a copy). Undo: restore the `.lanes-bak-*` file, or delete the groups whose
+command contains `lane-signal`.
+
+What each event writes (`agent{}` vocabulary):
+
+| Harness | Event | status |
+|---|---|---|
+| Claude Code | `UserPromptSubmit`, `PostToolUse` | `working` |
+| Claude Code | `Stop`, `Notification` (`idle_prompt`) | `needs_input` |
+| Claude Code | `PermissionRequest`, `Notification` (`permission_prompt`) | `needs_approval` |
+| Claude Code | `StopFailure` | `errored` |
+| Claude Code | `SessionEnd` | `shell` |
+| Codex | `SessionStart` | `idle` |
+| Codex | `UserPromptSubmit`, `PostToolUse` | `working` |
+| Codex | `PermissionRequest` | `needs_approval` |
+| Codex | `Stop`, `notify` (turn complete) | `done` |
+| Codex | `SessionEnd` | `shell` |
+
+Verified event names (2026-10-04, this host): Claude Code 2.1.288's hook-event list compiled into its binary
+(`PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, Notification, UserPromptSubmit, UserPromptExpansion,
+SessionStart, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop, PreCompact, PostCompact, PreModelSwitch,
+PostModelSwitch, PermissionRequest, PermissionDenied, …`); Codex 0.160.0's hook event variants in its binary
+(`PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SessionEnd, SubagentStart,
+SubagentStop, Interrupt`, plus `UserPromptSubmit` and `Stop`), and the shape of a trusted project
+`.codex/hooks.json` (`{"hooks": {Event: [{"matcher": null, "hooks": [{"type": "command", "command", "timeout"}]}]}}`).
+Codex 0.160 has no `codex --help hooks`; the names come from the binary. Not yet proven on a live lane: that Codex
+loads a USER-level `~/.codex/hooks.json` the way it loads a project's (the only hooks.json files measured here are
+project files), and what a hook's parent process is under each harness (lane-signal skips one shell either way).
+
+Known limit (DEF-1434): after you approve a permission prompt, the lane shows `needs_approval` until the approved
+tool call returns (`PostToolUse`), because neither harness signals "approved". A long approved command therefore
+reads as waiting for you until it finishes. A lane whose agent crashed loses its sidecar at once (dead pid); one
+whose agent is alive but silent keeps the last word for up to an hour.
+
+## Economy projection (opt-in)
+
+`~/.local/state/lanes/economy.json` is what each lane costs and how hard the fleet is pushing the Throttle pool:
+a fleet strip (overflow spend against the enforced daily cap, alert level, pressure phase and spill fraction,
+effectively free accounts, the soonest 5 h reset, new upstream 429s since the last poll, paid and subscription
+requests in flight, the Fable governor's sustainable rate) and, per lane, live figures from the daemon's
+recent-request ring (model, paid share, $/h, tokens/min, cache-read ratio, downgrades, 429s, age of the last
+request) plus today's totals folded from `proxy.log` (requests, paid requests, the four token classes — dollars only
+as `list_usd_estimate`, which stays `null`; lanes keeps no price table).
+
+**What the sidebar shows from it.** Every sidebar re-reads `economy.json` when its mtime changes (one `stat()` per
+tick). Column 34 of a lane row is one tail cell (`⚠` starving, `↓` downgraded, `$` mostly paid; `?` — not observed —
+beats all three). The strip row above the footer rule (panes of 18 rows or more) becomes the fleet economy line, parts
+in priority order and whole parts dropped from the end to fit 34 cells:
+
+| Part | From | Shown |
+|---|---|---|
+| `$8.5k/16k 53%` | `overflow_spend_today_usd` / `overflow_budget_usd`, `spent_fraction` | amber at or over `alert_level_pct` |
+| `429 +4` | `upstream_429_delta` | only when > 0, amber |
+| `F2 S1` | this workspace's lanes by `model`: `F` fable, `O` opus, `S` sonnet, `H` haiku, `G` gpt | tier letters live here and in the preview, never in a row |
+| `spill 76%` | `spill_fraction` | amber unless `pressure_phase` is `closed` |
+| `free 3/19` | `effective_free` / `accounts` | |
+| `reset 2h` | `soonest_reset_5h` | only while in the future |
+
+A leading `?` and an all-dim line mean the figures are frozen: the poller kept its last fleet strip because `/status`
+failed (`"stale": true`), or the poller stopped — the poller rewrites `economy.json` at least every 60 s, and a sidebar
+treats a document more than 180 s old by its own clock as frozen (DEF-1447). A lane's tail cell follows the same rule:
+a `⚠` or `↓` drawn dim (not amber) is the last known figure, not a live alarm — the poller kept that lane's record
+because `/sessions` failed (`"stale": true` on the lane), or the whole document is frozen. With
+`LANES_THROTTLE_CONTROL=none` every fleet figure is `null`: the strip row then shows fleet attention exactly as without
+a poller, and no row carries an economy cell (the day totals carry no live figure).
+
+**Operator gate.** `lanes-economy.service` sends a GET to the Throttle daemon's control port (`/status` and
+`/sessions`, default `http://127.0.0.1:19181`) every 10 s. It is installed with the other units and enabled by
+nothing. Turning it on is your call.
+
+**Where it runs — read this before enabling.** The unit is a HOST user unit (the server installer renders it beside
+`lanes-statusd`); the daemon, its control port and its log normally live inside a workspace container. Neither
+default reaches them from the host:
+
+- The control URL is resolved in the HOST's network namespace. A daemon bound to `127.0.0.1` inside its container
+  (`[server] host = "127.0.0.1"`, measured 2026-10-04 in the `work` workspace container) is not reachable from the host at all, and
+  `http://127.0.0.1:19181` on the host is a different loopback. Until the control port is reachable from the host —
+  an operator change to the daemon's bind or forwarding, outside lanes — set `LANES_THROTTLE_CONTROL=none`: the
+  fleet strip and live per-lane figures stay `null`, the log fold still works (DEF-1444, open).
+- The log lives in the container's home. Set `LANES_THROTTLE_CONTAINER=<container name>`: the poller reads
+  `/home/coder/.local/share/throttle` through that container's home volume as `lanes sync` recorded it in
+  `~/.local/state/lanes/containers.json` (the container must be on a board). The host user's own
+  `~/.local/share/throttle` is the default only for a poller that runs where the daemon runs.
+
+Check what the poller can see before you enable it — `--once` names every source it could not read on stderr
+(`connection refused`, `timed out`, `HTTP 401`, `log dir missing: …`, `log dir unreadable: …`,
+`container … is not in containers.json`). `log dir unreadable` on a host unit usually means the container's home
+volume sits under the docker data root (`docker info -f '{{.DockerRootDir}}'`: `/var/lib/docker` by default,
+`/data/docker` on ceobox, where the workspace homes are named volumes at `<root>/volumes/coder-<id>-home/_data`),
+which only root normally traverses. The log half then needs the same operator decision as the control half
+(DEF-1444): point `LANES_THROTTLE_LOG_DIR` at a directory this user can traverse, or run the poller where the daemon
+runs:
+
+```sh
+LANES_THROTTLE_CONTROL=none LANES_THROTTLE_CONTAINER=<container> lanes economy --once --dry-run   # writes nothing
+systemctl --user edit lanes-economy.service     # put the same two settings in the drop-in ([Service] Environment=)
+systemctl --user enable --now lanes-economy.service
+journalctl --user -u lanes-economy.service      # one line each time a source goes down or comes back
+```
+
+Before you enable it, settle DEF-1479 (the lane-stable trace's fairness consequence) if any lane was created with
+the identity recipe; lanes without it are joined to their requests by `agent.session_id` alone.
+
+Settings (environment of the installer — `install/services.py` renders them into this unit only — or a
+`systemctl --user edit lanes-economy.service` drop-in):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `LANES_THROTTLE_CONTROL` | `http://127.0.0.1:19181` | control base URL, resolved in the poller's network namespace (see above); `none` sends no request at all (the log fold still runs) |
+| `LANES_THROTTLE_TOKEN_FILE` | unset | file holding a bearer; a loopback daemon without `remote_key` needs none. Never written to `economy.json` or the cursor |
+| `LANES_THROTTLE_CONTAINER` | unset | the container whose home volume holds the daemon's log; the log dir becomes its `/home/coder/.local/share/throttle` (via `containers.json`) |
+| `LANES_THROTTLE_LOG_DIR` | `~/.local/share/throttle` | where `proxy.log` and `proxy.log.<day>` are read (read only); wins over `LANES_THROTTLE_CONTAINER` |
+
+Behaviour you can rely on: GET only, 3 s timeout, no proxy from the environment, no redirects followed (a redirect
+would carry the bearer elsewhere). A failed `/status` keeps the last fleet strip with `"stale": true`; a failed
+`/sessions` keeps each lane's last live figures with `"stale": true`; `source` says which of status, sessions and
+log answered, and the journal (stderr) says why one did not — a line when a source's failure class changes, `ok`
+when it recovers; the reason is never written to `economy.json`. `economy.json` is rewritten only when something other than `at` changed. The fold cursor
+(`economy.cursor.json`) reads only bytes appended since the last poll and keeps ten days. Deleting both files is safe:
+the next poll re-folds today. For a look without the daemon: `LANES_THROTTLE_CONTROL=none lanes economy --once
+--dry-run --status-file status.json --sessions-file sessions.json` with saved documents.
+
+## Push notifications (opt-in)
+
+`lanes-notify.service` sends one push to an [ntfy](https://ntfy.sh) topic when a lane's agent ENTERS needs-you —
+`agent.status` becomes `needs_input` (`Needs you`), `needs_approval` (`Needs approval`) or `errored` (`Error`), the
+same set the sidebar's Needs you section and its OSC 9 use. It is the away-from-every-terminal half of the sidebar's
+OSC 9 ("Title and notifications" above): it reads only `~/.local/state/lanes/status.json` (checked every 3 s,
+re-read when its mtime changes) and `registry.json` for lane names; it never touches a lane, a session or the
+Throttle daemon.
+
+What a push says: `<lane name>: <agent task> — <status>` and, on a second line, `lanes-launch lane <id>` (the
+command that opens that lane from a client). No client registers a URL handler for that command, so a push is
+tappable only when you set `action_url` (below).
+
+When nothing is sent:
+
+- the status did not change, or the lane left needs-you (a later return is news again); a change from
+  `Needs you` to `Needs approval` is news;
+- the service just started: lanes already waiting when it (re)starts are not announced (no burst on restart —
+  unlike a starting sidebar's OSC 9);
+- a desk device was present within `quiet_when_device_active_s` (default 120 s): a `lanes attach` from any device
+  (`clients/<device>.<client>.pid`), or a lane opened from the sidebar of a desk device
+  (`clients/<device>.seen.json`, counted only for a device that has a `.pid` — one `lanes attach` has run for —
+  and whose `devices/<device>.json` is not `mobile: true`) that recently. Typing in a lane refreshes neither, so after two minutes at the keyboard without attaching or
+  opening a lane the pushes resume (DEF-1451). A suppressed transition is dropped, not sent later. Phone presence
+  is decided by the device's mobile layout, not by how it attached: a Safari phone writes no `.pid`, and an
+  SSH-only phone that ran `lanes attach phone --mobile` (below) is still a mobile device, so opening a lane from
+  the phone's picker never mutes pushes — you keep getting them while you are away from every desk (DEF-1452).
+  Only a phone's own `lanes attach` in the last two minutes counts, like any attach.
+
+A failed send (server down, `HTTP 429`, no network) is one journal line naming the lane and the failure class — the
+topic and the token are never logged — and is not retried.
+
+Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` in the server installer's environment renders another
+path into this unit only), `key=value` lines, `#` comments, re-read on change:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `url` | required | the ntfy server, `https://…` (self-hosted or `https://ntfy.sh`) |
+| `topic` | required | `[A-Za-z0-9_-]{1,64}`; on a public server the topic name is the only secret — pick a long random one |
+| `token_file` | unset | a file holding an ntfy access token (sent as a bearer). An unreadable file disables sending rather than sending unauthenticated. Keep the token in that file (`chmod 600`), never in `notify.conf` |
+| `quiet_when_device_active_s` | `120` | presence window above; `0` never suppresses |
+| `action_url` | unset | a URL template over `{lane}` (the lane id, URL-quoted), e.g. a page of yours that opens it; becomes the push's tap target and an **Open lane** button |
+
+Without a valid `url` and `topic` the service only tracks transitions and sends nothing. Turn it on:
+
+```sh
+$EDITOR ~/.config/lanes/notify.conf                                  # url=, topic=, token_file= …
+python3 ~/.local/share/lanes/current/libexec/notify.py --test        # one test push; exit 1 = not sent
+systemctl --user enable --now lanes-notify.service
+journalctl --user -u lanes-notify.service                            # send failures, one line each
+```
+
+**Operator gate.** The unit is installed with the others and enabled by nothing: it sends lane names and agent
+task titles to the server you configure. Not yet run against any ntfy server or phone (unit-proven only).
+
+**Not part of this:** answering a `PermissionRequest`-held approval from the phone. A push only says the lane needs
+you; approving from the notification needs a request/response channel back into the hook that holds the prompt — a
+follow-up design.
+
 ## Throttle Studio as a client
 
 Throttle Studio (`throttle-rc studio host` in a workspace container, the `/workspaces` view of the Throttle console)
@@ -316,14 +718,14 @@ already ignore it. Afterwards the in-container path is on your clipboard and in
 
 | Way | How |
 |---|---|
-| Upload box in the sidebar | Click the box (or `Ctrl-Alt-u` from anywhere in the tab), then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. |
+| Upload strip in the sidebar | The one row above the footer rule, ` ↑ uploads · click, then drop  (U)`. Click it (or press `U` in the sidebar, `Ctrl-Alt-u` from anywhere in the tab) — it turns into ` ↓ DROP FILES NOW · anywhere · Esc` — then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. While it sends the strip says ` ↑ sending 2 files · 12.4 MiB` and repaints only when the helper reports progress (no spinner, no fast tick); the result stays 8 s as ` ✓ name, name` or ` ✗ reason`. |
 | Watch folder | `~/Lanes Uploads/` → the board your view shows; `~/Lanes Uploads/<board>/` → that board. Sent files move to `.sent/<date>/`. Point CleanShot's save folder here for instant screenshot upload. |
 | Command | `lanes-upload [-w <board>] [--paste] <files…>` · `lanes-upload --clipboard [--paste]` (clipboard image or copied files) |
 | macOS droplet | `~/Applications/Lanes Upload.app`: drop files on it (Dock); double-click uploads the clipboard screenshot |
 | anarchy | `Super+Shift+U` uploads the clipboard and types the path into the lane |
 
 Why click first: a terminal delivers a drop as a *paste of the local path* into the FOCUSED pane (not the pane under
-the pointer), so the box has to hold the focus when you let go. And the server only ever receives that path string:
+the pointer), so the strip has to hold the focus when you let go. And the server only ever receives that path string:
 the file itself is sent by the **upload helper** that `lanes-launch` runs on your machine. The helper is the security
 boundary — it reads only from folders listed in `~/.config/lanes/upload-allow` (defaults: Desktop, Downloads,
 Pictures, Documents, Lanes Uploads, temp folders; macOS asks once per new folder; `lanes-upload --allow <dir>`), and
@@ -356,6 +758,34 @@ On the phone, connect Tailscale and open the printed URL. Paste the token into t
 when tapping **Type here** or another text input; swipes, live updates and reconnects leave it closed.
 **More → Text size** remembers your preferred terminal font. The phone has its own view selection of the same agents.
 
+The lane picker shows three rows per lane: the agent glyph and the name (`›` before the lane this phone views), then
+what the agent needs and since when with its harness (`Needs you · 25m · claude`; a shell says `Quiet · 2h`), then the
+agent's task. Its first line counts the lanes that need you (`◆1 need approval · ◇2 need you · ▸6 working`). The same
+counts come from the picker pane's title (see "Title and notifications" above): the header subtitle on the picker,
+the page title, a number on the **Lanes** button for lanes needing approval or input, and `◆ 1 · ◇ 2` on each
+workspace card. Nothing is fetched or polled for them. Not yet confirmed (DEF-1450): until plan Task 26 (2026-10-04)
+the phone's picker pane had the fixed layout name `Lanes`, which Zellij reports instead of the sidebar's title, so the
+phone showed no counts. Task 26 removed that name from the generated layout, which reaches a phone only when its
+session is laid out again (`lanes rebuild <device>`; see the device check below); whether the title
+now reaches the phone is still unchecked in a browser — until then only the picker's own first line is known to
+show them (DEF-1450).
+
+The phone's light/dark toggle repaints the whole terminal, not only the shell: the page applies its own sixteen-colour
+palette on attach, on every toggle and after every Zellij config reload (DEF-1413; not yet looked at on a device).
+
+On a lane's own tab a row of quick keys sits above the dock: `⏎ y n Esc ^C ↑ ↓`. A tap writes the key to the lane
+without opening the keyboard. `n` and `^C` write only after you hold them for 400 ms; a short tap says
+"Hold to send". With the keyboard open the row stays above the keyboard's modifier bar. The filter bar on the picker
+sends its text as UTF-8, so a filter like `ø` matches.
+
+Device check (plan Task 13 step 3, not yet run): on a real iPhone in Safari and from the Home Screen, tap each quick
+key on a lane tab and confirm that the keyboard does NOT open, that `y`/`⏎`/arrows arrive in the lane, that a short tap
+on `n`/`^C` sends nothing and a hold sends it, and (plan Task 26 has landed; DEF-1450 waits on this) that the Workspaces
+sheet shows each picker's counts. A phone device created before Task 26 keeps the old picker pane (`upgrade-session`
+does not re-lay-out a tab): run `lanes rebuild <device>` first (`lanes doctor` must not list it under DEF-1450), or no
+counts appear and the check says nothing about the title path. Record the
+device, iOS version and result here. The unit suite covers only the picker's text, not the browser.
+
 Tailscale Serve forwards HTTPS 8443 to `lanes-mobile.service` on `127.0.0.1:8083`. The separate unprivileged
 Caddy serves `web/` and forwards native authentication/assets/WebSockets to Zellij on `127.0.0.1:8082`.
 The Mac is a client; serving happens on the workspace host. See [frontend maintenance](../web/README.md).
@@ -365,6 +795,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
@@ -374,12 +821,48 @@ An SSH-only phone client can run `lanes attach phone --mobile` instead.
 - pty-name collision guard: the lanes' `client-attached` hook detaches a client whose tty *name* equals the
   lane's `pane_tty`; host and container pty numbers collide, so the holder re-wraps itself on a fresh pty.
 - Views attach only from a pane zellij has really sized (unviewed tabs are 14x49) and only after a first client.
-- The sidebar binds in `zellij/config.kdl` walk `MoveFocus "left"` once per possible viewport before `WriteChars`:
-  with a single left, `Ctrl-Alt-↓` pressed in the second viewport typed a `J` into a lane.
+- The two binds in `zellij/config.kdl` that still type into the sidebar (`Ctrl-Alt-/`, `Ctrl-Alt-u`) walk
+  `MoveFocus "left"` once per possible viewport before `WriteChars`: with a single left, a key pressed in the second
+  viewport typed into a lane. `Ctrl-Alt-↓/↑` type nothing since plan Task 19 (`lanes next|prev --focused`).
 - Tests: `python3 -m unittest discover -s tests/unit` needs no server (runs on the Mac) and carries the harness's
   pure-function pins — the viewer rule, the client-size bucketing, the status keying, the shared-socket
   attribution and the zmx word (`tests/unit/test_alignment.py`). Live suites, on a QUIET host only:
   `tests/guards.py`, `tests/view.py` (incl. the wide-view key walk), `tests/upload_box.py`,
-  `tests/smoke_real.py` (read-only, real lanes), `tests/latency.py` (from a client). All use disposable lanes except
+  `tests/smoke_real.py` (read-only, real lanes), `tests/latency.py` (from a client; `tests/latency.py --switch
+  [samples]` ON the server measures `switch` = SIGUSR1 to view.sh → first byte of the new lane, with a throwaway
+  view.sh on a temp `LANES_STATE` and two sessions on `-L lanes_test`, run ad hoc). 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.