@vibelord/lanes 1.1.1 → 1.2.0

package/payload/lanes/docs/RUNBOOK.md

@@ -16,11 +16,13 @@ measurements; substitute your account, containers and paths in operational comma
 | 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: `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 (the lane gets every key except the `shared` chords that stay live while locked — the Ctrl-Alt arrows, `/`, `u`, `c`, `s`, PageUp/PageDown/End; 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 |
+| Lock the view | `Ctrl-Alt-g` locks (the lane gets every key except the `shared` chords that stay live while locked — the Ctrl-Alt arrows, `/`, `u`, `l`, `c`, `s`, PageUp/PageDown/End; 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` (the chord types nothing: it moves the focus to the sidebar and runs `lanes sidebar-key filter --focused` in a floating pane that closes at once; on Host or a tool tab it does nothing) |
+| Focus the sidebar | `Ctrl-Alt-l` (three `MoveFocus "left"`, nothing typed); the footer then reads ` ▌ keys go to sidebar · Esc → lane` and `Esc` gives the keyboard back |
+| Browse the sidebar | `Ctrl-Alt-l` (or click it), then `↑/↓` or `j/k`, `Enter`; opening a lane, and every other action that ends, gives the keyboard back to the lane (a prompt, the filter and the armed upload strip keep it). `?` shows the key sheet; the [user guide](USERGUIDE.md#the-sidebar) has every key |
 | 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) |
+| Edit a lane's AGENTS.md, CLAUDE.md or .env.local | `Ctrl-Alt-e`: a floating **Edit** pane runs `lanes edit --focused`, one key picks (`1`–`5`; `q`/`Esc` closes), then `docker exec -it -u coder -w <checkout> <container> ~/.lz/bin/lane-edit <file>` replaces it — the editor runs in the lane's container as uid 1000, the server only checks the paths through `/proc/<init>/root` and copies nothing out ([guide](USERGUIDE.md#quick-edit)). `lanes edit: lane-edit is not installed in <c>` → `lanes install-container <c>`; `lane-edit: no editor on PATH` (exit 127) → the container has none of micro, hx, nvim, vim, vi (Lanes installs none); `container <c> is not running` → nothing to edit until it runs; `no git checkout in or above <dir>` → the lane works outside a checkout. The editor is the device's `lanes attach <device> --editor E` choice |
 | 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. |
 
@@ -31,15 +33,15 @@ 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 `…` |
+| 1 | `▌` the cursor (no underline); in `truecolor` / `256` the cursor row also lies on the `selected` background up to column 35 |
+| 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`) — or, on a device with an owner, from any device of theirs (`users/<login>.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 · `…` (ink-dim; ASCII `~`) an action on its way, the row refusing every verb meanwhile: a session `x` is closing (until the worker answers), a session `P` is registering (it stays listed until the registry lists its lane: `PENDING_S` = 80 s, and never while the sync the sidebar started still runs), a shell `+` is creating (on the New shell row) · `▲` (accent; ASCII `^`) a lane its owner pinned (`p`, cockpit v3 R5: it leads its section and never falls below `⋮ N more`), the lowest of these marks |
+| 4–27 | the name in its identity colour (else ink, painted in `truecolor` / `256`), bold while this pane shows it, faint for a lane its owner hid while `o` shows the hidden lanes; 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 |
+| 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**; in `truecolor` / `256` its section's tone in **Working** and **Done** too |
+| 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 stale, and in 16 colours also when an agent glyph sits in column 2 (`▸` + `○` is a long tool call, not a stuck lane) |
 | 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 |
+| 35 | `×` close, on unregistered sessions only: it asks ` › close ‘name’ — y⏎ confirm · Esc cancel` first; `y` arms (` — ⏎ confirm`), `Enter` 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
@@ -52,8 +54,11 @@ session laid out after Task 26: an existing phone device keeps the old picker pa
 (`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-1531). 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
+STARTS needing you (`◆` `✗` `◇`) raises one desktop notification, `name: task`, through OSC 9 — once per entry into
+Needs you (keyed on `agent.stable_since`, so a word that moves inside the section — input, approval, input again —
+is not news; from a statusd older than cockpit v3 S1, once per status as before),
+never for the lane this pane shows, never on a phone, and not at all for a device whose `devices/<device>.json` says
+`notify: "0"` (`lanes attach DEVICE --notify 0`, live) or, without that key, 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
@@ -61,9 +66,19 @@ notification is a silent no-op and nothing else changes. Mac check: not yet run
 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
+dimmed while the footer warns that status is old). Sections: **Needs you** (◆, ✗, ◇ — most urgent first, then in the
+order the lanes entered the section), **Working** (entry order), **Done** (newest entry first), then the workspace's
+other lanes under its own header. Once any lane of the workspace runs an agent, the Needs you and Working headers are
+always drawn, `(0)` included (an empty header's glyph is dimmed; a header with lanes says its words in its section's
+tone in `truecolor` / `256`), so a lane moving between them adds or removes no
+header row; Done only while it has a lane; without agents the list is the plain one. A filter flattens the sections
+and keeps column 2. The order key is `agent.stable_since`, never `agent.since` (which restarts on every status change
+inside a section — cockpit v3 S2, DEF-1811); ties by registry position. A lane moves UP a section at once and DOWN only after the
+lower word has held for 8 s (leaving Needs you) or 5 s (leaving Working or Done); a lane whose agent signal vanishes
+keeps its glyph 5 s — `lanes-statusd` debounces before it publishes (`agent_state.settle`; `agent.raw_status` in
+`status.json` is the undebounced word, `agent.stable_since` when the lane entered its section). The list does not
+scroll when a lane changes section above the cursor: the cursor goes with its lane, and the list moves only when that
+lane would leave the pane (`top` is pinned). 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
@@ -102,7 +117,23 @@ 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.
+To undo registration, press `u` on the lane in the sidebar or run `lanes unregister <lane-id>`
+(`registrations.unregister`: the record leaves `sessions` under the registry lock and the registry is republished;
+the terminal keeps running and is listed under Unregistered again with the same id, its name handed back through
+`user-sessions/<id>.json` and the workspace and id it was registered under through `handback/<binding digest>.json`,
+which statusd's first listing of that session reads — so it stays in the same workspace under the same id even when
+its directory now belongs to another one). `z` in the sidebar within 10 s restores the record byte for byte
+(`registrations.reregister`, which re-checks the session's tmux identity exactly as registration does and refuses
+a session closed and re-created under the same name meanwhile). While tmux gives no usable answer for the session (a
+timeout or connection error on a busy host) the unregister is refused, nothing written:
+` Session could not be checked; nothing was unregistered` — retry once the host has breath. If saving succeeded and
+handing back or publishing then failed (a full disk), the message is ` Unregistered; run lanes sync to finish
+publishing: …`; `z` still restores the record (and publishes), otherwise `lanes sync` finishes it, and the CLI prints
+the `lanes register` undo for once the session is listed again. A record no workspace lists any more (its workspace
+left the catalog or uses another container, or a repository declares the binding: `lanes sync` reports or ignores
+it) is removed by `lanes unregister <its id>` as well, without asking tmux. Removing the record by hand and running
+`lanes sync` still works. A repository lane is unregistered by editing its `terminals.json` (the sidebar and the CLI
+name the file).
 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.
@@ -155,18 +186,99 @@ lanes sync              re-read registries now        lanes ls [--json]   lanes
 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, with owners   lanes device forget <name>   stop recreating one
+lanes device claim <device> --login L   own a device from before enrolment   lanes user list | show <login>   profiles
+lanes workspaces hide|show|order <id…> --device D | --login L   a person's boards   lanes lane pin|unpin|hide|show <id> …   lanes
+lanes here <device>     show there the lane its owner opened last on another device (lanes-launch here from a client)
 lanes keys list         who may log in (members/)   lanes keys add <device> <file.pub|->   authorize a machine
-lanes keys revoke <device>   remove one machine     lanes keys adopt [--dry-run]   move hand-added lanes: keys in
+lanes keys revoke <device>   remove one machine     lanes keys adopt [--dry-run] [--login L]   move hand-added keys in
 lanes invite <name> --email ADDR   one-time join code (own terminal)   lanes invite list | revoke <id>
 lanes enrol list        open access requests      lanes enrol approve <id> | deny <id>   decide one
 lanes offboard <device> --yes   key, device, view (own terminal)   lanes token revoke <view>   sign a browser out
 lanes onboard <login> --container <name> [--workspace <id> --repo <path>] [--write]   a user's container, dry run first
 systemctl --user status lanes-statusd lanes-sync.timer lanes-ensure.timer lanes-web lanes-enrold
+lanes update --status   the last update and the last check (update/last.json)   lanes update --now   check and install now
+lanes update --rollback the release before again, the one left marked bad   systemctl --user status lanes-update.timer
 lanes studio-host status [--check]   the optional co-located Studio Host
 lanes studio-host re-key --yes       after the owner revoked the Host: a new machine key for the next deploy
                                      (refused while lanes-sharing-host or throttle-rc-studio-host still runs)
 ```
 
+- **A server update (W9 U2):** `npx @vibelord/lanes@<release> --server --update-only` (from a checkout:
+  `./install.sh --server --update-only`). One line per phase and step on the terminal (or in the journal), then the
+  outcome; the full output is `~/.local/state/lanes/update/last.log`, the outcome `update/last.json`. Read it with
+  `python3 -m json.tool ~/.local/state/lanes/update/last.json`: `result` `ok` (a step with `"warning": true` — `sync`
+  exiting 1 for a board with an error, e.g. a removed container — needs the board fixed, not the update: `lanes sync`
+  names it); `partial` (exit 4) — the release is installed and a step after the switch failed: each step with a
+  non-zero `rc` is the one to run by hand (`sync` → `lanes sync`, `restart lanes-statusd` →
+  `systemctl --user restart lanes-statusd.service`, `install-container <c>` → `lanes install-container <c>`,
+  `reload-views` → `lanes reload-views`, `ensure` → `lanes ensure --if-layout-changed`); `refused` (exit 3) — nothing changed: the last step names what said no
+  (`preflight`: a prerequisite, the user manager or Docker, or no installed release — `no release is installed here`:
+  run the full `./install.sh --server` / `npx @vibelord/lanes@<release> --server` first; `commit`: another install
+  holds `~/.local/share/lanes/.install.lock`, or a link is no symlink). A run that printed only
+  `refused: another lanes update is running (pid N, since T)` found the run lock `~/.local/state/lanes/update/.lock`
+  held and recorded nothing — `last.json` is the other run's; wait for pid N to end (`ps -p N`), then run it again.
+  `failed` (exit 1) — nothing was installed (a download or a checksum, `binaries`). A `commit` step with a non-zero
+  `rc` and result `partial` means the switch happened but nothing was restarted: fix what the log names (the
+  `~/.local/bin/lanes` link), then run the update again. `rc` 124 is a step stopped after 300 s.
+- **Automatic updates (W9 U3):** `lanes-update.timer` runs `lanes update --timer` 15 min after a boot, then every
+  30 min; `journalctl --user -u lanes-update.service` shows each run (the check, then the installer's lines). Only the
+  full server install enables the timer — an update (`--update-only`) enables nothing — so a server set up before
+  1.2.0 and updated since with `--update-only` has it off: `lanes doctor` says `⚠ updates: … lanes-update.timer is not
+  enabled` (`systemctl --user is-enabled lanes-update.timer` says `disabled`); fix it with `systemctl --user enable
+  --now lanes-update.timer`, or one full `npx @vibelord/lanes@latest --server`.
+  `lanes update --status` prints `update/last.json`; its `check` is the last check and `check.outcome` says what came
+  of it: `current` (the newest release is installed), `older` / `bad` (the tag names an older release, or the one a
+  rollback left: not installed, by design), `unanswered` (the registry gave no release: `check.said` has curl's line —
+  a network or registry outage, or with `channel=stable` no `lanes-stable` tag: `npm dist-tag add
+  @vibelord/lanes@<release> lanes-stable`), `refused` (`~/.config/lanes/update.conf` names a channel other than
+  `stable` or `latest`), `installing` (an install that is running, or one that was stopped: read `last.log`), `installed`
+  (npx ran the installer; the record's own `result` says how it ended, as in the bullet above) or `failed` (nothing was
+  installed: no recorded npx or one that is gone — run `npx @vibelord/lanes --server --update-only` once from a shell
+  whose npx works, which records it again in `update/npx` — or npx ended before the installer recorded a run: the
+  journal has npx's own error). A `partial` result is run again by the next timer tick, once per release (`rerun` names
+  the release); after that the unit fails each tick until `lanes update` by hand ends `ok`. A run that prints
+  `another lanes update is running` or `refused: another lanes install is running` did nothing: wait for it.
+  `lanes update --rollback` goes back to the release `current.previous` names, without the network, and marks the one
+  left `bad` (`check.outcome` `bad` from then on for that release); `lanes doctor` names the mark. The mark is written
+  with the record of the flip (`result` `partial`, steps `[rollback]`), before the post-commit: a rollback stopped in
+  its post-commit (Ctrl-C, a dropped SSH session; its exit is 130/143/129) keeps it, and the next timer tick — or
+  `lanes update` by hand — runs the post-commit again and does not install the release left. A checkout server is
+  never touched by the timer.
+- **`lanes reload-views`:** asks each viewport to start again from the installed release at its next lane switch
+  (SIGUSR2, only to a `view.sh` that handles it); it names the devices whose viewports run an older `view.sh` — which
+  that signal would end — and leaves them alone: `lanes rebuild <device>` moves them. Agents are never touched. Two
+  checks decide, both required (`bin/lanes` `cmd_reload_views`): the release of the tree the viewport RUNS is 1.2.0 or
+  later (`VIEW_RELOAD_SINCE`, the first release whose `view.sh` traps USR2; `view_tree` reads the script file the
+  shell holds open under `/proc/<pid>/fd` — resolved when it started, so a `current` path names the tree it named
+  then, not the one an update or rollback flipped it to since — else the command line's path; `view_reloads` compares
+  that tree's VERSION as major.minor.patch, and a tree with no VERSION or `dev` never qualifies), and the process has a
+  USR2 handler installed now (SigCgt in `/proc/<pid>/status`).
+- **`lanes ensure --if-layout-changed` (W9 U6), the update's last step:** compares each running view's
+  `layouts/<device>.kdl` with the layout the installed release generates. Only a tab both still have counts, line for
+  line, plus the tab template: a tab `lanes sync` added, renamed or moved since the view was built is no change
+  (upgrade-session does that live). A changed view is rebuilt when `zellij -s <device> action list-clients` lists no
+  client (`<device>: its layout changed and no client is attached: rebuilding it`); with a client, or when zellij does
+  not answer, it keeps running and gets `~/.local/state/lanes/clients/<device>.update-ready` (`… left running, its
+  sidebars offer update ready · reload (r)`). The sidebar looks for that file every 30 s and shows ` update ready ·
+  reload (r)` in the footer; `r` then runs `lanes rebuild <device>` (the window reconnects). `lanes-ensure.timer`
+  compares a stamped view again every minute and rebuilds it once its last client has left; a layout that is current
+  again (after `lanes update --rollback`) drops the file. A view that cannot be rebuilt is named and the run exits 1
+  (the update records `ensure` failed: run `lanes ensure --if-layout-changed` again); the other views are still done.
+  A rebuild ends the view's Host tab shell like `lanes rebuild` does; lanes are never touched.
+- **The view-session lock (DEF-1792):** `~/.local/state/lanes/locks/sessions.lock`. Whatever lists the view sessions
+  and then creates, kills or deletes one holds it from that list to its last zellij call: `lanes ensure` (the whole
+  run), `lanes rebuild` (also the sidebar's `r`), the create of `lanes attach`, `prepare` and `web`, the end
+  `lanes offboard` gives a view, and `lanes device forget`. So no `ensure` finds a view missing while a rebuild has
+  killed it and not yet created it again, and starts a second one. A run that finds it held prints
+  `lanes: <who> (pid N, since <UTC>) is acting on the view sessions; waiting up to N s`. `ensure
+  --if-layout-changed`, `rebuild`, `prepare`/`web`, offboard and `device forget` wait 120 s, then exit 1 (offboard:
+  its step `failed`) naming the holder; run them again. The minute timer's plain `ensure` waits 10 s and then skips
+  the run (`ensure: skipped: …`, exit 0); `attach` waits 10 s and then attaches without creating anything. A lock that
+  stays held: `cat ~/.local/state/lanes/locks/sessions.lock` names the process (`{pid, doing, since}`; empty when
+  nobody holds it). The lock dies with its process. Unit ordering cannot do this: `After=` orders only jobs queued
+  together, `Conflicts=` would stop a running update, and `lanes rebuild`, the sidebar and an update by hand are no
+  units.
+
 - **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
@@ -183,6 +295,25 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   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-1540).
+- **What `lanes doctor` says about the release that runs (W9 V3, LNS-85), after an update:** four lines (five with the
+  information line below) just before `PRESSURE`. `current → pkg/1.2.0 (1.2.0), the release this lanes runs` — else a
+  `✗` (the link names a missing tree, one without `VERSION`, one whose `VERSION` disagrees with its `pkg/<version>`
+  name or npm stamp, or not the tree this `lanes` runs: run `~/.local/share/lanes/current/bin/lanes`; re-run the
+  server installer when `~/.local/bin/lanes` is the old one), or a `⚠` without the link. `processes run the current
+  release` — a `✗` names each process that runs now (doctor's one `ps` sweep, this account's processes, by the argv
+  Lanes starts them with: `python3 -S -E <tree>/libexec/<script>`, read from `/proc/<pid>/cmdline`; an editor or a
+  grep on the file, or a one-shot such as `statusd.py --once` or `notify.py --test`, is no daemon, DEF-1785) with an
+  older run record or none at all (`statusd runs without a run record (started by an older release)`), with
+  `systemctl --user restart lanes-<name>.service` or `lanes rebuild <device>` for a sidebar; when `ps` did not answer,
+  every daemon's older record counts. A record whose process is not running is an information line (it stays until
+  the process starts again; studio_host's is always that: it records a oneshot step). There is one sidebar record, the newest sidebar's: an older sidebar still open on another device shows up
+  through that device's layout line, not this one. `view layouts run the current release` — a `✗` names each device
+  whose `layouts/<device>.kdl` runs another tree (`lanes rebuild <device>`), a `⚠` each one that names the current
+  tree by another path than `lanes rebuild` writes now (since 1.2.0 a layout names `~/.local/share/lanes/current`; one
+  built before names its `pkg/<version>` tree, which the next update leaves it on). `✓ lanes units run the current
+  release (N units)` — a `✗` counts the units whose `ExecStart` runs another tree (units name `current` since 1.2.0, so
+  only units an older installer wrote, naming their tree itself, stay behind), or names none (edited by hand): re-run
+  the server installer.
 - **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
@@ -190,7 +321,8 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   each device, phone or desktop (viewports), its owner's login (blank for none) and whether its view session runs.
 - **Who a device belongs to (W8 A2):** `~/.local/state/lanes/members/<device>.json` records, beside the key, the
   owner `{login, name, email}` (the tailnet login; `null` for a key added with `lanes keys add|adopt`), `via`
-  (`invite`|`request`|`manual`), `approved_by`, the `invite_id` or `request_id` and the `workspaces`. A device's view
+  (`invite`|`request`|`manual`), `approved_by`, the `invite_id` or `request_id`, the `workspaces` and, for a device
+  that enrolled, the `client_version` its installer sent (W9 K1; absent when it sent none). A device's view
   session records that owner in `devices/<device>.json` when it is created (`lanes attach`, `prepare`, `web`, or
   `ensure`/`rebuild`) and `lanes attach` brings it up to date — for a window such as `mac-2`, whose base `mac` attach
   learnt, the owner of `members/mac.json`. Whenever such a member record exists it decides, also when it names nobody:
@@ -199,7 +331,20 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   the next attach or recreation (DEF-1702). After a revoke with no new record, the last owner is kept like `base`
   (`lanes device forget` clears it with the file); a member file that cannot be read is no evidence of another
   owner, so the recorded one stays too. Writing a member never creates `devices/*`: `lanes ensure` would build a view
-  session for it. A member file whose owner, `via`, ids or workspaces do not validate (a control or format character
+  session for it. A view no member record speaks for (a device from before enrolment) gets an owner with
+  `lanes device claim <device> --login <login> [--name N]`: it writes `owner` into `devices/<device>.json` and into
+  its windows' files (views whose recorded base is the device and that have no member record of their own), where
+  every rewrite keeps it while no member record exists, then folds those views' look and opened-lane marks into the
+  person's profile `users/<login>.json` (their theme, colour and glyphs leave the device files). A member record
+  decides whenever one exists: a claim that disagrees with it (another login, or a key added by hand that names
+  nobody) is refused with `lanes keys owner <device> <login>`, one that agrees writes no owner and only folds; a
+  member file that does not load refuses the claim too. Exit 1 when the profile could not be written (its lock was
+  busy, or a newer release wrote it: `lanes user show <login>` says why); the device's owner is recorded and the same
+  claim finishes the fold — with or without `--name`: a view the login owns already keeps the name (and email) it
+  records unless `--name` replaces the name, so running a claim again rewrites nothing. `lanes keys adopt --login` and `lanes keys owner` fold the devices they name the same way.
+  `lanes doctor` names the devices without an owner (⚠, never ✗); `lanes user list` prints each person with their
+  devices, `lanes user show <login> [--json]` one profile (read-only; exit 1 for a profile file this release does not
+  read). A member file whose owner, `via`, ids or workspaces do not validate (a control or format character
   such as a bidi mark or a zero-width space, a lone surrogate, a blank in a login, an `invite_id` on a request) is not
   rendered into `authorized_keys` and is named, like a bad key.
 - **Who may log in (`lanes keys`, W8 A1):** client access is a projection of `~/.local/state/lanes/members/<device>.json`
@@ -221,7 +366,8 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   authorized and says so; the same `add` again renders the line. `lanes keys list` shows each member with its
   fingerprint (the `SHA256:` form sshd logs on `Accepted publickey`), whether the block is in sync with `members/`, and
   hand-added `lanes:<device>` lines outside it. `lanes keys adopt [--dry-run]` moves those plain hand-added lines into
-  `members/` and the block, and re-renders the block; a line with options, another key type, or a device/key conflict
+  `members/` and the block, and re-renders the block (`--login <login>` records that owner on every key it moves in; a
+  member that exists keeps its own); a line with options, another key type, or a device/key conflict
   stays where it is and is named, and the first adopt keeps `authorized_keys.bak-<UTC>`. Malformed markers refuse every
   verb before anything, `members/` included, is written (fix the file by hand); a member file that does not validate is
   not rendered (fail closed) and is named on
@@ -238,28 +384,174 @@ lanes studio-host re-key --yes       after the owner revoked the Host: a new mac
   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.
+  Since W9 U4 it also prunes the server's old npm-staged trees (the npm installer prunes only a machine without
+  `~/.local/share/lanes/current`): in each folder of staged trees (the one `current`'s tree is in, `current.previous`'s,
+  the running `lanes`'s, `$LANES_PKG_ROOT` or `$XDG_DATA_HOME/lanes/pkg` when set, and `~/.local/share/lanes/pkg`) the
+  3 newest by mtime stay, and so does every older tree `current` or `current.previous` names, the running `lanes` came
+  from, a `layouts/*.kdl` names, a running daemon's `run/<name>.tree` names, or a process of this account uses
+  (`/proc/<pid>/cmdline`, `cwd`, `exe`, `fd/*`; none is pruned when `/proc` cannot be listed). A tree is renamed to
+  `.pruning-<version>-…` before it is removed, so a removal cut short never leaves a half tree under its version name;
+  the next run removes the rest. `kept <tree>: <why>` says what holds an old tree (`process <pid> uses it`: look at that
+  process; `the view layout of <device> names it`: `lanes rebuild <device>` moves the view to `current`).
+- **What a container sees of its own lanes (`~/.lz/status.json`, LNS-32):** statusd writes each container's slice of
+  `status.json` into that container's `~/.lz` (only where `~/.lz/bin/lane` is installed), on a change and at least
+  every 15 s. Inside the container, `python3 -c 'import json,time; d=json.load(open("/home/coder/.lz/status.json"));
+  print(round(time.time()-d["at"]), "s old", len(d["lanes"]), "lanes")'`: much older than 15 s means statusd is not
+  writing there. No file = no lane contract (`lanes install-container <name>`), or a failure statusd logs once per
+  distinct error: `journalctl --user -u lanes-statusd | grep 'container status'` (`NotADirectoryError` or
+  `Too many levels of symbolic links` = a symlink where `~/.lz` or a directory above it should be, which is refused,
+  never followed: make it a real directory). `lanes sync` refuses such a `~/.lz` the same way for the registry
+  projection: it prints `! container <name>: ~/.lz is not a real directory (…)` and exits 1, every other projection is
+  still published, and that container's `lane open` keeps its previous `registry.json` until it is fixed (DEF-1796).
+  A register or rename that publishes (Add to workspace, sidebar `R`, `lanes register`, `lanes rename`) reports the
+  same refusal at once instead of leaving it to the timer sync's journal: `… saved; run lanes sync to finish
+  publishing: container <name>: …` (the CLI exits 1; the sidebar adds or renames the lane and shows it in the footer).
 - **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`.
+  write) and syncs; the lane id, its resolve file and Cursor's `lane open <id>` stay the same. That host override wins
+  over the repository's own `lanes.terminals[<name>].displayName` in its `terminals.json` (LNS-33), which rename never
+  writes. Renaming back to the lane's default (that `displayName` when declared, else the terminal's own title)
+  removes the override. A `displayName` another lane on the board already answers to (its title, override or own
+  `displayName`) is dropped without a board error, so renaming one lane onto another lane's repository name moves
+  that lane back to its title until the override goes. `lanes cursor-sync` carries `displayName` unchanged. 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
+  refused on any lane that is already registered — a repository lane or an added session — and the writer also refuses
+  a session the file itself already binds under any terminal name (`lanes_lib.declared_tmux`, as `build_registry`
+  reads it): ` Already declared as 'name'; lanes sync lists it`, nothing written. The registry lists a promoted session
+  only after the next sync, so until DEF-1762 a `P` on another device, or on this one after its row let go, declared a
+  second terminal bound to the same session and the sync built two lanes for it. It asks the name first
+  (` › Register as: name█`, prefilled; `Enter` accepts — the terminal is declared under that name), then confirms in
+  the footer's one confirmation shape: ` › register ‘name’ — y⏎ confirm`, `y` arms (` › register ‘name’ — ⏎
+  confirm`), `Enter` writes; any other key — an arrow and a click included, as at a close — cancels. The name
+  reaches `session_actions.promote_to_registered(…, name=)`, which returns the id sync is expected to give the lane
+  (`promoted_id`: `lanes_lib.lane_id_for` over the repository prefix + the name). The sidebar starts `lanes sync`,
+  keeps its handle, and does NOT reload: the row stays in Unregistered under its old id with the new name and the
+  `pending` mark (`Sidebar.pending` old id → expected id; `pending_rows`) — kept even when one status.json omits it, and
+  also when the sync cannot be started (statusd's hot sync starts one on the changed file) — until `reload()` sees the
+  registry list a lane holding the session's binding (`settle_pending`; the binding decides, since sync suffixes an id
+  the board already has with `-2`), and the cursor on the row lands on that lane. Not listed after `PENDING_S` with the
+  sidebar's own sync ended (`expire_pending` on the tick, which `poll()`s and reaps it): the mark goes, ` ‘name’ not
+  listed yet — lanes sync`. `PENDING_S` = 80 s is the latest a sync can still list it, summed from the bounds where they
+  are enforced: the sidebar's sync can find the lock held (the 2-minute timer's sync on a slow docker daemon) and end
+  after `lanes_lib.REGISTRY_LOCK_S` (5 s) with nothing published; statusd starts the next at its first post-cycle check
+  `HOT_SYNC_EVERY_S` (10 s) admits — after its slowest pause (12 s) and one cycle that can hold a docker inspect
+  (`lanes_lib.DOCKER_INSPECT_S`, 20 s) and a probe round (7 s) — and that sync waits for the lock and docker again
+  (25 s); + 6 s for the files. It was 30 s until DEF-1762, which a slow docker overran. While pending the row takes no
+  verb but open (` registering ‘name’ — a moment`). `a` keeps the cursor on the session it registers; Esc / Cancel in
+  the picker put it back on the session (`cancel_registration`).
+- **Slow verbs run on the sidebar's worker thread** (cockpit v3 S9, DEF-1763): the close (`session_actions.close_session`:
+  up to `lanes_lib.REGISTRY_LOCK_S` = 5 s for `registry.lock`, then up to three tmux answers of 5 s), `P`'s write
+  (`promote_to_registered` and the `lanes sync` spawn, `sidebar.promote_job`) and New shell (`session_actions.new_shell`:
+  `docker exec` up to 15 s) used to run inside the key's handler and froze the frame for as long. `sidebar.Worker` is
+  one daemon thread, started by the first such verb, serial (two closes never contend for the lock inside one
+  process); a job's backend is bound when the key is pressed and the job never touches the sidebar's state. The answers
+  go to a `queue.Queue` that `run()`'s tick drains without waiting (`Sidebar.finish_actions`, after `reload()`, before
+  `expire_pending()`) — so an answer shows within one tick (≤ 1 s, or at the next key). `Sidebar.actions` maps a job's
+  key (the row's id, or `<ws>--new-shell`) to what it acts on: the row carries the `pending` mark (`closing_rows`,
+  S8's `promoted_rows`, the New shell row) and `still_pending` refuses every verb there — ` closing ‘name’ — a moment`,
+  ` registering ‘name’ — a moment`, ` creating a shell — a moment` — keeping the keyboard; a row being closed refuses
+  to open too. A close and a `P` hand the keyboard back at the `Enter` (S3). The close's session lives until the
+  worker's kill, so `close_lane` first points every viewport of this view that shows it at `!empty` (`empty_views`,
+  `sidebar.EMPTY_VIEW` — the target `clear_viewers` writes — via `lanes_lib.show_lane`, which wakes view.sh): the
+  hand-off lands on view.sh's `No lane selected` screen, whose wait discards keys, never in the shell being killed
+  (S9 fix cycle 1, DEF-1767; before S9 `clear_viewers` ran before `release_focus`). `clear_viewers` still empties other
+  devices' views after the kill; a refusal points each viewport still at `!empty` back at the session (`closed`,
+  `give_back`). A target that cannot be written (a full disk) refuses the close at the `Enter` — nothing handed to the
+  worker, the keyboard kept — and a give-back that cannot be written leaves the view on `No lane selected`. A new
+  shell keeps the keyboard and is opened by its answer only while the keyboard is still on the sidebar (`keys_here`),
+  nothing is open there, and its viewport still shows what it showed at `+` — else it is listed and the cursor moves
+  onto it from the New shell row. A shell statusd has already listed by the tick that takes the answer (that tick's
+  `reload()` runs first) is that row — matched by binding (`listed_row`), its observation kept — never a second one
+  (DEF-1767). A `P`'s row is held from the `Enter` (`hold_promoted` with no id yet); its answer adds the expected id
+  and the sync's handle, a refusal lets the row go with the writer's words; `expire_pending` never lets go while the
+  write is out. Any exception a job raises is its answer (` <message>`, or the exception's type): the worker lives on.
+  Lock waits stay bounded where the lock is taken and happen on the worker; the UI thread never waits for the worker.
+  (`a`, `u`, `z` and `R` on an added session still take the lock on the UI thread, bounded by the same 5 s — unchanged
+  by S9.) The process exits with its daemon thread: a sidebar that ends in the middle of a close can leave that
+  session's `resolve.dynamic/<id>` and `user-sessions/<id>.json` behind, as a sidebar killed during a close always
+  could.
+- **The sidebar footer** (bottom-up: footer, rule, strip row, upload strip; spec §4.6) shows ONE line by priority, from
+  ONE `Sidebar.footer_text()` that the phone draws too (cockpit v3 S6; until then the phone showed no Rename, Register
+  as or register confirmation, DEF-1821): the open prompt — the sidebar holds one, `Sidebar.prompt` = `{verb, entry,
+  stage, value, armed}`; a name field ` › Rename: …█` / ` › Register as: …█` (a long name shows its end after `…`), a
+  confirmation ` › close ‘name’ — y⏎ confirm · Esc cancel` / ` › register ‘name’ — …` (`⏎ confirm` once `y` armed it;
+  ` cancel`, then ` · Esc` give way and then the name is clipped before the keys would be) > ` Choose a workspace ·
+  Esc cancels` (phone: `Tap Cancel`) > the filter ` /abc · 3 matches` > the health banner > the version note
+  ` server 1.2.0 · view 1.1.0 — press ?` (cockpit v3 V2: `Sidebar.version_note`, while `current/VERSION` — re-read every
+  30 s by `recheck_version`, never per tick — differs from the VERSION of the tree the sidebar runs; ` — ?` at 36
+  columns; not while an update is ready, whose rung says what to do) > ` ⚠ registry: …` > the last
+  message > the undo offer ` Unregistered ‘name’ · z undo` (`Sidebar.undo`, 10 s after `u`: `UNDO_S`,
+  `Sidebar.expire_undo` on the tick) > ` update ready · reload (r)` (W9 U6: an update changed this view's layout while
+  it was attached — `clients/<device>.update-ready`, looked at once per `UPDATE_POLL` 30 s; `r` rebuilds the view; desktop
+  and phone) > the legend ` ⏎ open · / find · x close · ? keys` (phone: ` Swipe to scroll ·
+  Tap to open`). The last
+  message lasts 3 s (`MESSAGE_S`, measured on the 1 s tick: `Sidebar.expire_message`) or until the next action begins
+  (`Sidebar.begin_action`: open, `x`/`×`, `R`, `P`, `a`/`+`, `u`, `z`, `p`, `h`, `H`, `o`, `/`, `U`, `+`, `r`, `?`, `Tab`, a chord) — never just until
+  a key: a cursor move, typing in a field, `Esc`, a focus report, the theme's OSC 11 answer, a wheel tick or a mouse
+  release leaves it (DEF-1822; DEF-1815 before it kept it from the focus report only). `?` shows
+  the key sheet (`  lanes <current> · view <tree>` first — cockpit v3 V2 — then `sidebar.KEY_SHEET`, 18 lines since R5's
+  `p h` / `H o` and V2's `u z`: the user guide's "Sidebar keys" table in short — companion keys on one line,
+  PageUp/PageDown left to the table — ending with `Ctrl-Alt-l`) in place of the list until the next key; the body of a
+  pane under 24 rows is shorter than the sheet and cuts its last lines. Every key on it and in the guide's table acts in `handle()`, and no other
+  key a keyboard sends does (`test_sidebar.DocumentedKeys`, cockpit v3 S10). 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`).
+  from the status.json already read). Under `LANES_GLYPHS=ascii` every glyph, separator and quote has a seven-bit twin
+  (` > close 'sh' - y+Enter confirm` — `⏎` is the word `Enter`, so `y` and it are joined by `+` — then
+  ` > close 'sh' - Enter confirm - Esc` once armed, and ` Enter open - / find - x close - ? keys`).
+- **Typed text landing in the sidebar** (a sentence became `R`ename, `P` or `x` + `y`): since cockpit v3 S3 the sidebar
+  hands the keyboard back to its viewport after every action that ends (open, close, rename, register, cancel, `Esc`,
+  `r`, closing `?`, a drop, a click that opens no lane) with ONE focus move (`zellij action move-focus right` to the
+  pane's own viewport; on a phone nothing moves — the picker tab keeps the keyboard and only opening a lane switches
+  tabs), and drops the rest of the read the action came in. A prompt, the filter, the armed upload strip and a
+  refused key keep the keyboard; the wheel and a mouse release never move it (they reach the pane under the pointer,
+  focused or not). Close and register need `y` THEN `Enter`. If keys still land in the sidebar, the focus was put
+  there by a click, `Ctrl-Alt-l`, `Ctrl-Alt-/` or `Ctrl-Alt-u`; since cockpit v3 S4 the footer says so while it is
+  there (` ▌ keys go to sidebar · Esc → lane`, from Zellij's focus reports, else for 3 s after a key).
+- **A key typed after leaving a Rename / Register-as name went into the name** (`R`, then `→` or a click on a row, then
+  `j` and `Enter` renamed the session `shj`): fixed in cockpit v3 S6 fix cycle 1 (DEF-1824). No prompt outlives the
+  keyboard: `Sidebar.prompt_sequence` answers every escape sequence under the prompt at either stage — a release, a
+  wheel tick, motion or a cut report is no answer (consumed; nothing scrolls); a press ends the prompt first and then
+  acts (a click on a row opens that lane), except a click on the upload strip beside a name field, which arms the strip
+  and leaves the field; at a confirmation every other sequence cancels too, while a name field types nothing for
+  `→` `↑` `↓` `PageUp` `PageDown` `Shift-Tab` `←` `Home` `End` `Delete` (Enter, Space, `j`/`k`/`J`/`K` and `Tab`
+  already belonged to it). `Sidebar.hand_off` closes any prompt still open, silently, before the focus moves. If a
+  field still survives a lane opening, that sidebar process started before the fix and keeps its code (its wrapper,
+  `libexec/sidebar`, restarts `sidebar.py` only when it exits): `lanes rebuild <device>` starts it afresh.
+- **`Ctrl-Alt-/` or `Ctrl-Alt-u` did nothing:** the chord runs `lanes sidebar-key filter|upload --focused`, which
+  writes `~/.local/state/lanes/views/<device>/<workspace>.sidebar.cmd` only when the active tab has a sidebar that
+  holds the focus after the three lefts (not on Host or a tool tab, not when the focus was in another floating pane);
+  the sidebar acts on it within a second, or at the next key. `lanes sidebar-key filter --focused --device <device>`
+  on the server says what it found on that device's active tab (exit 1 with the reason). A terminal that sends
+  `Ctrl-Alt-/` as the legacy `Esc` + `Ctrl-_` pair never triggers the bind (Zellij 0.45.1 reads it as other keys).
+- **What a paste does in the sidebar:** a bracketed paste is routed by what is open when it arrives,
+  at its place in the read (`Sidebar.pasted`). The armed upload strip takes it as the drop; an open ` › Rename: `,
+  ` › Register as: ` or filter field types it (line breaks and tabs as one space, never `Enter`; other control
+  characters dropped) and keeps the keyboard; with no field open (a confirmation has none) it is a drop.
 - **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. 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>`.
+- **After an update flipped `current` (cockpit v3 U5):** a sidebar started through `…/current/libexec/sidebar` re-reads
+  `current/VERSION` every 30 s (`Sidebar.recheck_version`, through W9 U0's readers: `lanes_lib.installed_tree()` is
+  the `current` link whatever it names now, `lanes_lib.tree_version` its VERSION, first line and control characters
+  dropped for the screen by `sidebar.shown_version`); when it differs from its own tree's, the path it started
+  through now resolves to another tree (`LAUNCH_TREE` vs `lanes_lib.REPO`, a realpath on that tick only) and the
+  sidebar is idle (`Sidebar.idle`: no prompt, typed filter, armed strip, picker, key sheet, half-read paste, worker
+  action, held promotion, undo offer, upload, profile retry or `r` rebuild on its way — W9 U6's rebuild ends the
+  sidebar with its view), it writes `views/<device>/<ws>.<slot>.sidebar.state` (0600) and exits
+  75; `libexec/sidebar` re-executes itself at once from its logical directory (`pwd -L`), so the new tree's wrapper and
+  sidebar run, and `__init__` takes and deletes the state (cursor lane, `top`, seen marks merged, filter). Never from a
+  forced reload, never in the first 30 s of a process (no exec loop), never when the start path is a `pkg/<version>`
+  tree (the footer's version note stays instead — `lanes rebuild <device>`). A full disk writes no state and exits
+  nothing; the next recheck tries again. `view.sh` traps `USR2` before it writes its pid file: the signal only sets a
+  flag, and the next NATURAL exit of its child (the lane's viewer detaching, a `USR1` switch, a status screen's wait)
+  runs `exec "$0" <device> <ws> <slot> [--mobile]` — same pid, the path it was started by (through `current` since U1)
+  — unless that script is gone. A `view.sh` from before U5 has no `USR2` trap: the default action ends it, so only a
+  view whose tree has the trap may be sent the signal.
 - **A new workspace:** `lanes workspaces add <id> --container <name> --repo /home/coder/<repo>` (dry run), the same
   command with `--write`, then `lanes install-container <name>` and `lanes sync`. Sync adds the tab to running views
   (`upgrade-session`). A view with no attached client gets it at its next connection. Without `--write` nothing is
@@ -323,6 +615,9 @@ 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. |
+| Client window: `lanes: the update to <version> did not finish (exit N) — this window goes on with <old>; windows try again in 6 h, or now: npx @vibelord/lanes@<version>`, or `… asking npm for it failed (exit N, <npm code>) …`, or `… no npx and npm (Node.js 18 or newer) …`, or `… not updating by itself: … install-options was written by a newer installer …` | The window's self-update could not install the server's release: before it connects, at most every 6 h, a window whose client is older than the server (`lanes hello --client-version` answered ` update=<version>`) asks npm whether it has that release (`npm view @vibelord/lanes@<version> version --fetch-retries=0`, 15 s) and then runs `npx --yes @vibelord/lanes@<version>` with the remembered install options (10 min; when that runs out, or the window closes, every process of the install is ended, not only npx). npm, the npm wrapper or `install.sh` failed or ran out of time (their own output is above the line; exits 3 and 4 count as installed), npm could not be asked (offline, a proxy, the registry: the code is npm's), no npx with its npm beside it was found on the window's PATH nor through the login shell's profile, or `install-options` has a newer `SCHEMA`. The window goes on with the client it has; the next question comes 6 h after this one (`~/.local/state/lanes-client/checked`). | `npx @vibelord/lanes@<version>` in a terminal (the whole install, on screen; your remembered options are read again) — `lanes-launch update` installs npm's `@latest`, which need not be that release; the `self-update:` lines in `~/.local/state/lanes-client/launch-<target>.log`. `LANES_NO_AUTOUPDATE=1` in the window's environment turns it off. |
+| Every client keeps attaching with `lanes client <old> is older than the server (<version>) — run lanes-launch update`, nothing updates by itself, and `lanes-launch update` changes nothing; the client log has `self-update: the server runs <version>, which npm does not have (yet): not installed` | The server runs a release that is not on npm: a checkout server names its `lanes/VERSION` as soon as it is pulled, which can be before `npm publish` (the publish is an operator gate; CI only packs the package). The windows install nothing and say nothing about it (no client can change it); each asks npm again 6 h after its last question. | Publish that release (`npm view @vibelord/lanes versions` shows what npm has): the clients follow within 6 h, with no step on them. Or keep the server on the published release until the publish. |
+| Joining with an invite: `lanes-install: the server runs <version>, which npm does not have (yet): installing <old> from this package instead`, or `… asking npm for it failed (exit N, <npm code>) …`, or `… no npx with its npm is on PATH to fetch that installer …` | The enrolment-first update (W9 K3): the installer read the server's release from `/enrol/site`, found it newer than the package, and could not fetch that release's installer — it is not on npm (a checkout server names its `lanes/VERSION` before the publish), npm did not answer, or the machine has no npx beside its npm. Nothing was lost: the package that ran installed the client and redeemed the code as before (`server runs <version>: fetching that installer first` before it is that run's hand-over, which installed nothing). | Nothing on the client: a window updates it once npm has the release (`lanes-launch` self-update). If the release is not on npm, publishing it is the operator's step. `LANES_NO_SELF_UPDATE=1` skips the question. |
 | 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. |
 | Linux client, key with a passphrase: `journalctl --user -u lanes-helper` shows `Permission denied (publickey)` | The user manager has no SSH agent (or one without the key). The helper looks up the agent the user manager holds before every login, so an agent the desktop session hands over after boot (GNOME or KDE keyring, uwsm) is used from its next attempt, at most a minute later — the journal then says `upload helper: SSH agent of the user manager: <socket>`. The installer hands one over and the `# >>> lanes agent hand-off >>>` block in the login profile repeats it at each local login, but only when `SSH_AUTH_SOCK` is set there — an agent started later that never reaches the user manager (for example `ssh-agent` from a compositor's autostart) is not seen. | From a terminal whose agent holds the key: `systemctl --user import-environment SSH_AUTH_SOCK` (the helper takes it at its next attempt; `systemctl --user restart lanes-helper` for at once), or re-run `./install.sh`. |
 | `./install.sh --check` warns `upload helper: uploads are off, but the service still runs` | Uploads are off — `install-options` says `UPLOADS=0`, or `--check` was given `--no-uploads` — while `lanes-helper` is still active: an install that turned uploads off could not stop it, or the service was started by hand. | `./install.sh --no-uploads` (it takes away what uploads-off leaves running; a bare `./install.sh` repeats the remembered choice, which may still be `UPLOADS=1`); by hand: `systemctl --user disable --now lanes-helper.service lanes-upload.path` (macOS: `launchctl bootout gui/$(id -u)/ai.beyondwork.lanes-helper`). |
@@ -447,7 +742,8 @@ Coexistence mode can be turned back on at any time with `touch ~/.local/state/la
   (`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.
+  — see "TUIs and the terminal's colours" below. On a device with an owner it goes to that person's profile;
+  `--device-only` keeps it on this device (`lanes-window --dark --device-only w2`).
 - 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`.
@@ -484,35 +780,74 @@ night sky of single-dot Braille "stars". Started with no client attached it pain
   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:
+`docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md` §2.4) and these switches, resolved per device (the
+notification switch `--notify` / `LANES_NOTIFY` resolves the same way, above):
 
 | 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_COLOR` / `--color` | `truecolor` · `256` · `16` · `none` | `truecolor` when `COLORTERM` is `truecolor`/`24bit`, else `256` when `TERM` contains `256color` (fixed xterm-256 colours 16–255, never your palette's 0–15), else `16` (your terminal's own palette); `NO_COLOR` set ⇒ `none` (glyphs only). Inside a view that default is always `truecolor`: see "256 colours inside a view" below |
 | `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`).
+| `LANES_DIM` / `--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`, `--notify N`,
+  `--dim D`) 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. `bin/lanes` `clean_env()` forwards `LANES_COLOR`, `LANES_THEME`,
+  `LANES_GLYPHS`, `LANES_DIM` and `LANES_NOTIFY`, when set, from the shell that creates a session (`lanes attach` of
+  a device without a running session, `lanes ensure`, `lanes rebuild`; cockpit v3 P4, DEF-1577), so
+  `LANES_NOTIFY=0 lanes rebuild DEVICE` silences a device until its next recreation. The device file wins over the
+  environment.
+- The sidebar publishes what it resolved: `clients/<device>.theme` (`dark`/`light`; for `glow` and `view.sh`),
+  `clients/<device>.glyphs` (`unicode`/`ascii`/`emoji`; read by `view.sh`) and `clients/<device>.color`
+  (`truecolor`/`256`/`16`/`none`; the stamp `view.sh` picks its colour set by, with `.theme`, cockpit v3 P3). Each is
+  compared by content whenever the sidebar resolves (start, a device-file change, the OSC 11 answer or its 0.3 s
+  grace), so a stamp an earlier attach left — a light terminal's `light` — is replaced within about a second of the
+  next sidebar start, also when that terminal answers dark (DEF-1775); an equal stamp is not rewritten.
+- In `truecolor` and `256` the sidebar spends the palette: section words in their section's tone with the `(n)` dim,
+  lane names in ink (an identity colour still wins), the age in its section's tone (dim only outside Needs you /
+  Working / Done), the stream glyph in its own tone beside an agent (dim only when stale), and the cursor row on the
+  `selected` background — the `▌` stays, and column 36 is never painted. `16` and `none` look exactly as before:
+  the 16 colours are your terminal's, and its yellow may be unreadable on a light background.
+- 256 colours inside a view are chosen, never detected (cockpit v3 P5). config.kdl's `env` block gives every pane
+  `COLORTERM=truecolor`, and the sidebar reads `COLORTERM` before `TERM`, so the `256color` rule applies
+  only outside Zellij — a `libexec/sidebar` started by hand in a plain terminal; so does `NO_COLOR`, which
+  `clean_env()` does not forward. On a terminal that cannot show 24-bit colour, choose the 256 set:
+  `lanes attach DEVICE --color 256` (live, per device, kept across `lanes ensure` and `lanes rebuild`), or
+  `LANES_COLOR=256 lanes rebuild DEVICE` (the environment of the shell that creates the session, until its next
+  recreation). It is fixed xterm colours 16–255, the `256 dark` / `256 light` columns of `docs/DESIGN.md`, the cursor
+  row's band included; `clients/<device>.color` then says `256`, and the viewport's status screens follow.
+  `--color none` is the glyphs-only look for a view. Proven minus zellij by
+  `test_server_cli.LookEnvironment.test_inside_a_view_256_colours_are_chosen_never_detected`.
 - 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.
+  colour 8 is close to the background (classic Solarized dark) can set `LANES_DIM=2` (or `lanes attach DEVICE
+  --dim 2`) as the escape hatch.
+- From the Mac or Omarchy window: `lanes-window --ascii`, `--light` or `--dark` (with `--device-only`, before an
+  optional suffix: `lanes-window --dark w2`) hands `--ascii` / `--theme light|dark` (and `--device-only`) to
+  `lanes-launch`, which passes them to `lanes attach` — recorded as above: per device on a device without an owner or
+  with `--device-only`, else in the owner's profile, which every sidebar of that person's devices paints within a tick
+  (beneath a device's own `--device-only` keys; above the environment, and above a look a device recorded before
+  its profile existed — `lanes user show <login>` names each device's own look, `lanes device claim <device> --login
+  <login>` folds one from before the profile). `lanes-window --device-only`
+  alone refuses (exit 64). `lanes-launch DEVICE --ascii|--theme T|--glyphs M|--color C|--notify N|--dim D|--device-only`
+  takes them directly, and `--editor E` too (the editor `Ctrl-Alt-e` starts, always per device: `micro`, `hx`, `nvim`,
+  `vim`, or `auto` to take the choice back); 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.
+  `clients/<device>.glyphs` says `ascii` — and a dim hint line. The device's stamps are read on every screen with the
+  shell's builtin `read`, so `lanes attach DEVICE --ascii|--color C|--theme T` reaches the next status screen without
+  a restart. `.color` and `.theme` pick the colour set (cockpit v3 P3): in `truecolor` and `256` of the device's
+  variant the hint is that set's ink-dim and the lead takes the warning's amber; `none` keeps bold only; `16`, a
+  missing stamp, or a vivid `.color` whose `.theme` is not (yet) `dark`/`light` is the 16-colour screen as before —
+  the hint in SGR 90 (never SGR 2) and the lead plain bold. Stuck on 16 colours on a truecolor device? On the server,
+  `cd ~/.local/state/lanes/clients && cat <device>.color <device>.theme`: no `.theme` means the sidebar has not
+  resolved a variant yet. A `.theme` that disagrees with the sidebar beside it for more than a second or two after a
+  sidebar start is a defect (DEF-1775 closed that path), not a stale attach to wait out.
 - 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.
@@ -623,7 +958,7 @@ What each event writes (`agent{}` vocabulary):
 
 | Harness | Event | status |
 |---|---|---|
-| Claude Code | `UserPromptSubmit`, `PostToolUse` | `working` |
+| Claude Code | `UserPromptSubmit`, `PreToolUse`, `PostToolUse` | `working` |
 | Claude Code | `Stop`, `Notification` (`idle_prompt`) | `needs_input` |
 | Claude Code | `PermissionRequest`, `Notification` (`permission_prompt`) | `needs_approval` |
 | Claude Code | `StopFailure` | `errored` |
@@ -645,11 +980,153 @@ Codex 0.160 has no `codex --help hooks`; the names come from the binary. Not yet
 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-1515): after you approve a permission prompt, the lane shows `needs_approval` until the approved
+Known limit (DEF-1571): 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
+reads as waiting for you until it finishes. Claude's `PreToolUse` (cockpit v3) does not close that window — it fires
+before the permission check (a PreToolUse hook may itself allow or deny the call: `permissionDecision` is part of its
+output schema in the 2.1.290 binary) — but it does end a `needs_approval` the turn has moved past at the start of the
+next tool call: after a denied prompt, or an approved call that failed (`PermissionDenied` and `PostToolUseFailure`
+write nothing). 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.
 
+## The agents' MCP entries (`lane-mcp`, on by default)
+
+`lanes install-container <name>` ships `~/.lz/bin/lane-mcp` (with `lane_core.py`) and adds it to both agents in that
+container: `mcpServers.lanes = {"command": "/home/coder/.lz/bin/lane-mcp"}` in `~/.claude.json`, and
+`[mcp_servers.lanes]` with that `command` and `env_vars = ["LANE_ID", "LANE_WS", "TMUX", "TMUX_PANE"]` in
+`~/.codex/config.toml`. `--no-mcp` leaves all of that out.
+Codex starts an MCP server with a cleared environment (its own short list: `HOME`, `PATH`, `USER`, `SHELL`, `TERM`,
+`LANG`…, plus the table's `env_vars` and `env`; MEASURED with codex-cli 0.160.1). Without the `env_vars` line,
+`lanes_whoami` from a Codex lane answers `lane: null` ("no LANE_ID and no TMUX/TMUX_PANE") while `lanes_list` still
+works. A table with our `command` that lacks any of the four names (`codex mcp add`'s, or an earlier hand edit) is
+not "present": the install adds the line, or appends the missing names to a one-line list, and reports `wrote`.
+`install-container` writes nothing through a symbolic link in the container's home (DEF-1798): a link at `~/.lz`
+or one of its directories stops the install with its name, a link at a contract file is replaced, and a linked
+dotfile (`~/.bashrc` from a dotfile manager) does not get the `env.sh` line; the command prints that line to add by
+hand.
+
+- Only a missing entry is written. The file is kept as `<file>.bak-<UTC time>` first and replaced atomically with
+  its own mode (a new file is 0600). The file is re-read just before the write, and Claude Code rewrites
+  `~/.claude.json` while it runs; when the bytes changed, the edit is made once more on the new bytes, and a second
+  change refuses. Run it again then.
+- Left alone, with `! <file>: <reason>` and exit 1, while the other agent still gets its entry: a file that is not
+  strict JSON or valid TOML, an entry named `lanes` that starts something else, a `lanes` server Codex's file
+  defines some other way than its own `[mcp_servers.lanes]` table, or an `env_vars` there that misses a name and is
+  not one line of plain names (a multi-line list, `{name, source}` tables). Remove or fix it by hand, then run it
+  again.
+- On a uid split (this account or the home volume is not uid 1000) no entry is written: the agent could not read
+  the file. Same exit 1 and reason as `lanes hooks install` (DEF-1727). A symbolic link at `~/.claude.json`,
+  `~/.codex` or `config.toml` is refused too, also by `lane mcp install`: from the host it would resolve outside
+  the container. Add the entry to the file it points at by hand.
+- Inside the container: `~/.lz/bin/lane mcp install [--agent claude|codex|all]` prints the diff, `--write` applies it.
+- New agent sessions load the server; a running one keeps its tools. Check from a lane with the agent's own MCP
+  listing (`/mcp` in Claude Code). The server's log is `~/.lz/s/logs/lane-mcp.log` (one line per request, rotated
+  at 1 MiB; never a capture's text, a sent text or a note).
+- Undo: restore the `.bak-*` file, or delete the `lanes` entry (`claude mcp remove lanes -s user` does the same for
+  Claude Code). The whole procedure, Codex included, is "Install, check, uninstall" below.
+
+### Install, check, uninstall
+
+What agents may and may not do through it, and the wire contract, are in
+[ARCHITECTURE "Agent API"](ARCHITECTURE.md#agent-api); how an agent should use it is
+[`skills/lanes-agent-tools`](../../skills/lanes-agent-tools/SKILL.md).
+
+Install, per container (the plan's operator gate 3):
+
+1. On the host: `lanes install-container <container>`, or `lanes onboard <login> --container <container> --write`
+   for a new user. It ships `~/.lz/bin/lane-mcp` with `lane_core.py` and `VERSION`, then adds the two entries where
+   they are missing, each file kept first as `<file>.bak-<UTC time>`. Read its `! <file>: <reason>` lines: an entry
+   it could not write is exit 1, and the other agent still gets its own.
+2. Or inside the container, as the lane user: `~/.lz/bin/lane mcp install` prints the diff to both files;
+   `--agent claude|codex` narrows it, `--write` applies it.
+
+Check, in this order:
+
+1. The [protocol smoke](#protocol-smoke) below: two frames in, two frames out.
+2. A NEW agent session: `/mcp` in Claude Code lists `lanes` as connected, and `codex mcp list` shows `lanes` with
+   `lane-mcp` as its command. A session that was running before the install keeps the tools it started with.
+3. From that session, `lanes_whoami` names its lane. Each start of the server writes a
+   `start lane-mcp <version> wire 1` line to `~/.lz/s/logs/lane-mcp.log`.
+
+Uninstall, per container, as the lane user:
+
+1. Claude Code: `claude mcp remove lanes -s user`.
+2. Codex: `codex mcp remove lanes`, or delete the `[mcp_servers.lanes]` table from `~/.codex/config.toml` by hand.
+3. Instead of 1 and 2, the `.bak-<UTC time>` files written at install restore each file as it was then. Do that only
+   when nothing else in the file has changed since; Claude Code rewrites `~/.claude.json` while it runs.
+4. On the host, every later `lanes install-container <container>` and `lanes onboard` for this container needs
+   `--no-mcp`. Without it, the next install writes the entries again. `--no-mcp` removes nothing by itself.
+5. Optional: `rm ~/.lz/bin/lane-mcp ~/.lz/s/logs/lane-mcp.log*`. Keep `lane_core.py`: `lane` imports it.
+
+Agent sessions started afterwards have no `lanes_*` tools; running ones keep theirs until they end. Nothing on the
+host changes: `lanes sync` and `lanes-statusd` keep writing `~/.lz/registry.json` and `~/.lz/status.json` for `lane`.
+
+### What an agent can change through it
+
+Six of lane-mcp's tools write (LNS-35; the user guide's "Agent tools (MCP)" lists them with their refusals). What
+lands where, and how to take it back:
+
+- `lanes_register`, `lanes_unregister`, `lanes_rename` and `lanes_new` edit a repository's `.vscode/terminals.json`
+  inside the container: one `terminals[]` item and its `lanes.terminals` entry, or one `displayName`. The root
+  `throttle` object, the other terminals and their order stay byte for byte. `lanes-statusd` notices the changed
+  file within a cycle and starts one `lanes sync` (at most one every 10 s), so the boards show it within about 15 s;
+  the 2-minute `lanes sync` timer catches anything else. Undo: `git diff` / `git checkout` the file in the
+  repository — no `.bak` file is written. A lane an agent removed by mistake comes back with `lanes_register` from
+  its still-running session, or the sidebar's `P`.
+- `lanes_new` also starts a tmux session on `lanes-shells-<board>` inside the container: the one client lane-mcp runs
+  without `-N`, with an allow-listed environment (account, locale, `TMUX_TMPDIR`, TERM/COLORTERM as the host's
+  `new_shell` sets them), so a server it starts hands neither a lane identity nor the agent's own variables
+  (`CLAUDECODE`, `CLAUDE_CODE_*`, `ANTHROPIC_*`) to later sessions (DEF-1559, DEF-1802); the new session gets its
+  own identity through `-e`, as the canonical recipe gives it. Check a board's shell server with
+  `tmux -L lanes-shells-<board> show-environment -g` in the container.
+- `lanes_send` types into a lane's active pane: printable text, then Enter half a second later as its own keystroke
+  (DEF-1803), never a control key, and not while the lane's agent is working or waiting for an approval unless the
+  agent passes `force`. When the Enter alone fails, the answer says the text is waiting at the prompt.
+- `lanes_signal` writes the agent's own hook sidecar through `lane-signal` (status, and an optional note shown as the
+  lane's task line). The report stands until the agent's next tool call, prompt or permission prompt; the end of
+  its turn keeps it unless it is `working` (DEF-1801). `cat ~/.lz/state/hooks/<lane id>.json` shows it: `event`
+  stays `lanes_signal` while it stands.
+- Nothing an agent does ends, interrupts or attaches a lane, uploads a file, runs `lanes sync`, `lanes gc` or
+  `lanes ensure`, renames a tmux session, or touches a session added with `lanes register` (`registered-sessions.json`
+  on the host).
+- Every call is one line in `~/.lz/s/logs/lane-mcp.log` with the lane and the outcome; a refusal carries its code
+  (`isError refused=agent_working`), so `grep refused= ~/.lz/s/logs/lane-mcp.log` shows what agents were stopped
+  from doing.
+- From the host, a declared lane leaves its file through the same editor: `session_actions.unregister_lane(<id>)`
+  (the sidebar's `u` and `lanes unregister <id>` on a declared lane, which then start / run `lanes sync`) refuses a
+  symbolic link in the container's home, the last terminal and an adopted session with the codes the tool uses.
+
+### Troubleshooting lane-mcp
+
+| Symptom | Cause | What to do |
+| --- | --- | --- |
+| `/mcp` does not list `lanes`, or lists it as failed | No entry: the install skipped it (`--no-mcp`, a uid split, a foreign `lanes` entry, a file that is not strict JSON or valid TOML), or `~/.lz/bin/lane-mcp` is gone; or the session started before the install | Read the install's `! <file>: <reason>` line or run `~/.lz/bin/lane mcp install` (a dry run), fix what it names, then start a new session. The [protocol smoke](#protocol-smoke) tells a broken server from a missing entry |
+| `lanes_whoami` answers `lane: null` | Its reason says which. Under Codex, a table without `env_vars` (Codex clears the server's environment); outside tmux; a session `lanes sync` or the status daemon has not published yet | `~/.lz/bin/lane mcp install --agent codex --write` adds `env_vars`; otherwise wait one sync (about 15 s) and ask again |
+| A tool answers `contract_outdated` or "newer than this contract" | The host's Lanes is newer than the container's `lane` contract | On the host: `lanes install-container <container>` |
+| `lanes_list` says `fresh` is false | `~/.lz/status.json` has not been rewritten for over 60 s: the status daemon is down or cannot write into this container | On the host: `systemctl --user status lanes-statusd`; `lanes sync` prints `! container <name>: …` for a container whose `~/.lz` it refuses. Until then the states are last known, not live |
+| A write answers `not_in_container` | The lane belongs to another container. Each container's `lane-mcp` sees only its own lanes | Ask a person, or the agent in that container |
+| A write answered success but the boards do not show it after 15 s | `lanes sync` refused the board (`lanes doctor` shows board errors), or the edited file is not one the registry names, which hot sync does not watch | `lanes doctor` on the host; the 2-minute `lanes-sync.timer` retries. `git diff` the terminals.json in the container to see the edit |
+| `lanes_send` answered `tmux_failed` with `changed` | The text was typed but its Enter failed: it waits at the target's prompt | A person presses Enter in that lane, or clears the line |
+| Agents keep being refused | `grep refused= ~/.lz/s/logs/lane-mcp.log` lists every refusal with its code | Each refusal's `human` says what a person does instead |
+
+### Protocol smoke
+
+Two JSON-RPC frames in, two frames out, with no agent involved. In the container, as the lane user:
+
+```sh
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+  | ~/.lz/bin/lane-mcp
+```
+
+It prints two frames, one line each, exit 0 and nothing on stderr. Frame `id` 1 carries `protocolVersion`
+`2025-06-18` and `serverInfo` `{"name": "lanes", "version": <~/.lz/VERSION>}`. Frame `id` 2 lists the ten tools in
+wire order, the same tools `lanes/tests/unit/golden/lane-mcp-tools.json` pins. The list is deterministic: run the
+command twice through `sha256sum` and the two digests match. The log gains a `start lane-mcp <version> wire 1` line.
+No output at all means the server could not start, for example because `lane_core.py` is missing beside it; run
+`lanes install-container <container>` on the host. `test_docs.AgentApi` runs this block exactly as printed here.
+
 ## Economy projection (opt-in)
 
 `~/.local/state/lanes/economy.json` is what each lane costs and how hard the fleet is pushing the Throttle pool:
@@ -746,8 +1223,9 @@ the next poll re-folds today. For a look without the daemon: `LANES_THROTTLE_CON
 same set the sidebar's Needs you section and its OSC 9 use — and one when someone files an enrolment request
 (below). 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), `registry.json` for
-lane names and `enrol-requests/`; the one file it writes is `notify.enrol-seen.json` beside them. It never touches a
-lane, a session, a request or the Throttle daemon.
+lane names and `enrol-requests/` — and, when a lane enters needs-you, the presence files below (`clients/`,
+`devices/`, `members/`, `users/`); the one file it writes is `notify.enrol-seen.json` beside them. It never
+touches a lane, a session, a request, a profile 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
@@ -756,7 +1234,8 @@ 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;
+  `Needs you` to `Needs approval` is news. `agent.status` is debounced by `lanes-statusd` (the sidebar's sections,
+  above): a lane whose agent goes back to work for less than 8 s never left needs-you, so its return is not 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
@@ -768,6 +1247,22 @@ When nothing is sent:
   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-1533).
   Only a phone's own `lanes attach` in the last two minutes counts, like any attach.
+  Since cockpit v3 R7 a person's profile counts too: `users/<login>.json` changed within the window by a desk
+  device (its `updated_by_device`; same desk rule as the seen file) — the sidebar writes the mark of an opened lane
+  there as well, so presence does not depend on `clients/<device>.seen.json`. A phone's write and a change no device
+  made never count. A change is the device's only when it was made AT that device — its sidebar, `lanes attach`,
+  `lanes next|prev`, `lanes here`; the admin verbs `lanes workspaces hide|show|order`, `lanes lane
+  pin|unpin|hide|show` (with `--device`, `$LANES_DEVICE` or `--login`) and the fold of `lanes device claim`, `lanes
+  keys adopt --login` and `lanes keys owner` stamp the profile `cli:<command>` / `cli:migration` (its
+  `updated_by_device`, shown by `lanes user show`), so running one over SSH for somebody's desk device never mutes
+  that person's pushes (W9 review, DEF-1833). Each piece of presence belongs to a person (the device's owner — its
+  member record, `lanes keys owner`, `lanes device claim` — or the profile's login) and is recent within that person's
+  own window: the profile's `notify.quiet_s` when it sets one (0 = never mute my pushes), else
+  `quiet_when_device_active_s`.
+  When the recent presence is one person's alone, that is presence; when it is several people's (a device nobody
+  owns counts as one more), `quiet_when_device_active_s` decides for all of them. No `lanes` verb sets `quiet_s`
+  yet: it is the profile's `"notify": {"quiet_s": N}` (integer 0-86400), written by hand only while no sidebar or
+  verb is writing the same profile.
 
 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.
@@ -802,7 +1297,7 @@ that becomes readable switches the pushes on within one tick and a removed one s
 | `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 (or with the token it held before). Keep the token in that file (`chmod 600`), never in `notify.conf` |
-| `quiet_when_device_active_s` | `120` | presence window above; `0` never suppresses |
+| `quiet_when_device_active_s` | `120` | presence window above; `0` never suppresses — except for the one person present when their profile sets a `notify.quiet_s` of its own |
 | `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:
@@ -965,7 +1460,16 @@ the Zellij source) delivers as that frame plus the query again, so `abc` filtere
 now never puts an Esc and other bytes in one frame: a new query is a lone `Esc`, then at least 60 ms later `/` and the
 text; each edit after that sends only its backspaces and new letters; clearing sends a lone `Esc`. Leaving the picker
 forgets the query and sends nothing, because the lane has the focus by then and an `Esc` can interrupt its agent
-(DEF-1752).
+(DEF-1752; cockpit v3 S5 fixed the same symptom on its own line as DEF-1817, and the main sync kept both detectors).
+Cockpit v3 S5 adds, on top of those frames: the query belongs to the picker it was typed on, so moving to another
+workspace's picker from the Workspaces sheet leaves it behind and that picker's bar starts empty (DEF-1820); the
+clearing `Esc` of an emptied field or of Esc is owed to that picker and sent only while it is the current tab, and a
+picker left filtered gets that one `Esc` the next time it is current, so its list is whole again.
+
+On the picker tab the quick row appears only while the sidebar asks for a key (a close, the Register confirmation, Add
+to workspace), as `⏎ y Esc`; never while a name is being typed (Rename, Register as), where a `y` would land in the
+name (DEF-1819). It follows the picker's pane title (` · › close`), so it shares the title path's open browser check
+(DEF-1531).
 
 **Type here** is a plain text field (it was a password field: iOS showed the secure-entry keyboard and the
 strong-password bar, DEF-1734). A QuickType word arrives whole (composition input — CJK, GBoard — stays the client's
@@ -999,8 +1503,12 @@ a real iPhone in Safari and from the Home Screen —
 7. On a picker tab, type `ab` in the filter, backspace once, type `c`: the picker's footer shows `/ac` (not `/acac`,
    the doubled query) and the list shows the matching lanes; clear the field: the footer is back to `Swipe to scroll ·
    Tap to open`. Filter again and open a lane from the list: the lane receives nothing (its agent is not
-   interrupted), and back on the picker the field is empty.
-8. (Plan Task 26 has landed; DEF-1531 waits on this.) The Workspaces sheet shows each picker's counts. A phone device
+   interrupted), and back on the picker the field is empty and the list whole. Type a filter, open the Workspaces
+   sheet and tap another workspace: its bar is empty and its list unfiltered; go back: the first list is unfiltered too.
+8. (Cockpit v3 S5.) On a picker, tap `×` on an unregistered row: the `⏎ y Esc` row appears, `y` then `⏎` closes the
+   session; with the keyboard open, `P` on an unregistered row shows no quick row until ` › register ‘sh’ — y⏎
+   confirm`.
+9. (Plan Task 26 has landed; DEF-1531 waits on this.) 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-1531), or no counts appear and the check
    says nothing about the title path.
@@ -1171,12 +1679,17 @@ and every member keeps logging in, because sshd reads the block, not the service
 - **Stores** under `~/.local/state/lanes/`: `invites/<id>.json` (minted by `lanes invite`, W8 A4; a redemption adds
   `redeemed_by {device, login, pubkey_sha256}` and `redeemed_at`), `enrol-requests/<id>.json`, `members/<device>.json`
   (via `invite`/`request`; `approved_by` = the approving tailnet login on `/enrol/pending`, `cli[:<device>]@<address>`
-  from `lanes enrol approve`, null for an invite minted over SSH — its `minted_by.login` is null). The invite is used
+  from `lanes enrol approve`, null for an invite minted over SSH — its `minted_by.login` is null; `client_version` =
+  the release the installer sent with the redeem or the request, W9 K1, absent when it sent none or a value that is
+  not 1-32 characters of `[A-Za-z0-9._+-]`). The invite is used
   up before the key is written; when the key cannot be written and the block demonstrably lacks it, the invite and the
   member file are put back (`503`).
 - **Log:** `~/.local/state/lanes/enrol.log` (0600, append-only), one line per attempt —
   `<UTC> <redeem|request|approve|deny|invite|invite-revoke|offboard> <id> <device> <login> fp=<SHA256:…> <result>`,
-  `-` for an unknown field. No code is ever written, not even the id half of a code that matched nothing. Service
+  `-` for an unknown field. A redeem attempt's lines end ` client=<release>` when its body named one (W9 K1:
+  `redeem 7q4k anna-mbp anna@example.com fp=SHA256:… ok client=1.2.0`, a refusal's too); a line written before
+  the body is read (`rate-limited`, and a body refused as `bad-request`, `too-large` or `length-required`) carries
+  none. No code is ever written, not even the id half of a code that matched nothing. Service
   errors go to the journal. A redeem or approval re-renders the whole block from the member files that load, so a
   member file that no longer validates (a hand edit) loses its line — fail closed — and that is logged, one
   `<redeem|approve> <id> <its device> <login> fp=- dropped-member` line per such file before the attempt's own, with
@@ -1185,8 +1698,9 @@ and every member keeps logging in, because sshd reads the block, not the service
 
 **Who approves.** `/enrol/pending` lets in a tailnet login that some member record names as its owner (and, in
 request mode, passes the domain gate). Keys added by hand — `lanes keys adopt` (the plan's bootstrap step) or
-`lanes keys add` — record **no owner**, so after the bootstrap nobody can approve on the web yet. Name yourself on
-one of your own devices, with the login exactly as `/site` echoes it as `caller`:
+`lanes keys add` — record **no owner** (unless adopt is given `--login <login>`), so after a bootstrap without one
+nobody can approve on the web yet. Name yourself on one of your own devices, with the login exactly as `/site` echoes
+it as `caller`:
 
 ```sh
 lanes keys list                                   # find your device, e.g. my-mac
@@ -1318,13 +1832,18 @@ fingerprint and `ok` or `incomplete`.
 - 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 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`).
+- No bind in `zellij/config.kdl` types into a pane (no `WriteChars`; the one `Write` is tmux mode's `Ctrl-b`
+  prefix passthrough). `Ctrl-Alt-/`, `Ctrl-Alt-u` and `Ctrl-Alt-l` walk `MoveFocus "left"` once per possible
+  viewport (with a single left, a key pressed in the second viewport reached a lane); the first two then run
+  `lanes sidebar-key filter|upload --focused` (cockpit v3 S4) and `Ctrl-Alt-↓/↑` run `lanes next|prev --focused`
+  (plan Task 19), each in an invisible floating pane that closes on exit (`tests/unit/test_keybinds.py`).
 - 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/guards.py`, `tests/view.py` (incl. the wide-view key walk: three lefts without wrapping, then
+  `Ctrl-Alt-/`, `Ctrl-Alt-u` and `Ctrl-Alt-l` pressed through the client's pty from each viewport — the verb's command
+  file, the Run pane's focus hand-back to the sidebar, the first letters typed after it landing in the filter, the
+  focus legend — and both chords doing nothing on the Host tab; then `Ctrl-Alt-↓/↑`), `tests/upload_box.py`,
   `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
@@ -1344,11 +1863,23 @@ 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.
+stable tab IDs. It never restarts agents or changes client focus, and closes exactly one
+kind of tab (cockpit v3 R4): the tab of a workspace the device owner's profile hides
+(`users/<login>.json` `workspaces.hidden`), identified by its sidebar/view panes — viewers
+only, the lanes live in containers. The owner's `workspaces.order` orders the boards (an
+unlisted board follows in catalog order); a device nobody owns keeps the catalog. A
+profile that hides every board hides none. A hidden board's tab closes only while another
+workspace tab exists on that device, counted over the tabs it has rather than the boards it
+should show: when the shown boards have no tab yet (one added while no client was attached),
+nothing closes and `lanes upgrade-session` prints `<device>: kept <title> open although
+hidden: …`; the missing tab is added once a client is attached, and the next sync or ensure
+tick closes the hidden one. A reconcile that would show no board at all is refused before
+any change.
 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.
+Per-device file locks serialize a sync with the ensure timer; the view-session lock (`locks/sessions.lock`) serializes
+`ensure`, `rebuild` and every create or end of a view session ("The view-session lock" under "Server").
 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.