@vibelord/lanes 1.0.0

package/payload/lanes/docs/RUNBOOK.md

@@ -0,0 +1,385 @@
+# lanes — runbook
+
+`lanes` is the host-level workspace server for a deployment's container terminals. The canonical source is
+`bw-tools/lanes`; [INSTALL.md](INSTALL.md) covers the full setup and [ARCHITECTURE.md](ARCHITECTURE.md) explains
+its parts. Run host commands as the workspace account. Deployment-specific incidents below retain their
+original names and measurements; substitute your account, containers and paths in operational commands.
+
+## Daily use (client)
+
+| Do | How |
+|---|---|
+| Open the lanes window | `lanes-window` (own Ghostty instance) — or `lanes-launch` inside any terminal |
+| Second independent view (other monitor) | `lanes-window 2` |
+| Wide view: 2 or 3 viewports side by side per workspace | `lanes-window w2` / `w3` (anarchy: `Super+Shift+Alt+L`). In the sidebar `Enter` opens in the first viewport, `2` / `3` open the lane under the cursor in the second / third; `²` `³` mark what they show |
+| One lane, no multiplexer, native Ghostty scrollback | `lanes-launch lane <lane-id>` (ids: `lanes-launch ls`) |
+| Switch workspace | `Ctrl-Alt-←/→` (zellij tabs) |
+| Next / previous lane | `Ctrl-Alt-↓` / `Ctrl-Alt-↑` (works from inside the lane, in a wide view from every viewport; they move the FIRST viewport and focus ends there) |
+| 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 |
+| Scroll a lane | mouse wheel / tmux copy-mode as before (history lives in the lane, not in the viewer) |
+| Throttle monitor | its own full-size tab, `Throttle` (next to `Host`); it starts when you first open the tab and restarts itself if it exits. It is no longer an entry in every board's sidebar. |
+| Detach | `Ctrl-Alt-o` then `d` — or just close the window. Nothing on the server stops. |
+
+Sidebar glyphs: `●` output in the last 20 s · `○` quiet · `–` absent (no such session right now, e.g. a finished
+orchestrator turn) · `!` pane dead · `✖` container down · `?` / a dimmed glyph = not observed right now, last known
+state shown (see "When the host is overloaded") · `👻 unregistered` = an observed tmux session associated with this
+workspace but absent from its registry — nothing alive is ever hidden, and a session whose NAME could not be
+declared (parentheses, `/` and `,` are outside the lane grammar) is listed, opened and closed exactly like any
+other ghost: the grammar governs what may be DECLARED, never what may be SEEN. (`status.json` carries a `note`
+on such a row saying why it cannot be declared; no surface draws it yet.) A session on a socket SEVERAL boards
+declare, whose name claims no board and whose directory is under nobody's roots, is listed by EVERY owner of
+that socket rather than dropped — one id, one row, several sidebars.
+A `·` after a lane's name (up to three) = other sessions VIEW that lane: any session GROUPED onto it, a Throttle
+Studio browser attach (`view-<studio>-<ch>`) included — counted in the lane's `attached`/`viewers` in `status.json`,
+never listed as unregistered (`statusd.viewer_of`; a ghost carries its viewers too, so a browser on an undeclared
+lane is counted there). The `view-` NAME decides nothing: an ungrouped `view-notes`, and a `view-…` whose lane was
+killed under it, are alive and ARE listed — but when a killed lane left SEVERAL grouped survivors, the oldest is
+the lane and the later ones are its viewers, the same choice the Studio makes (`statusd.group_leaders`,
+`inventory::group_leader`). A declared lane is always its own row, whatever it is grouped onto. A Studio lane the
+Studio itself started is `st_<board>_<slug>` on the board's socket and IS shown as `👻` until declared, on a
+socket some board declares or not: discovery probes every live socket in the container.
+
+**Unregistered terminals:** every workspace has an **Unregistered** section, including sessions on shared and
+otherwise unlisted tmux servers. Sessions are associated with their existing workspace or working directory;
+changing directory later does not move a discovered session to another board. **New +** creates a persistent
+shell in that workspace. Reopening it attaches to the same shell, preserving running programs and scrollback.
+The old disposable **Remote Shell** entry has been removed. **×** at the right of an unregistered row (or `x`
+with that row selected) permanently terminates that session and clears viewers showing it. A session other
+sessions are GROUPED onto shares its windows with them, so `×` ends the Studio Host's own `view-…` members
+first and otherwise REFUSES, naming what is grouped on: killing the group leader alone leaves every window and
+process running under the survivor, which returns next cycle as a new `👻` (DEF-981). Registered lanes
+have no close control. `+` creates a shell from the keyboard. New and Close are explicit user actions; discovery,
+reattachment, and reconnects never create or close a session.
+
+Old plain Docker shells recovered during the transition are labelled **Legacy**. They remain tracked,
+including their existing running jobs. A still-connected viewer continues working; after leaving it, the old
+Docker connection has no normal reattach operation. Selecting that entry explains its status, and × ends the
+shell and its jobs. New + shells do not have this limitation.
+
+## Server (as the workspace account)
+
+```
+lanes doctor            full health check            lanes status        per-workspace counts
+lanes sync              re-read registries now        lanes ls [--json]   lanes with live status
+lanes rebuild <device>  recreate a view session       lanes ensure        recreate missing view sessions
+lanes invariant save|check   prove no live pane changed (pid + window size)
+systemctl --user status lanes-statusd lanes-sync.timer lanes-ensure.timer lanes-web
+```
+
+- **A view looks wrong / stuck:** `lanes rebuild mac`. Views are disposable; agents are untouched; the client reconnects.
+- **A lane was added/renamed/removed in a repo's `.vscode/terminals.json`:** nothing to do. `lanes-sync.timer`
+  re-reads registries every 2 minutes and the sidebar follows. The zellij layout is never edited live.
+- **A newer layout added a tab (e.g. `Throttle`):** `lanes upgrade-session` adds it to the live sessions without a
+  rebuild and leaves you on the tab you were on.
+- **A new workspace:** add it to `~/.config/lanes/workspaces/catalog.json` + a manifest, `lanes sync`, then
+  `lanes rebuild <device>` (the only time a layout changes).
+- **Registry invalid:** the workspace keeps its previous lanes; the sidebar footer and `lanes doctor` show why.
+
+## When the host is overloaded
+
+2026-09-19: ceobox thrashed (load 400+ on 64 cores, swap full, memory pressure 68 %); `coder-dev-work` sat at 207 of
+its 208 GiB, 95 GiB of that in its RAM-backed `/tmp`. **No lane was lost** — every pane kept its pid — but the
+harness timed out on its own questions, reported "gone", and the client window closed itself. The rule since then:
+lanes live in the containers' tmux servers and the harness only LOOKS at them; under memory pressure the looking
+fails first. A question that got no answer is never published as "the lane is gone".
+
+### What you see, and what it means
+
+| You see | It means | Do |
+|---|---|---|
+| Sidebar footer `⚠ host under memory pressure · status 3 m old` | The one-line `~/.local/state/lanes/health` (rewritten by statusd every cycle) says `level=busy` or `critical`, or has not been rewritten for 30 s. The sidebar measures that age with its OWN clock, so a frozen statusd shows too. The list above it is the last known state, not a live one. | Nothing is lost. `lanes pressure`. |
+| A lane's glyph dimmed, with `?` | That lane's tmux server did not answer in time: its LAST state is kept and marked stale. A bare `?` = never observed yet. `–` (absent) and `✖` (missing) are only ever shown when the server answered, or positively does not exist. | Wait. The lane is running. |
+| Viewport: **THIS VIEWER DISCONNECTED — the lane's tmux server is still running** | The viewer's tmux client was dropped or could not attach in time; the lane's socket is still there. That is ALL this headline claims: the retry below it is what learns whether the session itself survived, and when the holder then answers `is not provisioned`, nothing says the lane is untouched (a lane killed elsewhere — a Throttle Studio `Stop`, an operator's `kill-session` — leaves the server up, and the old headline claimed the lane still ran, DEF-965). The reason and a health hint follow; it retries by itself. | Nothing, unless the retries keep saying `is not provisioned` — then the lane is gone: pick another in the sidebar. |
+| Viewport status screen WITHOUT that line | The lane's tmux socket is really gone. | "A dead lane, or a blind harness?" below. |
+| Client window: `connecting…`, later a hold screen with a countdown | `lanes-launch` never closes the window by itself. ssh failed, or the server dropped a slow client (zellij does that with exit 0), or the server refused (exit 64–78): it holds, re-attaches when the countdown ends, backs off up to 60 s. `Enter` = now; closing the window = quit. Log: `~/.local/state/lanes-client/launch-<target>.log`. | Leave it open. |
+| Upload box `no upload helper` while windows were closing | The helper is a per-machine service now (launchd `ai.beyondwork.lanes-helper` / `systemctl --user status lanes-helper`) and survives the window. It counts as serving while `~/.local/state/lanes-client/helper.alive` is younger than 90 s. | `./install.sh --check` on the client. |
+| A live test suite prints `SKIP  host is busy: …`, exit 75 | `tests/*.py` refuse to start above load 2 × cores or memory pressure (some avg10) 20 %: they add load and would fail for the wrong reason. | Run it later (`LANES_TESTS_FORCE=1` only on purpose). |
+
+### Look, without adding load
+
+```
+lanes pressure             memory / io / cpu pressure, swap, load, per-container memory (current / max / RAM-backed
+                           shmem) and /tmp fill. Plain files + statvfs: safe on a thrashing host. Exit 1 unless level ok.
+cat ~/.local/state/lanes/health    what statusd wrote last; at= and status_at= are epochs — compare with `date +%s`
+lanes doctor               every external call is bounded; "N shown with their last known state" = blind, not dead
+lanes invariant check      1 s: every live pane's pid and size against the last `invariant save`
+```
+
+Levels: `critical` = memory some avg10 ≥ 40 % or full avg10 ≥ 15 %; `busy` = memory some ≥ 10 %, io some ≥ 25 %, or
+load ≥ 1.5 × cores. While the host is busy: no `docker exec`, no `du`, no test suites, no rebuilds, no server
+rollout — one batched ssh instead of many.
+
+### Free the RAM: `lanes tmp`
+
+A container's `/tmp` is tmpfs: every byte in it is RAM charged to the container's memory limit (`shmem` in
+`lanes pressure`). `lanes tmp` walks it from the HOST through `/proc/<container-init-pid>/root/tmp` — no docker
+exec, no `du`, nice 19, a 120 s budget per run, and the next run resumes where the last one stopped.
+
+```
+lanes tmp plan  [container…]             table, largest first + the plan file. Reads only.
+lanes tmp apply [container…]             lists what the plan would delete (its STALE units)
+lanes tmp apply [container…] --approve   deletes them; each unit is judged AGAIN immediately before it goes
+```
+
+A unit (a top-level `/tmp` entry, or one `claude-<uid>/<project>/<session>`) is kept when ANY of these holds: a
+process has its cwd, an fd or a mapping in it; it holds a socket, fifo or device; something in it belongs to another
+uid; its newest change is younger than 24 h; its Claude transcript was written in the last 48 h; its scan was cut
+short. `tmux-*` and `.lz` are not even walked. A plan older than 6 h, or made for another container start, is
+refused. Everything removed is logged in `~/.local/state/lanes/tmpscan/deleted.log`. The hourly
+`lanes-tmpreap.timer` applies the same rules to what has been idle for 3 days — as a DRY RUN until you arm it with
+`touch ~/.local/state/lanes/flags/tmpreap.armed`.
+
+### The guards
+
+- **`lanes-guard.timer`** (user unit, every 60 s, `lanes guard --once`): raises `oom_score_adj` to 800 on compilers,
+  linkers and test runners inside the containers, matched by exact `comm` from an allow-list, so the next
+  in-container out-of-memory kill takes a build — a build can be re-run, a lane cannot. It only ever raises, never
+  touches node / claude / codex / tmux / shells, and is plain `/proc` writes. `lanes guard --dry-run` shows the pass.
+- **`sudo sh ~/.local/share/lanes/current/sudo/host-guard.sh --user "$(id -un)"`** (root, by hand, once): without `--apply`, read-only status plus what `--apply`
+  would do. `--apply` sets a `MemoryLow` envelope on `user.slice` → `user-<uid>.slice` → `user@<uid>.service`, so the
+  ~1 GiB harness and the login path are not swapped out (a user manager cannot protect itself: its ancestors cap
+  it), and installs a 60 s root timer that LOWERS `oom_score_adj` for tmux servers, agents and zellij servers.
+  `--undo` puts the recorded values back. It never restarts, stops or signals anything. Reasons: `docs/HOST-GUARD.md`.
+- The harness's own units run in `lanes.slice` with a high `CPUWeight`: tiny, but scheduled while the host thrashes.
+
+### NEVER
+
+- Restart or stop a container, docker, or `user@<uid>.service`: every lane dies with its container, every view with
+  the user manager. No symptom on this page is fixed by a restart.
+- Touch `/tmp/tmux-1000` inside a container — by hand, by a cleaner, by a "free space" one-liner. Those are the
+  lanes' sockets: without them every lane is alive and unreachable.
+- `systemd-oomd` on docker scopes · `memory.oom.group=1` (one OOM then kills the whole container) · `swapoff` under
+  pressure · a `memory.max` below current usage (a live OOM sweep) · tightening ANY limit before usage has dropped.
+- Live test suites, `docker exec`, `du` or a server rollout on the busy host.
+- Recreate a lane because the sidebar shows `?`, or because a window showed `[terminated]`.
+
+### A dead lane, or a blind harness?
+
+1. `lanes invariant check`: all pane pids unchanged = nothing died, whatever any screen says.
+2. The glyph: dimmed / `?` = NOT OBSERVED. `–`, `!`, `✖` = observed — the server answered, or does not exist.
+3. `lanes doctor`: "N shown with their last known state (tmux server did not answer)" is the blind case. In
+   `status.json` those lanes carry `"stale": true` and `"observed": "timeout"` or `"error"`, and their server
+   `"outcome": "timeout"`; `absent` / `missing` are published only from `ok` / `noserver`.
+4. The socket: `ls -l /proc/$(cat ~/.local/state/lanes/containers/<name>.pid)/root/tmp/tmux-1000/` — look, never
+   touch. Socket there and the server's pid alive = the lane lives and only the harness is blind.
+5. `health` older than 30 s (`at=` against `date +%s`) = statusd itself is starved: the sidebar shows history.
+
+A lane is dead only on a POSITIVE observation: its server answered without that session (`–`), its pane died (`!`),
+or its container is down (`✖`).
+
+## Switch-over — DONE on this Mac, 2026-09-18
+
+- `coder-launch` is the new client (`coder-launch worlds` opens your view on that workspace's tab). The previous
+  client is kept as `coder-launch-legacy`; `client/install.sh --rollback` (or `./install.sh --uninstall`) puts it back, and the old remote
+  `/home/coder/.config/coder-launch/attach <ws>` would recreate a `cl-<ws>` viewer. Old files are untouched
+  (`~/.config/zellij/coder-launch`, snapshot in `~/.local/state/lanes-migration/snapshots/`).
+- Retired: 12 local zellij sessions + 10 stale ones, `wake-guard`, 13 Coder proxy processes; in the containers all
+  `cl-*` zellij viewers incl. two orphaned duplicates and one wedged client (SIGKILL needed), and `cl-slowfast`.
+  Container memory 212.9 GiB -> ~175 GiB of 208. Every lane pane kept its pid.
+- Coexistence mode is OFF: the view attaches as a normal tmux client and sizes the lane you look at. Other clients
+  of a lane (e.g. Cursor terminals) still take part in tmux's `window-size latest`, as always.
+- Still running on purpose: `/home/coder/.config/coder-launch/session-state.py daemon` (the conversation-id ledger).
+
+Coexistence mode can be turned back on at any time with `touch ~/.local/state/lanes/flags/coexist`
+(viewers then attach with `ignore-size`; tmux honours it only while another normal client is attached).
+
+## Omarchy / Hyprland client (anarchy)
+
+- `Super+Shift+L` opens the lanes window, or focuses it if it is already open (Omarchy's launch-or-focus);
+  `Super+Shift+Alt+L` opens the WIDE view (`anarchy-w2`: two viewports per workspace, made for the 7680-px
+  monitor at full width; a narrow tiled window should use the normal view). Also in the app launcher as "Lanes".
+- Window class `org.omarchy.lanes`: matched by Omarchy's `+terminal` tag, so `Super+C` / `Super+V` send
+  Ctrl+Insert / Shift+Insert (copy/paste) instead of Ctrl+C / Ctrl+V. Links: `Ctrl+Shift+click`.
+- Terminal: Ghostty in a dedicated instance (`~/.config/lanes/ghostty.conf`, inherits `~/.config/ghostty/config`, so
+  Omarchy theme switches follow). Foot stays the system default; without Ghostty the window falls back to Foot with
+  the same class. Install Ghostty only: `omarchy-pkg-add ghostty` (`omarchy-default-terminal` is not touched).
+- 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`.
+- Path: tailnet (`Host lanes`); after two immediate connect failures the client uses `lanes-public` (same sshd,
+  public address, key-only) until the next healthy session.
+- Update: `git pull` in the checkout, then `./install.sh` again. Verify: `./install.sh --check`. Uninstall:
+  `./install.sh --uninstall` (removes the Hyprland line and bind file, the launcher entry, the commands, `~/.config/lanes`,
+  the uploads watcher and the `Include` line — each edited file is backed up first); then on the server
+  `zellij kill-session <device>`.
+- New people: they run `./install.sh` from the package (see `README.md`); it prints their public key, and an admin
+  appends that line to `~dev/.ssh/authorized_keys` on the server. Site facts that should not live in the package
+  (the public fallback address) are served to authorized clients by `lanes client-config` from
+  `~/.config/lanes/site.conf` on the server.
+
+## TUIs and the terminal's colours (Codex's dark box, the "stars")
+
+A program in a lane learns the terminal's background by asking (OSC 11); tmux answers with the colour reported by the
+OLDEST attached client that has one — a Cursor terminal or the lanes window — and answers nothing when no client is
+attached. `tests/colors.py` proves that the lanes path (direct and through the view) hands the real colour through.
+Codex samples this ONCE, at its own startup: started under a dark client it paints a dark input box for the rest of
+its life (unreadable once you look at it in light mode, and the other way round at night), plus — `tui.whimsy` — a
+night sky of single-dot Braille "stars". Started with no client attached it paints no box at all.
+
+- The stars are off: `[tui] whimsy = false` in `~/.codex/config.toml` of both containers (new/restarted sessions).
+- Codex has no setting for the box. To fix ONE session: restart that Codex (`/quit`, then `codex resume`) while you
+  look at it from the window and theme you use. Never restart a working agent for this.
+- It stops recurring when the clients agree on brightness: the same light/dark choice in Cursor's terminal and in the
+  lanes window (Ghostty `theme = light:…,dark:…` follows the OS and therefore flips twice a day).
+
+### "tmux server … is not running" on every lane at once (deleted sockets)
+
+Seen 2026-09-20 04:24: something emptied `coder-dev-work:/tmp`, and with it `/tmp/tmux-1000` — the directory of every
+lane's socket file. All tmux servers and agents kept running; nothing could attach. How to tell: `lanes sockets`
+lists tmux servers without a socket file, the sidebar footer says *lane sockets deleted*, lanes keep their last
+state with a `?`, and the viewport says the lane runs but its socket file was deleted. Fix (nothing restarts —
+SIGUSR1 is tmux's own "recreate the server socket"): `lanes sockets repair`. Views reattach by themselves;
+Cursor terminals need a reopen. Never `rm -rf /tmp/*` in a workspace container; to free its RAM-backed /tmp use
+`lanes tmp plan` / `apply` / `caches`, which never touch sockets or anything a process has open.
+
+## Cursor / VS Code terminals = the same lanes
+
+Cursor uses the Terminals Manager extension, which opens what `<folder>/.vscode/terminals.json` lists. Those files
+stay the source of truth for WHICH lanes a board has (the lanes registry is built from them). `lanes cursor-sync`
+only normalizes HOW a terminal reaches its lane:
+
+- every `command` becomes `exec /home/coder/.lz/bin/lane open <lane-id>` — attach; if the lane is missing, run its
+  recorded create recipe (the repo's original command, kept in a top-level `lanes` block the extension ignores and
+  Throttle Studio's Host only reads, as its `lanes-block` source); refuses to nest inside tmux; holder-agnostic, so a
+  later move to zmx / tmux-per-lane changes no editor config.
+- `lanes cursor-sync` = dry run for all boards (prints diffs); `lanes cursor-sync <ws> --diff` = full diff;
+  `lanes cursor-sync <ws> --write` applies (backup under `~/.local/state/lanes/cursor-sync-backups/`). The repo then
+  shows an ordinary git diff to review and commit. Boards that keep their registry outside a repository
+  are additionally projected into the file Cursor reads (`"cursor"` in `workspaces/*.json`).
+- Size policy "the lanes view wins": lanes-view tmux clients run with `TERM=xterm-lanesview` (a user-level terminfo
+  alias of xterm-256color). While such a client shows a lane, every other client of that lane (Cursor terminals,
+  ad-hoc attaches) is in tmux `ignore-size`; `lanes-statusd` reconciles every few seconds and gives editors the size
+  back once no view shows the lane. This covers every socket `observe` reads, the ones no lane declares
+  included, and both halves apply there: an `ignore-size` an operator set by hand on such a socket is given
+  back like any other once no view shows the lane (DEF-982).
+
+## Throttle Studio as a client
+
+Throttle Studio (`throttle-rc studio host` in a workspace container, the `/workspaces` view of the Throttle console)
+is a second client of the SAME lanes — it owns none of ours. It reads `~/.lz/registry.json` first, then each repo's
+`.vscode/terminals.json` (the `throttle.terminals` bindings and our `lanes` block), then `lane ls --json`, then the
+live tmux servers with `-N`; it never writes any of them, never touches a zmx socket directly, and never sweeps
+`/tmp/tmux-1000`. Its ids are ours (studio = board id, lane = `<board>--<slug>`), its status words are `statusd`'s
+(`active` / `quiet` / `dead` / `absent` / `missing` / `unknown` — those six and no others, zmx lanes included;
+`unknown` is `statusd`'s too: a `list-panes` that exits non-zero or hangs gives NO verdict and is never re-spelled
+`absent`, and one wedged server no longer costs the other boards their `status.json` write. The two daemons SPELL
+that no-verdict differently, and the difference is named: `statusd` republishes the lane's LAST entry marked
+`stale` with `observed: timeout|error` — the sidebar draws the last glyph dimmed with a `?` — and reaches
+`unknown` only with no last observation or after `STALE_MAX` 300 s, carrying `observed`, not a sentence; the
+Studio Host publishes `unknown` at once, with the probe's own sentence. See DM-LANES-STATUS in
+`docs/master-datamodel.md`),
+and the two things it does to a board's tmux server are recognisable:
+
+- **The viewer rule.** A browser attach is a session GROUPED onto the lane and named `view-<studio>-<ch>`.
+  `statusd.viewer_of` treats any UNDECLARED session grouped onto a DIFFERENT session that still LEADS its group
+  as a VIEWER of it, whatever the viewer is named: counted in its `attached`/`viewers`, drawn as the `·`
+  marks, never listed as `👻 unregistered` (`tests/unit/test_alignment.py`). A DECLARED session is always a lane
+  of its own, whatever it is grouped onto — an operator can bind two declared lanes with tmux's own
+  `new-session -t <other-lane> -s <name>`, and filing the second as a viewer published the registry's own row
+  `absent` while its session was alive (`split_viewers`, DEF-914). The Studio mirrors the same pure rule
+  (`tmux::viewer_of`) AND the same declared exemption (`inventory::attached_clients` takes the socket's declared
+  session names; it did not, and published one more client than the sidebar for that listing, DEF-961), so the
+  sidebar and the Studio never disagree about one session. It attaches `ignore-size`,
+  and while a lanes-view client (`TERM=xterm-lanesview`) shows the lane the browser's "take size" is refused with
+  "the lanes view owns the size" — the lanes view wins, from both sides: `reconcile_client_sizes` buckets clients
+  by the lane they SHOW (so a grouped viewer is flagged too) and never strips the `ignore-size` of a client that is
+  BOTH on a grouped session AND named the way the Host MINTS its own — the whole `WebSession::channel_of`
+  grammar (`view-<board>-<n>`, `web-<n>`), which `lanes_lib.is_host_view` mirrors, never the `view-`/`web-`
+  PREFIX: an operator's own grouped `scratch` client must get its size back like any other (DEF-852), and so
+  must a grouped `view-notes` the Host never minted and therefore never un-flags (DEF-980) — over every socket
+  `observe` reads, the DISCOVERED ones included (the reconcile used to visit only sockets registered lanes bind,
+  so a lanes view showing a `New +` shell or a Studio lane on a Host-owned socket never had its later-arriving
+  editor clients flagged, DEF-964; a discovered socket is governed by BOTH halves, so a client an operator had
+  put into `-f ignore-size` by hand on such a socket is un-flagged there too — DEF-964's "changes nothing" was
+  false, DEF-982) —
+  and the Host flags its OWN client and holds the channel in `ignore` when a lanes view arrives later — on ITS OWN
+  view tick, not only when the browser next resizes, and it gives its client the size back (`!ignore-size`) when
+  no lanes view shows the lane, which `reconcile_client_sizes` deliberately leaves to it. Closing the
+  browser tab destroys only its `view-*` session.
+- **Studio-started lanes** are ordinary tmux sessions named `st_<board>_<slug>` on the board's own socket, so
+  they appear as `👻 unregistered` until someone declares them in the repo's `terminals.json` and `lanes cursor-sync`
+  runs. The Studio does not write that declaration. Stopping one from the browser kills its `view-*` members first,
+  then the exact session name — nothing else on the socket. The Stop cannot reach this host's view state (the
+  `!empty` target + `SIGUSR1` the sidebar's own close writes), so a viewport that was showing that lane does NOT
+  end: it falls back to its status screen and retries the gone session (`is not provisioned`, above) until the
+  operator picks another lane — or, with the operator's `detach-on-destroy off`, tmux moves the client to another
+  session on the same socket and the viewport silently shows a different lane. DEF-965.
+
+The Studio's design of record is `docs/design/throttle-studio.md` (§1.1 "The lanes harness", §8.3, §8.5).
+
+## Uploads (the Cursor `uploads/` folder, without Cursor)
+
+Files land in `<board folder>/uploads/` on the server — the same folder you drop into from Cursor. The folder is
+created on first use and kept out of commits through the repo-local `.git/info/exclude` when the repo does not
+already ignore it. Afterwards the in-container path is on your clipboard and in a notification.
+
+| Way | How |
+|---|---|
+| Upload box in the sidebar | Click the box (or `Ctrl-Alt-u` from anywhere in the tab), then **drop the files anywhere on the window**. The file goes to the board of that tab and its path is typed into the lane, ready for the agent. `Esc` cancels. |
+| Watch folder | `~/Lanes Uploads/` → the board your view shows; `~/Lanes Uploads/<board>/` → that board. Sent files move to `.sent/<date>/`. Point CleanShot's save folder here for instant screenshot upload. |
+| Command | `lanes-upload [-w <board>] [--paste] <files…>` · `lanes-upload --clipboard [--paste]` (clipboard image or copied files) |
+| macOS droplet | `~/Applications/Lanes Upload.app`: drop files on it (Dock); double-click uploads the clipboard screenshot |
+| anarchy | `Super+Shift+U` uploads the clipboard and types the path into the lane |
+
+Why click first: a terminal delivers a drop as a *paste of the local path* into the FOCUSED pane (not the pane under
+the pointer), so the box has to hold the focus when you let go. And the server only ever receives that path string:
+the file itself is sent by the **upload helper** that `lanes-launch` runs on your machine. The helper is the security
+boundary — it reads only from folders listed in `~/.config/lanes/upload-allow` (defaults: Desktop, Downloads,
+Pictures, Documents, Lanes Uploads, temp folders; macOS asks once per new folder; `lanes-upload --allow <dir>`), and
+never from `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.kube`, `~/.config`, keychains or `.git`. A window opened before this
+feature has no helper: reopen it once.
+
+On macOS the background service runs as `~/Applications/Lanes Helper.app`. This gives it an identity for macOS
+folder permissions: choose **Allow** when it asks for Downloads, Desktop or Documents, or enable the folder under
+System Settings → Privacy & Security → Files and Folders → Lanes Helper. Full Disk Access is not needed. The
+allowlist above and macOS's folder permission are separate checks. Older installs ran an anonymous `/bin/sh`
+from launchd: macOS silently denied protected folders, tar produced an empty archive, and the box said "nothing
+arrived" even for small files. Re-run `./install.sh` to install the app-backed helper.
+
+The helper logs each transfer and the original error in `~/.local/state/lanes-client/helper-service.log` (Linux:
+`journalctl --user -u lanes-helper`). The sidebar shows received MiB and times out after two minutes **without
+incoming data**, so an active large upload can run longer. The service heartbeat also stays fresh while uploading
+or waiting for a macOS permission prompt. Archive/SSH failures remain failures, and failed watch-folder uploads
+keep their source files for a retry.
+
+## Web / phone
+
+The [installation guide](INSTALL.md#4-optional-safari--home-screen-access) owns setup. After the server has
+Caddy, Tailscale and operator permission, run `sh install/enable-phone.sh --host lanes` from an installed
+client, or `sh install/enable-phone.sh --local` on the host. The remote path uses the selected SSH key and
+the installed checkout shortcut, with no password fallback or agent forwarding. The token is printed only
+in the interactive caller's terminal. Existing tokens remain valid.
+
+On the phone, connect Tailscale and open the printed URL. Paste the token into the sign-in screen and choose
+**Share → Add to Home Screen**. Use **Workspaces**, **Lanes** and **Panes** to navigate. The keyboard opens only
+when tapping **Type here** or another text input; swipes, live updates and reconnects leave it closed.
+**More → Text size** remembers your preferred terminal font. The phone has its own view selection of the same agents.
+
+Tailscale Serve forwards HTTPS 8443 to `lanes-mobile.service` on `127.0.0.1:8083`. The separate unprivileged
+Caddy serves `web/` and forwards native authentication/assets/WebSockets to Zellij on `127.0.0.1:8082`.
+The Mac is a client; serving happens on the workspace host. See [frontend maintenance](../web/README.md).
+
+`lanes prepare phone --mobile` creates the view without attaching a terminal. Hidden mobile views wait for
+a real client before attaching; visible views accept 20 columns / 4 rows for the on-screen keyboard.
+Revoke a named token with `~/.local/share/lanes/bin/zellij-0.45.1 web --revoke-token NAME`.
+An SSH-only phone client can run `lanes attach phone --mobile` instead.
+
+## Safety rules baked into the code (do not remove)
+
+- tmux is always called with `-N` (`attach-session`, `new-session` and `start-server` on a missing socket start
+  a phantom server; the read-only commands exit 1) and `env -i`.
+- In-container sockets are reached through `/proc/<container-init-pid>/root/…`, verified to be a docker cgroup.
+- The holder `exec`s the tmux client, so a lane switch detaches it instead of orphaning it on the pty.
+- pty-name collision guard: the lanes' `client-attached` hook detaches a client whose tty *name* equals the
+  lane's `pane_tty`; host and container pty numbers collide, so the holder re-wraps itself on a fresh pty.
+- Views attach only from a pane zellij has really sized (unviewed tabs are 14x49) and only after a first client.
+- The sidebar binds in `zellij/config.kdl` walk `MoveFocus "left"` once per possible viewport before `WriteChars`:
+  with a single left, `Ctrl-Alt-↓` pressed in the second viewport typed a `J` into a lane.
+- Tests: `python3 -m unittest discover -s tests/unit` needs no server (runs on the Mac) and carries the harness's
+  pure-function pins — the viewer rule, the client-size bucketing, the status keying, the shared-socket
+  attribution and the zmx word (`tests/unit/test_alignment.py`). Live suites, on a QUIET host only:
+  `tests/guards.py`, `tests/view.py` (incl. the wide-view key walk), `tests/upload_box.py`,
+  `tests/smoke_real.py` (read-only, real lanes), `tests/latency.py` (from a client). All use disposable lanes except
+  the explicitly read-only smoke test; every one refuses to start on a busy host (exit 75) and removes its lanes and
+  sessions when it is killed with SIGTERM / SIGHUP.

package/payload/lanes/docs/SHARING.md

@@ -0,0 +1,124 @@
+# Share Lanes through Throttle
+
+**Candidate feature:** requires a platform and Studio Host built with Lanes
+sharing support (Studio tunnel revision 1.3 and migration 0039). Workspace
+exposure is off by default. This page does not enable anyone's workspaces.
+
+The Throttle console's **Shared lanes** page shows workspaces shared with the
+signed-in person. Select a workspace, then a registered lane to read its current
+terminal output. The page refreshes every five seconds and works on desktop and
+mobile Safari. Scrolling and refreshes do not summon the keyboard.
+
+## Connect your Lanes installation
+
+Use your organization's existing Throttle SSO URL. Viewers need access to that
+URL and an account in the same organization; they do not need your SSH key,
+Zellij token, or a direct connection to your computer. The Host makes an outbound
+connection to Throttle. If Throttle is on a private tailnet, viewers also need
+access to that tailnet.
+
+Install matching `throttle-rc` platform and Host builds using your normal
+Throttle deployment procedure. Back up the platform database before applying
+migration 0039. Run the Host as the account that can read your Lanes registry and
+tmux sockets, then enroll it once:
+
+```sh
+throttle-rc studio enroll https://throttle.example.com
+```
+
+An existing in-container Studio Host reads `~/.lz/registry.json` by default.
+That is the registered-lane projection written by `lanes sync`. No additional
+configuration is needed for this source.
+
+For a Lanes server hosting several workspace containers, run Studio Host on
+that server and add these settings to its
+`~/.config/throttle-rc/studio-host.toml`:
+
+```toml
+server = "https://throttle.example.com"
+machine_id = "lanes-server"
+
+[inventory]
+sharing_state_dir = "~/.local/state/lanes"
+sharing_container_uid = 1000
+legacy_coder_launch = false
+```
+
+`sharing_state_dir` must name the directory used by `lanes sync` and
+`lanes-statusd`. Change `sharing_container_uid` if the workspace's tmux owner
+uses a different UID. The host-side adapter requires Linux, Docker inspection
+access, and permission to read sockets through `/proc/<container-pid>/root`.
+It verifies the live container PID before and after a capture.
+
+```sh
+throttle-rc studio host --check
+throttle-rc studio host
+```
+
+Keep the Host running through your normal process supervisor. Enrollment is
+persistent: the Host proves its own machine key and does not borrow a human
+SSO session or need an eight-hour renewal. Keep its key and enrollment receipt
+private and persistent across upgrades.
+
+The enrollment command prints a short code. In the signed-in console, open
+**Workspaces → Machines → Approve a machine**, enter that code, and approve.
+The terminal stores the enrollment receipt; compare its label and fingerprint
+with the console receipt. See the [Host enrollment runbook](../../docs/runbooks/studio-host-enrollment.md)
+for revocation, checks and upgrades. Sharing is a separate configuration below.
+
+The pre-merge sharing candidate used migration 0037 for different SQL and an
+eight-hour Host session. If you deployed that candidate, use the
+[candidate upgrade procedure](../../docs/runbooks/lanes-sharing-candidate-upgrade.md)
+before deploying current builds. The normal migrator correctly refuses that
+journal; do not edit its digest or reset the database.
+
+## Enable publishers, then expose workspaces
+
+1. Sign in to Throttle and open **Shared lanes → Manage sharing**.
+2. An organization administrator selects eligible people or teams under
+   **Who may share workspaces**, then saves publisher access.
+3. An eligible owner expands a workspace, checks **Expose this workspace**,
+   selects people or teams, and saves. The audience preview shows the selection.
+4. Share the workspace's ordinary `/shared-lanes/<id>` URL with those people.
+   Opening a URL still requires SSO and a current grant.
+
+Each workspace is private until enabled. Direct user grants and current team
+memberships are additive. Administrators can manage publisher eligibility but
+do not automatically receive access to other people's output. Removing
+exposure, eligibility, or membership denies subsequent reads; an open viewer
+clears on its next refresh. Previously read output cannot be recalled.
+
+## What viewers can see
+
+- The selected workspace's current and future **registered lanes**. Unregistered
+  sessions, legacy shells, extra/tool tabs and unrelated workspaces are excluded.
+- Lane names and observed activity; “active” describes recent terminal output,
+  not a build verdict.
+- For tmux lanes, a selectable pane and its latest 2,000 lines, capped at
+  256 KiB. Unsupported holders show metadata without terminal output.
+
+Output is escaped plain text. There is no input, upload, start/stop, resize,
+PTY attach, or interactive terminal connection. Snapshots are not a log archive:
+they stay briefly in platform memory, never in the database or browser storage.
+Full raw terminal output in the selected pane can include sensitive information;
+choose workspace audiences accordingly.
+
+If output disappears, check the owner's Host connection, current SSO session,
+`lanes sync`, `lanes-statusd`, and sharing settings. Old Hosts without revision
+1.3 cannot serve snapshots; update the Host instead of sharing a personal
+interactive `/phone` endpoint.
+
+## Validation
+
+Focused regression coverage lives in the platform's `pg_http_studio` sharing
+tests, `pg_studio_schema`, the Host's `studio_host_sharing` real-tmux test, and
+`views/shared-lanes/view.test.mjs`. The Node tests run without an npm install:
+
+```sh
+node --test crates/throttle-platform/src/http/console/views/shared-lanes/view.test.mjs
+```
+
+The `Lanes sharing` GitHub Actions workflow runs the focused Rust, PostgreSQL,
+real tmux and UI checks. Its manual `candidate_image` option also produces a
+checksum-pinned Docker image and matching Host binary after those checks pass.
+It does not deploy, publish a release, or change anyone's sharing settings.

package/payload/lanes/docs/ZMX-RING0.md

@@ -0,0 +1,51 @@
+# zmx ring 0 — gate report (2026-09-18)
+
+Scope: zmx 0.8.1 (pinned, GitHub asset digest `dfd75720…ebe8`) as the per-lane pass-through holder, exercised ONLY on
+disposable lanes `lz-test-*` created through the real contract (`lane new` inside `coder-dev-work`) and attached from
+the host through `holders/zmx.sh`, plus a host-only sandbox for the daemon-count soak. Reproduce: `tests/zmx_ring0.py`.
+The live-lane invariant (170 panes: pid + window size) held before and after every run.
+
+| Gate | Result |
+|---|---|
+| Create through the contract; host reaches the socket via `~/.lz/<container>` (40-byte path, limit 108) | pass |
+| Agent environment defined by `lane-run` (LANE_ID set; no XDG_CACHE_HOME / SSH_* / ZELLIJ / TMUX leak) | pass |
+| Missing lane: refused (exit 66); nothing created on the host (`/bin/false` create-guard + socket precheck) | pass |
+| Pass-through I/O host pty -> container lane | pass |
+| `lane send` / `lane capture` (automation contract replacing tmux send-keys / capture-pane) | pass |
+| Re-attach replays screen + scrollback into the viewer (1499 of 1500 lines, 18.6 KB) | pass |
+| 50 attach/detach switches: always the right lane, zero leaked clients | pass |
+| zmx #215 scenario: 200 column-halving resizes over dense OSC 8 hyperlinks, 3 clients | daemon survived (same pid) |
+| Lanes never die: agent exit -> login shell; shell exit -> still there (`lane-run` loops) | pass |
+| Daemon cost | ~4 MB RSS with a full scrollback; 100 daemons = 351 MB, create 22 ms each, `list` 19 ms |
+
+Characterised, not failures:
+- **Size policy**: the client that typed last leads (60x20 then 140x40 observed). One active device is fine; a wall of
+  live attaches is not — the wall tab must use snapshot tiles (`lane capture --vt`), as planned.
+- **`zmx list` rows are indented / marked**: parse keys stripped. The socket file is the liveness signal.
+- **A session ends when its root command ends** (contrary to the README): `lane-run` must never exit — it does not.
+- **Logs never rotate**: ~260 KB per torture minute for three lanes -> `lanes gc` truncates them (daily timer).
+- Not yet exercised here: kitty-keyboard/mouse-mode restore inside a zellij pane with a real codex/claude TUI, Android
+  touch (#263), output before the first client (#246/#264 — `lane new` always has its creation client attached).
+
+## Terminal niceties through the chain (measured with `tests/niceties.py`, `tests/osc8_zmx.py`)
+
+What the client terminal actually receives, lane -> holder -> host zellij -> client:
+
+| Nicety | tmux-held lane (all lanes today) | zmx-held lane |
+|---|---|---|
+| 24-bit colour fg/bg, italic, strike, bold/dim, emoji, box drawing | yes | yes |
+| Curly / double / coloured underlines | yes | yes |
+| OSC 8 hyperlinks (cmd/ctrl-click targets) | yes, and they survive lane switches (tmux re-emits them) | live: yes. **After a re-attach: text only, the link target is lost** (zmx snapshot replay and `history --vt` drop OSC 8) |
+| Plain URLs (terminal-side detection) | yes | yes |
+| Copy from tmux copy-mode -> system clipboard (OSC 52) | yes | n/a (zellij selection/copy instead) |
+| App-emitted clipboard write (OSC 52) | no (tmux `set-clipboard external`; unchanged from before) | yes |
+| Agent desktop notifications (OSC 9) | no (tmux drops them; unchanged from before) | yes |
+
+Every lane switch is a re-attach, so with zmx a link already on screen stops being clickable after switching away
+and back (plain URLs keep working). This is a real fidelity gap for ring 1; candidates: upstream fix in zmx's replay,
+or the tmux-per-lane fallback, which keeps links and only needs `set-clipboard on` + passthrough for the other two rows.
+
+Decision: **ring 0 passed.** Ring 1 (5–10 low-stakes real lanes for two weeks) needs the user's go-ahead because it
+restarts agents, and should wait until the viewer switch-over has freed memory in the container (it sits at its
+208 GiB memcg limit today). Fallback holder if ring 1 disappoints: tmux-per-lane (`tmux -L lane_<id>`) behind the same
+`lane` contract.

package/payload/lanes/holders/exec.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# View-owned displays; interactive shells are persistent tmux sessions created by New +.
+# usage: exec.sh <container> monitor|legacy [cwd-or-id]
+set -u
+container=${1:-} kind=${2:-} cwd=${3:-/home/coder}
+case "$container" in ''|-*|*[!A-Za-z0-9_.-]*) echo 'invalid container' >&2; exit 64 ;; esac
+if [ "$kind" = legacy ]; then
+    repo=$(cd "$(dirname "$0")/.." && pwd)
+    exec python3 -S -E "$repo/libexec/legacy_sessions.py" view "$container" "$cwd"
+fi
+case "$cwd" in /*) ;; *) cwd=/home/coder ;; esac
+case "$cwd" in *[!A-Za-z0-9_./-]*) cwd=/home/coder ;; esac
+common="-it -u coder -e TERM=xterm-256color -e COLORTERM=truecolor -e LANG=C.UTF-8"
+case "$kind" in
+    monitor)
+        # Same measured four-worker pilot the previous viewer used.
+        # shellcheck disable=SC2086
+        exec docker exec $common -e TOKIO_WORKER_THREADS=4 -w /home/coder "$container" \
+            /home/coder/.local/bin/throttle monitor ;;
+    *) echo "unknown helper: $kind" >&2; exit 64 ;;
+esac