@vibelord/lanes 1.0.1 → 1.0.3

package/payload/lanes/docs/SHARING.md

@@ -30,9 +30,10 @@ 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`:
+For a Lanes server hosting several workspace containers, prefer the installer-owned
+[co-located Studio Host](#co-located-studio-host-one-host-per-lanes-server) below. Hand-run, the server's
+`~/.config/throttle-rc/studio-host.toml` reads (add `mode = "lanes-server"` under `[inventory]` for the
+interactive adapter; without it the Host serves the read-only sharing capture only):
 
 ```toml
 server = "https://throttle.example.com"
@@ -72,6 +73,236 @@ eight-hour Host session. If you deployed that candidate, use the
 before deploying current builds. The normal migrator correctly refuses that
 journal; do not edit its digest or reset the database.
 
+## Co-located Studio Host (one Host per lanes server)
+
+On a lanes server — the account that runs `lanes-statusd` and reaches every workspace container's tmux sockets
+through `/proc/<container-pid>/root/tmp/tmux-<uid>/` — ONE Studio Host serves every board, installed and supervised
+by the lanes installer as `lanes-studio-host.service` (design: `docs/design/throttle-studio.md` §8.10). It replaces
+one Host per workspace container and the hand-built `lanes-sharing-host.service`. Laptops keep the in-container Host
+and `throttle-rc studio service`; never run both on one machine (the enable step refuses).
+
+**Status of the pieces.** Assembled on the integrated tree (2026-10-04): the installer below
+(`tests/unit/test_studio_host.py`), the Host's interactive `lanes-server` adapter, `studio publish-key` /
+`adopt-receipt` and the platform's `server studio-adopt-host`. Only a `throttle-rc` built before 2026-10-04 refuses
+those verbs `not_assembled`, and the enable step then stops with exit 1 before enabling anything. A live lanes
+server and a live deploy are operator-gated; see "Deploy-provisioned enrolment" for the handoff's precondition.
+
+### 1. Install the binary
+
+No `node/<sha12>` release that carries the co-location CLI is pinned yet, so install a locally built binary. It is
+hashed, copied to `~/.local/share/lanes/bin/throttle-rc-local-<sha12>`, re-hashed, and selected through the link
+`~/.local/share/lanes/bin/throttle-rc` that the unit runs; `throttle-rc.pin.json` beside it records the digest:
+
+```sh
+cargo build --release --locked -p throttle-rc        # on a build machine; copy the file to the server
+lanes studio-host install --from ./throttle-rc --sha256 <the sha256 you computed where you built it>
+```
+
+Once a release is tagged, its line goes into `holders.lock` as an `opt-in` pin (the file's comment has the
+template) and `lanes studio-host install` with no `--from` downloads it — `gh release download` for the private
+repository, else `curl` — and refuses unless BOTH the tarball and the binary inside it match their digests.
+`./install.sh --server` never downloads an opt-in pin. Nothing is restarted by `install`.
+
+### 2. Enable
+
+```sh
+sh install/enable-studio-host.sh --server https://throttle.example.com --dry-run   # the plan; changes nothing
+sh install/enable-studio-host.sh --server https://throttle.example.com
+```
+
+In order, and refusing (exit 3) before anything changes when another Host unit is enabled or running
+(`another_host_unit`), the hand-built unit exists (`hand_built_unit_present`, below), no binary is installed
+(`no_binary`) or an existing config is not in lanes-server mode (`config_mode`, fixed by `--set-mode`):
+
+1. writes `~/.config/throttle-rc/studio-host.toml` (0600) in lanes-server mode if there is none —
+   `[inventory] mode = "lanes-server"`, `interactive = true`, `sharing_state_dir = $LANES_STATE`,
+   `sharing_container_uid = 1000` (`--container-uid`), `machine_id` from `--machine-id` or `<hostname>-lanes`.
+   An existing file is never rewritten except, with `--set-mode`, its one `mode` key (a `.bak-<time>` is kept);
+2. runs `throttle-rc studio publish-key --out ~/.local/state/lanes/studio-host/public.jwk` — the machine key is
+   created HERE if absent and only its PUBLIC half (0644) is written for the deploy;
+3. enrols, if it can: a deploy receipt at `~/.local/state/lanes/studio-host/receipt.json` (`--receipt PATH`, which is
+   remembered in the enrolment record so the enrol timer and `status` watch that path too) is installed
+   with `throttle-rc studio adopt-receipt --config <the config>`, which refuses a receipt issued for another key
+   (`receipt_key_mismatch`) or by another server URL (`receipt_server_mismatch`); else a registration key
+   file at `~/.config/throttle-rc/registration.key` (`--registration-key-file`, 0600, remembered like `--receipt`) is
+   handed to `throttle-rc studio enroll <server> --registration-key-file` — the script names the file and never opens
+   it (its readability is access(2) and the timer's memory is the file's stat identity, never a digest of the secret;
+   review round 5). A refused or failed receipt/key does not stop the next step: the units are still rendered and enabled, and the
+   run exits with the refusal (3, or 1 for an operational failure) saying the unit is waiting;
+4. renders the lanes units (`install/services.py`), enables `lanes-studio-host.service` and
+   `lanes-studio-host-enrol.timer`;
+5. enrolled: runs `throttle-rc studio host --check`, then starts the Host (restarts it when it was running, so a new
+   config or binary is in force) and exits 0 only when it is still running `--settle` seconds (default 5) later.
+   Not enrolled (and nothing refused): exits 0 **waiting for enrolment** — the unit is enabled and exits 3 (a clean
+   stop, never a restart loop) until a receipt or key arrives.
+
+`lanes-studio-host-enrol.timer` runs `enable-studio-host.sh --retry` every 5 minutes. It acts only on something
+new — a receipt it has not adopted and has not refused (typed, exit 3) within the last hour under the same config, a
+key file not tried in the last hour (a chmod/chown of it counts as new), a machine key that is gone (it publishes a
+new one — over an existing `credential.json` only as described below), an enrolment the Host has not been started with — so a Host that stopped on a revoked enrolment is not restarted into the same refusal. The
+hour applies to the timer only: a manual run of the script always tries the registration key and always tries a
+refused receipt — enrolled or not (review round 4: an enrolled machine used to leave a refused NEW receipt alone for
+ever). A receipt refused with `receipt_server_mismatch` is tried again by the timer as soon as `studio-host.toml`
+changes (the deploy re-emits the SAME bytes, so fixing the Host's `server` is enough); an operational failure of a
+RECEIPT (exit 1/2: a read-only disk, an unloadable config, a timeout) is never remembered. A registration key is
+remembered for the hour after ANY attempt (each try may spend one of its uses), with what `studio enroll` answered:
+`status` says `key-refused` (code, exit, time, next retry) instead of `waiting-for-enrolment`, and a refused key
+SOURCE (`registration_key_source_refused`, the binary's exit 2) is the installer's typed exit 3. A new receipt for
+THIS machine's key is adopted over an existing `credential.json` for the same key (a relabel, a new host row after a
+platform reset); `adopt-receipt` refuses one that would replace a receipt issued for ANOTHER key
+(`receipt_replaces_enrolment`) unless `--new-key` says so, and refuses a receipt for an enrolment this machine
+MEASURED revoked (`receipt_for_revoked_key`). `status` says `receipt-refused` for a refused receipt on disk whether
+or not an older credential exists. A `credential.json` whose machine key is gone, or is not the key this machine
+published, is an enrolment only when it binds the published key (`status --json` `key_binding`). The installer
+re-keys over it — publishes a new key, then `adopt-receipt --new-key` / `studio enroll --new-key` — ONLY when this
+machine MEASURED that host row revoked (the Host's `state.json`); otherwise it refuses `credential_for_gone_key`,
+publishes nothing, and `status` says `credential-for-gone-key`: revoke the row (console, or `throttle-rc studio revoke
+--id <host>`), then `lanes studio-host re-key --yes` — the explicit decision to enrol this machine under a new key
+(review round 6: the installer used to decide that itself). A receipt, key or config this account cannot read is a typed refusal
+(`receipt_unreadable`/`key_unreadable`/`config_unreadable`, exit 3) naming the file's owner and mode — never a
+traceback; `status` says `receipt-unreadable`/`key-unreadable`/`config-unreadable`. Both studio units ALWAYS pin `XDG_CONFIG_HOME`/`XDG_DATA_HOME` — the roots this enable step ran with
+(recorded in `~/.local/state/lanes/studio-host/xdg-roots.json`; a later `./install.sh --server` renders the studio
+units from that record, never from its own shell, and warns when they differ), else `%h/.config` and
+`%h/.local/share` — and every `throttle-rc` child the installer runs gets the same two, so neither the user manager's
+environment nor a reinstall from another shell points the supervised Host at another `credential.json`. A manual run
+on an enrolled machine whose `studio host --check` is red ONLY on the refusal the Host's own last run recorded (the
+owner's tunnel cap, a build mismatch fixed by `lanes studio-host install`, three displacements) starts the Host
+anyway — its first phase replaces that record, and the settle window reports a refusal that still holds. The unit files are
+written where the user MANAGER reads them: `$XDG_CONFIG_HOME/systemd/user` when `systemctl --user show-environment`
+carries it, else `~/.config/systemd/user`. The adopt refusal's code is read from `throttle-rc studio adopt-receipt`'s
+own line (`throttle-rc studio adopt-receipt: refused <code>: …`); a line with no code is remembered as `unknown`.
+
+### Deploy-provisioned enrolment (no human step)
+
+The platform deploy binds the published PUBLIC key to its owner (`throttle-rc server studio-adopt-host`, design
+§8.10 C4) and writes the receipt where this server finds it:
+
+```sh
+THROTTLE_RC_STUDIO_ADOPT_JWK=/home/dev/.local/state/lanes/studio-host/public.jwk
+THROTTLE_RC_STUDIO_ADOPT_OWNER=owner@example.com
+THROTTLE_RC_STUDIO_ADOPT_RECEIPT=/home/dev/.local/state/lanes/studio-host/receipt.json
+```
+
+The step is `deploy/studio-adopt-host.sh`, sourced by `deploy/deploy-ceobox-rc.sh`; a receipt path whose directory is
+absent or not writable is refused `receipt_dir_unusable` (exit 2) before the platform is asked.
+
+Run the deploy **as the lanes account**: `~/.local/state/lanes/studio-host/` is kept at 0700 and the deploy writes
+the receipt 0600 as whoever ran it, so a deploy run by another account cannot read `public.jwk` and leaves a receipt
+the Host cannot read (DEF-1429 in `docs/defect-ledger.md`; a group-readable handoff directory is the unbuilt
+alternative). `--receipt PATH` points the installer at another path the lanes account can read; it is remembered,
+so the enrol timer adopts a receipt that appears there later and `status` reports it (naming the default path again
+forgets it). The receipt carries no secret.
+
+**Precondition — one filesystem (DEF-1441).** The handoff is a file exchange, so the deploy must run where both
+paths above exist: on the docker host, as the lanes account, from a checkout of this repository (the compose build
+context), with an env file that account can read named by `THROTTLE_RC_ENV_FILE` — the script's default is the
+literal `/home/coder/.config/throttle-rc/ceobox.env`, which a lanes account named anything else does not have:
+
+```sh
+THROTTLE_RC_ENV_FILE=~/.config/throttle-rc/ceobox.env bash deploy/deploy-ceobox-rc.sh   # as the lanes account
+```
+
+Copying that env file (it holds the database password) to the lanes account is a secret-custody step the operator
+owns. On ceobox the deploy is normally run from the Coder workspace container, which has neither `/home/dev` nor the
+lanes account, so the zero-step path above does NOT execute there as-is (`[INFERRED-NOT-EXECUTABLE]`, design §8.10
+C4 "Topology precondition"); until one of those two is arranged, use the registration-key path. An owner who has not signed in yet makes the adopt exit 3 and the deploy
+retries next time; the timer picks the receipt up within 5 minutes of it appearing. `lanes studio-host status` then
+says `enrolment: via deploy`.
+
+### After the owner revokes this machine
+
+A revoked key is never adopted again: the Host stops (exit 3) and later deploys WARN `host_revoked` and finish. Give
+the machine a new key:
+
+```sh
+lanes studio-host re-key            # the plan; changes nothing (exit 2)
+lanes studio-host re-key --yes      # stop the Host; remove the machine key, credential.json, public.jwk, receipt.json
+                                    # and the Host's refused state; publish a NEW public key
+```
+
+Then deploy again: the deploy adopts the new key, and the timer installs the receipt and starts the Host. A new key
+is a new machine in the console (design §8.7 "What a new key costs"); any `throttle-rc` login session on this
+account was bound to the old key and must log in again.
+
+### Check it
+
+```sh
+lanes studio-host status            # state: running | running-unenrolled | waiting-for-enrolment | receipt-refused | key-refused | credential-for-gone-key | receipt-unreadable | key-unreadable | config-unreadable | not-enabled | stopped | failed | conflict | not-installed | unknown
+lanes studio-host status --check    # also runs `throttle-rc studio host --check`; its exit binds (below)
+journalctl --user -u lanes-studio-host.service -n 30
+journalctl --user -u lanes-studio-host-enrol.service -n 20   # the enrol timer's one line per tick
+```
+
+`waiting-for-enrolment` is said only while the Host unit is enabled AND the enrol timer is active; otherwise the
+machine is `not-enabled` (nothing retries: re-run the enable script). `receipt-refused` names a receipt on disk the
+installer recorded as refused (its code, when, and when the timer tries it again — an hour, or at once after
+`studio-host.toml` changes); its remedy is the code's (`receipt_server_mismatch`: the config's `server`;
+`receipt_key_mismatch`: redeploy with this machine's public key), then `sh install/enable-studio-host.sh` to try now.
+`key-refused` is the registration key's twin (`studio enroll`'s code and exit; fix the file, its mode or the key, then
+re-run the script — the timer also retries a changed file on its next tick). `credential-for-gone-key` is a receipt
+on disk for a key this machine no longer holds, for a row it has not measured revoked: revoke it, then
+`lanes studio-host re-key --yes`.
+
+`status` re-hashes the selected binary against its record, names the config's mode, the enrolment's `via`, both
+units and any other Host unit, and says `unknown` — never a guess — when the user manager does not answer. It exits
+0 only when the Host runs enrolled (an active unit with no enrolment is `running-unenrolled`, exit 1; with
+`--check`, an active unit whose `studio host --check` is non-zero is `running-check-failed`, exit 1). A caller without
+`XDG_RUNTIME_DIR` (a `sudo -u` or cron shell) reaches the manager at `/run/user/<uid>` when that exists, and
+`re-key` refuses `manager_unreachable` rather than remove the key under a Host whose state the manager did not
+answer, and `another_host_running` (exit 3, nothing changed) while `lanes-sharing-host.service` or
+`throttle-rc-studio-host.service` is active: every Host unit of this account signs with the same machine key, so
+re-keying under the hand-built Host would end its sessions. Migrate (or stop) that unit first. It refuses
+`rekey_path_unremovable` (exit 3, nothing changed) when a file it must remove — e.g. a remembered `--receipt` in the
+deploying account's directory — sits in a directory this account cannot write, and it removes the machine key LAST.
+`status` also reports an installed unit that has lost a load-bearing line
+(`SuccessExitStatus=3`, `KillSignal=SIGINT`, `KillMode=process`, the slice, the statusd ordering).
+
+### Migrating the hand-built `lanes-sharing-host.service`
+
+ceobox's first Host was a hand-written unit running `~/.local/bin/throttle-rc-lanes studio host` with a sharing-only
+config (no `mode`, so in-container). That Host predates enrolment receipts: it authenticated with a stored human
+login SESSION beside its machine key, and holds NO `credential.json` (docs/handoffs/2026-09-22-lanes-sharing.md).
+The lanes unit never uses a session, so such a machine is enrolled as part of the migration. Read the unit before
+replacing it:
+
+```sh
+systemctl --user cat lanes-sharing-host.service
+lanes studio-host install --from ./throttle-rc --sha256 <digest>
+sh install/enable-studio-host.sh --migrate-hand-built --dry-run
+sh install/enable-studio-host.sh --migrate-hand-built
+```
+
+`--migrate-hand-built` refuses a unit that does not run `studio host`, or that names a `--config` other than
+`~/.config/throttle-rc/studio-host.toml` (`%h`, `${HOME}`, `$HOME` and `~` are resolved to the account's home before
+the comparison). Otherwise it sets `mode = "lanes-server"` in the existing config (keeping a `.bak-<time>`), runs the
+replacement's own `throttle-rc studio host --check` on that config (an enrolled machine), and only when it passes
+saves the unit's text to `~/.local/state/lanes/studio-host/migrated/`, runs
+`systemctl --user disable --now lanes-sharing-host.service`, and then starts the new unit. A refusing check
+(`host_check_failed`; e.g. a version-1 credential whose key binding is `unchecked`) leaves the hand-built unit
+running and enabled, restores the config from the `.bak`, and names both — as does ANY failure before the
+hand-built unit is stopped (a failed `publish-key`, an unreadable receipt or key, a failed `disable --now`; review
+round 5: its older binary refuses the `mode` key at its next start). A RUNNING hand-built unit on a machine with no
+`credential.json` (ceobox's shape) is enrolled first, and the **published public key is the first artifact**:
+
+1. `sh install/enable-studio-host.sh --migrate-hand-built` with nothing to enrol from installs the binary, publishes
+   this machine's PUBLIC key to `~/.local/state/lanes/studio-host/public.jwk` (the existing machine key is loaded,
+   never rewritten; the hand-built Host, its unit and its config are untouched) and refuses
+   `hand_built_host_unenrolled` (exit 3), naming the `THROTTLE_RC_STUDIO_ADOPT_*` values for the deploy;
+2. the deploy adopts that key and writes the receipt to the receipt path (see the runbook's one-filesystem
+   precondition; a deploy that runs before step 1 defers — "not published yet" — and finishes) — or put the owner's
+   registration key in `~/.config/throttle-rc/registration.key` (0600) instead;
+3. re-run `sh install/enable-studio-host.sh --migrate-hand-built`: it installs the receipt (or enrols) FIRST, with the
+   same machine key, while the hand-built Host still runs, and only then checks, stops and replaces it (a refused
+   enrolment leaves it running with its config restored). The machine key (`~/.local/share/throttle-rc/machine/key.json`)
+is never read or moved, and an existing enrolment receipt is kept: the new Host serves as the same machine (the same
+key, so the same thumbprint and machine id once enrolled). The old unit file and the old binary are left for
+you to delete. A later run treats the disabled, stopped unit as migrated while the enrolment record under
+`~/.local/state/lanes/studio-host/` survives; if that record is lost, the enrol timer still never refuses on the
+stopped, disabled unit, and a manual run asks for `--migrate-hand-built` again (idempotent: it saves the text again).
+
+**Rollback:** `systemctl --user disable --now lanes-studio-host.service lanes-studio-host-enrol.timer`, restore the
+config's `.bak-<time>`, then `systemctl --user enable --now lanes-sharing-host.service`.
+
 ## Enable publishers, then expose workspaces
 
 1. Sign in to Throttle and open **Shared lanes → Manage sharing**.
@@ -91,7 +322,7 @@ 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.
+  sessions, 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
@@ -112,7 +343,11 @@ interactive `/phone` endpoint.
 
 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:
+`views/shared-lanes/view.test.mjs`. The co-located Host's installer pieces (the
+rendered unit against `tests/unit/golden/lanes-studio-host.service`, the opt-in
+pin, `lanes studio-host`, `install/enable-studio-host.sh` and the hand-built
+migration) are `tests/unit/test_studio_host.py`, run with the other lanes unit
+tests: `python3 -m unittest discover -s lanes/tests/unit`. The Node tests run without an npm install:
 
 ```sh
 node --test crates/throttle-platform/src/http/console/views/shared-lanes/view.test.mjs

package/payload/lanes/holders/exec.sh

@@ -1,13 +1,10 @@
 #!/bin/sh
 # View-owned displays; interactive shells are persistent tmux sessions created by New +.
-# usage: exec.sh <container> monitor|legacy [cwd-or-id]
+# usage: exec.sh <container> monitor [cwd]   (the `legacy` view of pre-persistence Docker shells was retired by
+# plan Task 19: a leftover `exec … legacy` resolve file now ends as an unknown helper, and `lanes gc` removes it)
 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"

package/payload/lanes/holders.lock

@@ -3,3 +3,16 @@
 # zellij 0.45.1: tarball digest matches GitHub's asset digest; inner binary d006c521…19dd matches the published .sha256sum.
 zellij 0.45.1 40bcc2e03f5d5ae8e054e39f676081fe12ab70871506996ba595834c3718eefc https://github.com/zellij-org/zellij/releases/download/v0.45.1/zellij-x86_64-unknown-linux-musl.tar.gz
 zmx 0.8.1 dfd75720b942466f28870731cc86dbc07afa72fb8f3bd5eeb4ff707e4eecebe8 https://github.com/neurosnap/zmx/releases/download/v0.8.1/zmx-0.8.1-linux-x86_64.tar.gz
+# glow 3.0.0 (markdown preview, `lanes preview`): tarball digest matches GitHub's asset digest and the release's checksums.txt;
+# the binary sits in glow_3.0.0_Linux_x86_64/. Installed only when no glow is on PATH; without either, the preview uses less -R.
+glow 3.0.0 13e05e4b2acc18d2aee44291aefe6325b077ec321b631a0cfa780e8e3bc33f78 https://github.com/charmbracelet/glow/releases/download/v3.0.0/glow_3.0.0_Linux_x86_64.tar.gz
+#
+# OPT-IN pins carry three more fields and are skipped by host-install.sh; the step that needs one installs it:
+# name  version  sha256(tarball)  url  opt-in  member-inside-the-tarball  sha256(member)
+# throttle-rc is the co-located Studio Host (docs/SHARING.md "Co-located Studio Host"; `lanes studio-host install`
+# downloads, checks BOTH digests and selects it). It comes from a `node/<sha12>` GitHub prerelease
+# (docs/runbooks/node-release-asset.md): version = node-<sha12>, the asset sidecars give both digests. No
+# node/<sha12> release containing the co-location CLI exists yet, so no line is active: until one is tagged, install
+# a locally built binary with `lanes studio-host install --from PATH [--sha256 HEX]` (also sha256-verified).
+# Template (fill from the release's two .sha256 sidecars, then uncomment):
+# throttle-rc node-<sha12> <tarball-sha256> https://github.com/bwllaming/bw-tools/releases/download/node/<sha12>/throttle-rc-x86_64-unknown-linux-gnu.tar.gz opt-in throttle-rc-x86_64-unknown-linux-gnu/throttle-rc <binary-sha256>

package/payload/lanes/install/enable-studio-host.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Opt-in: run the Throttle Studio Host co-located on this lanes server (docs/SHARING.md "Co-located Studio Host").
+# As the workspace account. Writes the Host config in lanes-server mode if absent, publishes this machine's PUBLIC
+# key for the deploy, adopts a deploy receipt or enrols with a registration key file, and enables
+# lanes-studio-host.service — or leaves it enabled and WAITING for enrolment (exit 0; exit 3 when a receipt or key
+# was refused, the units still enabled so lanes-studio-host-enrol.timer retries).
+# Never prints a key. --dry-run changes nothing. --help lists the options.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+case "$(uname -s)" in Linux) ;; *) echo 'The co-located Studio Host runs on a Linux lanes server.' >&2; exit 1 ;; esac
+[ "$(id -u)" != 0 ] || { echo 'Run as the workspace account, not root.' >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo 'Missing prerequisite: python3 (see docs/INSTALL.md)' >&2; exit 1; }
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+exec python3 "$repo/libexec/studio_host.py" enable "$@"

package/payload/lanes/install/host-install.sh

@@ -22,7 +22,7 @@ for command in python3 curl tar sha256sum infocmp tic install systemctl docker t
     command -v "$command" >/dev/null 2>&1 || { echo "Missing prerequisite: $command (see docs/INSTALL.md)" >&2; exit 1; }
 done
 python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else "Python 3.9+ is required")'
-export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
+export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
 if [ "$start" = 1 ]; then
     systemctl --user show-environment >/dev/null
     python3 -c 'import subprocess; subprocess.run(["docker", "info", "--format", "{{.ServerVersion}}"], check=True, timeout=15)'
@@ -34,10 +34,18 @@ fi
 share=${LANES_SHARE:-$HOME/.local/share/lanes}
 state=${LANES_STATE:-$HOME/.local/state/lanes}
 mkdir -p "$share/bin" "$share/dl" "$state/flags"
-grep -v '^#' "$repo/holders.lock" | while read -r name version sha url; do
+# The view server's PATH (bin/lanes clean_env): the Run pane that renders `lanes preview` sees this, never the
+# installer's PATH, so a glow in ~/.local/bin or ~/go/bin does not count as installed.
+pane_path=$share/bin:$repo/bin:/usr/local/bin:/usr/bin:/bin
+grep -v '^#' "$repo/holders.lock" | while read -r name version sha url flag _rest; do
     [ -n "$name" ] || continue
+    # An `opt-in` pin (the co-located Studio Host's throttle-rc) is installed by the opt-in step that needs it
+    # (install/enable-studio-host.sh, `lanes studio-host install`), never by every server install.
+    [ "$flag" != opt-in ] || continue
     target=$share/bin/$name-$version
     if [ -x "$target" ]; then echo "ok  $name $version"; continue; fi
+    # The markdown preview's renderer is optional: a glow the pane can find serves `lanes preview` as well.
+    if [ "$name" = glow ] && system_glow=$(PATH=$pane_path; command -v glow); then echo "ok  glow (system: $system_glow)"; continue; fi
     archive=$share/dl/$(basename "$url")
     curl -fsSL --retry 3 -o "$archive" "$url"
     actual=$(sha256sum "$archive" | cut -d' ' -f1)
@@ -45,7 +53,11 @@ grep -v '^#' "$repo/holders.lock" | while read -r name version sha url; do
     temporary=$(mktemp -d)
     trap 'rm -rf "$temporary"' EXIT HUP INT TERM
     tar -xzf "$archive" -C "$temporary"
-    install -m 0755 "$temporary/$name" "$target"
+    binary=$temporary/$name
+    # zellij and zmx ship the binary at the top of the tarball; glow nests it in glow_<version>_Linux_x86_64/.
+    [ -f "$binary" ] || binary=$(find "$temporary" -type f -name "$name" | head -n 1)
+    [ -n "$binary" ] && [ -f "$binary" ] || { echo "no $name binary in $archive" >&2; exit 1; }
+    install -m 0755 "$binary" "$target"
     rm -rf "$temporary"
     trap - EXIT HUP INT TERM
     echo "installed $target"

package/payload/lanes/install/services.py

@@ -1,7 +1,10 @@
 #!/usr/bin/env python3
 """Register this checkout's user services without starting or restarting them."""
+import json
 import os
 import shutil
+import sys
+import subprocess
 from pathlib import Path
 import tempfile
 
@@ -14,8 +17,116 @@ def unit_value(value, command=False):
     return value.replace('$', '$$') if command else value
 
 
-def register(repo, home, share, state, workspaces=None):
+# The opt-in economy poller's settings (libexec/economy_poll.py). Rendered into lanes-economy.service only, and only
+# when set in the installer's environment; the unit itself is never enabled by an install (operator gate).
+ECONOMY_SETTINGS = ('LANES_THROTTLE_CONTROL', 'LANES_THROTTLE_TOKEN_FILE', 'LANES_THROTTLE_LOG_DIR',
+                    'LANES_THROTTLE_CONTAINER')
+ECONOMY_UNITS = ('lanes-economy.service',)
+# The opt-in push notifier's config path (libexec/notify.py), rendered into lanes-notify.service only and only when
+# set in the installer's environment (a config FILE path; the ntfy token stays in the file its token_file names).
+NOTIFY_SETTINGS = ('LANES_NOTIFY_CONF',)
+NOTIFY_UNITS = ('lanes-notify.service',)
+
+
+def economy_settings(environ):
+    """The non-empty LANES_THROTTLE_* settings of `environ` (a token FILE path, never a token)."""
+    return {name: environ[name] for name in ECONOMY_SETTINGS if environ.get(name)}
+
+
+def notify_settings(environ):
+    """The non-empty LANES_NOTIFY_* settings of `environ`."""
+    return {name: environ[name] for name in NOTIFY_SETTINGS if environ.get(name)}
+
+
+def throttle_rc_path(share):
+    """The co-located Studio Host's binary: a stable link the opt-in installer points at a sha256-verified file
+    (`lanes studio-host install`, libexec/studio_host.py). Rendered whether or not it exists yet, like @CADDY@."""
+    return Path(share) / 'bin' / 'throttle-rc'
+
+
+# Units that run throttle-rc (or the installer that resolves its paths): they must see the SAME XDG roots the
+# installer used, or the config and credential it wrote are not where the supervised Host looks (review round 1).
+# Review round 3: BOTH roots are pinned ALWAYS — the installer's own, else the defaults as systemd specifiers — never
+# left to the user manager's environment block, which can carry roots the installing shell did not.
+STUDIO_HOST_UNITS = ('lanes-studio-host.service', 'lanes-studio-host-enrol.service')
+XDG_ROOTS = ('XDG_CONFIG_HOME', 'XDG_DATA_HOME')
+XDG_DEFAULTS = {'XDG_CONFIG_HOME': '%h/.config', 'XDG_DATA_HOME': '%h/.local/share'}
+
+
+# Review round 4: the roots the opt-in enable step (install/enable-studio-host.sh) rendered the studio units with,
+# recorded beside its enrolment record. A later server install (re-run for every update, possibly from a shell that
+# does not carry them, e.g. `sudo -u <account> sh` without -i) renders the studio units from THIS record, never from
+# its own environment, so it cannot move the supervised Host away from the config and credential enable wrote.
+XDG_RECORD = Path('studio-host') / 'xdg-roots.json'
+
+
+def recorded_xdg(state):
+    """The roots enable recorded under $LANES_STATE, or None when it never ran (or the record is unreadable)."""
+    try:
+        doc = json.loads((Path(state) / XDG_RECORD).read_text())
+    except (OSError, ValueError):
+        return None
+    if not isinstance(doc, dict) or not isinstance(doc.get('roots'), dict):
+        return None
+    return {name: value for name, value in doc['roots'].items()
+            if name in XDG_ROOTS and isinstance(value, str) and value.startswith('/')}
+
+
+def record_xdg(state, xdg):
+    """Record the roots enable renders the studio units with (an empty dict = the defaults)."""
+    path = Path(state) / XDG_RECORD
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary = tempfile.mkstemp(prefix='.xdg-roots-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'w') as handle:
+            json.dump({'schema': 'lanes.studio-host-xdg-roots', 'version': 1,
+                       'roots': {name: str(Path(xdg[name]).resolve()) for name in XDG_ROOTS if xdg.get(name)}},
+                      handle, sort_keys=True)
+            handle.write('\n')
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def studio_host_config(home, xdg):
+    """The Host's config path as libexec/studio_host.py's Layout resolves it: $XDG_CONFIG_HOME, else %h/.config
+    (left as the systemd specifier so the unit stays the golden when no XDG root is set)."""
+    if xdg.get('XDG_CONFIG_HOME'):
+        return unit_value(Path(xdg['XDG_CONFIG_HOME']) / 'throttle-rc/studio-host.toml', command=True)
+    return '%h/.config/throttle-rc/studio-host.toml'
+
+
+def manager_unit_dir(home):
+    """Where the user MANAGER reads unit files (systemd.unit(5)): $XDG_CONFIG_HOME/systemd/user when the manager's own
+    environment sets it, else ~/.config/systemd/user. Asked of the manager, never of this shell (review round 2);
+    no answer keeps the default. libexec/studio_host.py's manager_units_dir is the same rule."""
+    default = Path(home) / '.config/systemd/user'
+    try:
+        result = subprocess.run(['systemctl', '--user', 'show-environment'], capture_output=True, text=True,
+                                timeout=10, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.TimeoutExpired):
+        return default
+    if result.returncode == 0:
+        for line in result.stdout.splitlines():
+            if line.startswith('XDG_CONFIG_HOME=') and line.split('=', 1)[1].startswith('/'):
+                return Path(line.split('=', 1)[1]) / 'systemd/user'
+    return default
+
+
+def register(repo, home, share, state, workspaces=None, economy=None, notify=None, xdg=None, units_dir=None):
     repo, home, share, state = (Path(p).resolve() for p in (repo, home, share, state))
+    if xdg is None:
+        ambient = {name: os.environ[name] for name in XDG_ROOTS if os.environ.get(name)}
+        xdg = recorded_xdg(state)
+        if xdg is None:
+            xdg = ambient
+        elif {k: str(Path(v).resolve()) for k, v in ambient.items()} != {k: str(Path(v).resolve()) for k, v in xdg.items()}:
+            print(f'services.py: the studio units keep the XDG roots install/enable-studio-host.sh recorded in '
+                  f'{state / XDG_RECORD} ({xdg or "the defaults"}), not this shell\'s ({ambient or "none"}); re-run '
+                  'install/enable-studio-host.sh from the shell whose roots should hold', file=sys.stderr)
+    xdg = {name: str(Path(value).resolve()) for name, value in xdg.items() if name in XDG_ROOTS and value}
     current = home / '.local/share/lanes/current'
     links = ((current, repo), (home / '.local/bin/lanes', repo / 'bin/lanes'))
     for link, _ in links:
@@ -25,6 +136,13 @@ def register(repo, home, share, state, workspaces=None):
     if workspaces:
         settings.append(('LANES_WORKSPACES', Path(workspaces).resolve()))
     environment = ''.join(f'Environment="{name}={unit_value(value)}"\n' for name, value in settings)
+    economy_environment = ''.join(f'Environment="{name}={unit_value(value)}"\n'
+                                  for name, value in sorted((economy or {}).items()) if name in ECONOMY_SETTINGS)
+    notify_environment = ''.join(f'Environment="{name}={unit_value(value)}"\n'
+                                 for name, value in sorted((notify or {}).items()) if name in NOTIFY_SETTINGS)
+    studio_environment = environment + ''.join(
+        f'Environment="{name}={unit_value(xdg[name]) if name in xdg else XDG_DEFAULTS[name]}"\n'
+        for name in XDG_ROOTS)
     rendered = {}
     for source in sorted((repo / 'systemd').iterdir()):
         if source.name.startswith('.') or source.suffix not in ('.service', '.timer', '.slice') or not source.is_file():
@@ -32,10 +150,15 @@ def register(repo, home, share, state, workspaces=None):
         content = source.read_text().replace('@REPO@', unit_value(repo, command=True))
         content = content.replace('@SHARE@', unit_value(share, command=True))
         content = content.replace('@CADDY@', unit_value(shutil.which('caddy') or '/usr/bin/caddy', command=True))
+        content = content.replace('@THROTTLE_RC@', unit_value(throttle_rc_path(share), command=True))
+        content = content.replace('@STUDIO_HOST_CONFIG@', studio_host_config(home, xdg))
         if '[Service]\n' in content:
-            content = content.replace('[Service]\n', '[Service]\n' + environment, 1)
+            lines = studio_environment if source.name in STUDIO_HOST_UNITS else environment
+            extra = (economy_environment if source.name in ECONOMY_UNITS else
+                     notify_environment if source.name in NOTIFY_UNITS else '')
+            content = content.replace('[Service]\n', '[Service]\n' + lines + extra, 1)
         rendered[source.name] = '# Generated by lanes/install/services.py; re-run the server installer to update.\n' + content
-    units = home / '.config/systemd/user'
+    units = Path(units_dir) if units_dir else home / '.config/systemd/user'
     units.mkdir(parents=True, exist_ok=True)
     for name, content in rendered.items():
         fd, temporary = tempfile.mkstemp(prefix='.lanes-', dir=units)
@@ -58,4 +181,5 @@ if __name__ == '__main__':
     register(Path(__file__).resolve().parents[1], Path.home(),
              os.environ.get('LANES_SHARE', Path.home() / '.local/share/lanes'),
              os.environ.get('LANES_STATE', Path.home() / '.local/state/lanes'),
-             os.environ.get('LANES_WORKSPACES'))
+             os.environ.get('LANES_WORKSPACES'), economy_settings(os.environ), notify_settings(os.environ),
+             units_dir=manager_unit_dir(Path.home()))