@vibelord/lanes 1.0.4 → 1.1.0

package/payload/lanes/client/lanes-launch

@@ -6,6 +6,12 @@
 #   lanes-launch <device> [--ascii] [--theme dark|light|auto] [--glyphs M] [--color C]   the device's look (lanes attach)
 #   lanes-launch lane <lane-id>  attach straight to ONE lane, no multiplexer in between
 #   lanes-launch ls              list lanes with live status
+#   lanes-launch web phone|laptop|<device> [--desktop|--mobile] [--no-qr]
+#                                a browser view in one step: the server prepares it, prints its private URL and a QR
+#                                code of it (--no-qr: none), then a login token in THIS terminal. phone = <your
+#                                device>-phone (phone layout), laptop = <your device>-web (desktop layout); any other
+#                                name is that device
+#   lanes-launch update [install.sh options]   the newest client from npm, with your remembered install options
 #   lanes-launch --helper <device> [--service | --while-pid PID]   run only the upload helper
 #                                (--service: the per-machine background service that install.sh sets up)
 # It never ends by itself: after network loss, sleep, or a server that dropped or refused it, it says so, waits and
@@ -13,7 +19,9 @@
 set -u
 host=${LANES_HOST:-lanes}
 primary=$host
-fallback=${LANES_FALLBACK_HOST:-lanes-public}
+# Tried in this order after two immediate connect failures, each only when the ssh config defines it: lanes-ip (the
+# server's tailnet address, when `lanes` names it by its MagicDNS name), then lanes-public (the site's public path).
+fallbacks=${LANES_FALLBACK_HOST:-lanes-ip lanes-public}
 remote='$HOME/.local/bin/lanes'
 config=${XDG_CONFIG_HOME:-$HOME/.config}/lanes
 state=${XDG_STATE_HOME:-$HOME/.local/state}/lanes-client     # logs and helper.alive; `install.sh --check` reads them
@@ -24,6 +32,113 @@ default_device() {
     printf '%s' "$name" | tr 'A-Z' 'a-z' | tr -c 'a-z0-9_.-' '-' | sed 's/-*$//'
 }
 
+# The directory this script really lives in. install.sh links ~/.local/bin/lanes-launch (and coder-launch) to the copy
+# in ~/.local/share/lanes/client, or with --link to a checkout's client/ — always by an absolute path.
+self_dir() {
+    sd=$0 sd_hops=0
+    while [ -L "$sd" ] && [ "$sd_hops" -lt 8 ]; do
+        sd_to=$(readlink "$sd") || break
+        case "$sd_to" in /*) sd=$sd_to ;; *) sd=$(dirname "$sd")/$sd_to ;; esac
+        sd_hops=$((sd_hops + 1))
+    done
+    (cd "$(dirname "$sd")" 2>/dev/null && pwd -P)
+}
+# This client's release: the VERSION file install.sh copies beside the client, else a checkout's lanes/VERSION.
+# Nothing when neither is there (then the server is told no version).
+client_version() {
+    cv_dir=$(self_dir)
+    for cv_file in "$cv_dir/VERSION" "$cv_dir/../VERSION"; do
+        if [ -r "$cv_file" ]; then head -n 1 "$cv_file" | tr -cd 'A-Za-z0-9._+-'; return 0; fi
+    done
+}
+
+# `lanes-launch web phone|laptop|<device>`: one command for a browser view, run in THIS terminal: `lanes web` on the
+# server prepares the view, enables the web services and prints the private URL with a QR code of it (never of the
+# token; --no-qr: none), then shows a fresh login token here (the server refuses it without a terminal; nothing logs
+# it). phone and laptop are views of their own, named after this machine's device so the server counts them as this
+# machine's (`--default-device`: one upload helper per machine).
+web_view() {
+    wv_usage='usage: lanes-launch web phone|laptop|<device> [--desktop|--mobile] [--no-qr]'
+    [ $# -gt 0 ] || { echo "$wv_usage" >&2; exit 64; }
+    wv_base=$(default_device)
+    case "$1" in
+        phone) wv_device=$wv_base-phone wv_layout=--mobile ;;
+        laptop) wv_device=$wv_base-web wv_layout=--desktop ;;
+        *) wv_device=$1 wv_layout= ;;
+    esac
+    shift
+    wv_chosen= wv_qr=
+    # Spliced into the remote command line: only this closed vocabulary passes, anything else refuses before a connection.
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --desktop|--mobile)
+                if [ -n "$wv_chosen" ] && [ "$wv_chosen" != "$1" ]; then echo '--desktop and --mobile are exclusive' >&2; exit 64; fi
+                wv_chosen=$1 ;;
+            --no-qr) wv_qr=' --no-qr' ;;
+            *) echo "lanes-launch web: unknown option $1" >&2; echo "$wv_usage" >&2; exit 64 ;;
+        esac
+        shift
+    done
+    [ -z "$wv_chosen" ] || wv_layout=$wv_chosen
+    for wv_name in "$wv_base" "$wv_device"; do
+        case "$wv_name" in ''|-*|*[!A-Za-z0-9_.-]*) echo "invalid name: $wv_name" >&2; exit 64 ;; esac
+    done
+    # The server's limit. Never shortened here: a cut suffix could turn the view into the machine's own device.
+    if [ "${#wv_device}" -gt 32 ]; then
+        echo "lanes-launch web: $wv_device is longer than 32 characters; name the view: lanes-launch web <name>" >&2; exit 64
+    fi
+    # One connection, decided on the server: `lanes hello` says its release (`ok device=- version=V boards=N`, every
+    # release since 1.0). A server older than 1.1.0 refuses --default-device and --no-qr (`unknown option`, before the
+    # view exists), so it gets the view and the token without them, and this says what that costs and how the server
+    # updates. Run by sh -c on the server whatever the account's login shell is; the names are checked above and the
+    # sentence holds no single quote.
+    wv_view="$remote web $wv_device${wv_layout:+ $wv_layout} --token"
+    wv_old='lanes-launch web: the server runs lanes '\$wv_release', older than this client: no QR code, and the upload box of this view does not reach this machine. The server updates with: npx @vibelord/lanes@latest --server'
+    exec ssh -t "$host" "sh -c 'wv_release=\$($remote hello 2>/dev/null); wv_release=\${wv_release##* version=}; wv_release=\${wv_release%% *}; case \$wv_release in 0.*|1.0.*) echo \"$wv_old\" >&2; exec $wv_view ;; *) exec $wv_view --default-device $wv_base$wv_qr ;; esac'"
+}
+
+# `lanes-launch update`: the newest client from npm with this machine's remembered choices. Every KEY=VALUE line of
+# ~/.config/lanes/install-options becomes its install.sh flag, checked as install.sh checks the file (a value it would
+# ignore is not passed; it names that one itself), so the update repeats the last install even where the new package
+# would resolve a default differently. Arguments given here follow the replayed ones: on install.sh's command line the
+# last flag wins.
+update_client() {
+    for uc_arg in "$@"; do
+        case "$uc_arg" in --server) echo 'lanes-launch update updates this client; a server updates with: npx @vibelord/lanes@latest --server' >&2; exit 64 ;; esac
+    done
+    uc_dir=$(self_dir)
+    if [ -r "$uc_dir/../install.sh" ]; then
+        # (a linked or checkout client: npm would replace it with a copy)
+        echo "lanes-launch update: this client runs from a checkout ($(dirname "$uc_dir")): update it there with git pull, then ./install.sh" >&2
+        exit 64
+    fi
+    command -v npx >/dev/null 2>&1 || { echo 'lanes-launch update: needs Node.js 18 or newer (npx), https://nodejs.org' >&2; exit 69; }
+    uc_given=$#
+    uc_options=$config/install-options
+    if [ -r "$uc_options" ]; then
+        case "$(sed -n 's/^SCHEMA=//p' "$uc_options" | tail -n 1)" in
+            ''|1)
+                while IFS= read -r uc_line || [ -n "$uc_line" ]; do
+                    uc_value=${uc_line#*=}
+                    uc_flag=$(printf '%s' "${uc_line%%=*}" | tr 'A-Z_' 'a-z-')
+                    case "$uc_line" in
+                        DEVICE=*) case "$uc_value" in ''|*[!a-z0-9_.-]*|.*) ;; *) set -- "$@" --device "$uc_value" ;; esac ;;
+                        KEY=/*|KEY='~/'*) set -- "$@" --key "$uc_value" ;;
+                        SITE=/*) set -- "$@" --site "$uc_value" ;;
+                        SITE=*) case "$uc_value" in ''|.*|*/*|*[!A-Za-z0-9_.-]*) ;; *) set -- "$@" --site "$uc_value" ;; esac ;;
+                        DESKTOP=1|UPLOADS=1|PALETTE=1|CODER_LAUNCH=1) set -- "$@" "--$uc_flag" ;;
+                        DESKTOP=0|UPLOADS=0|PALETTE=0|CODER_LAUNCH=0) set -- "$@" "--no-$uc_flag" ;;
+                    esac                    # (SCHEMA, comments, unknown keys: install.sh does not read them either)
+                done < "$uc_options" ;;
+            *) echo "lanes-launch update: $uc_options was written by a newer installer: not replayed" >&2 ;;
+        esac
+    fi
+    # The arguments given here go last: move them behind the replayed flags.
+    while [ "$uc_given" -gt 0 ]; do set -- "$@" "$1"; shift; uc_given=$((uc_given - 1)); done
+    printf 'lanes-launch update: npx --yes @vibelord/lanes@latest %s\n' "$*" >&2
+    exec npx --yes @vibelord/lanes@latest "$@"
+}
+
 while_pid=
 service=
 extra=
@@ -39,10 +154,12 @@ case "${1:-}" in
             esac
         done ;;
     ls) exec ssh -o RequestTTY=no "$host" "$remote ls" ;;
+    web) shift; web_view "$@" ;;
+    update) shift; update_client "$@" ;;
     lane)
         [ -n "${2:-}" ] || { echo 'usage: lanes-launch lane <lane-id>' >&2; exit 64; }
         mode=open target=$2 ;;
-    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,18p' "$0"; exit 0 ;;
     *) mode=attach target=${1:-$(default_device)} ;;
 esac
 if [ "$mode" = attach ] && [ $# -gt 1 ]; then
@@ -65,6 +182,9 @@ fi
 case "$target" in ''|-*|*[!A-Za-z0-9_.-]*) echo "invalid name: $target" >&2; exit 64 ;; esac
 client="$(hostname -s 2>/dev/null || echo client)-$$"
 client=$(printf '%s' "$client" | tr -c 'A-Za-z0-9_.-' '-')
+# Told to `lanes attach`, which says in one line when this client is older than the server (`lanes-launch update`).
+version=$(client_version)
+[ -z "$version" ] || version=" --client-version $version"
 
 # ---- log: what a window that showed nothing never left behind ------------------------------------------------------
 # One line per connection event, rotated to .1 at 256 KiB. The service writes to stderr instead: launchd / journald
@@ -176,10 +296,19 @@ hold() {
     wait "$reader" 2>/dev/null || :
     reader=
 }
-# The fallback host counts only if the ssh config really defines it (an undefined alias resolves to itself).
-fallback_defined() {
-    resolved=$(ssh -G "$fallback" 2>/dev/null | awk '$1 == "hostname" { print $2; exit }')
-    [ -n "$resolved" ] && [ "$resolved" != "$fallback" ]
+# A fallback host counts only if the ssh config really defines it (an undefined alias resolves to itself).
+defined() {
+    resolved=$(ssh -G "$1" 2>/dev/null | awk '$1 == "hostname" { print $2; exit }')
+    [ -n "$resolved" ] && [ "$resolved" != "$1" ]
+}
+# The path after $host: the next DEFINED alias in $fallbacks, and past the last one the primary again.
+next_host() {
+    nh_after=; [ "$host" = "$primary" ] && nh_after=1
+    for nh in $fallbacks; do
+        if [ -n "$nh_after" ] && [ "$nh" != "$primary" ] && defined "$nh"; then printf '%s' "$nh"; return 0; fi
+        [ "$nh" = "$host" ] && nh_after=1
+    done
+    printf '%s' "$primary"
 }
 # ---- upload helper: serves the sidebar's upload box ------------------------------------------------------------
 # A drop on the terminal only gives the SERVER a local path string; the file lives here. This helper waits for
@@ -213,6 +342,20 @@ service_serving() {
     seen=$(mtime "$state/helper.alive") || return 1
     [ -n "$seen" ] && [ $(( $(date +%s) - seen )) -lt 90 ]
 }
+# A systemd user service keeps the environment it was started with, and default.target starts lanes-helper at boot —
+# often before the desktop session (gnome-keyring, KDE, uwsm) hands its SSH_AUTH_SOCK to the user manager. So the
+# SERVICE takes the agent the user manager holds before every login: a key with a passphrase works from the first
+# login after that hand-over, with no restart and no login shell. Only a plain absolute path is taken (systemd prints a
+# value that needs quoting as $'…'). A window's helper keeps its terminal's agent; launchd has no user manager to ask.
+manager_agent() {
+    [ -n "$service" ] || return 0
+    command -v systemctl >/dev/null 2>&1 || return 0
+    ma=$(systemctl --user show-environment 2>/dev/null | sed -n 's/^SSH_AUTH_SOCK=//p' | tail -n 1)
+    case "$ma" in /*) ;; *) return 0 ;; esac
+    [ "$ma" != "${SSH_AUTH_SOCK:-}" ] || return 0
+    SSH_AUTH_SOCK=$ma; export SSH_AUTH_SOCK
+    log "upload helper: SSH agent of the user manager: $ma"
+}
 upload_helper() {
     [ -x "$HOME/.local/bin/lanes-upload" ] || return 0
     dflt=$(default_device)
@@ -230,6 +373,7 @@ upload_helper() {
         # A window's own helper is the fallback only. While the service serves this machine it opens no connection
         # (each one is a long-lived process on the server); when the service goes quiet it takes over within ~2 min.
         if [ -z "$service" ] && [ "$helper_target" = "$dflt" ] && service_serving; then sleep 30; continue; fi
+        manager_agent
         if ssh -o RequestTTY=no -o BatchMode=yes -o ServerAliveInterval=15 -o ServerAliveCountMax=4 "$primary" "$remote upload-requests $helper_target --default-device $dflt" 2>"$errfile" |
         (   heard=1
             while IFS= read -r line; do
@@ -319,7 +463,7 @@ while :; do
     log "connecting: $mode $target via $host"
     started=$(date +%s)
     if [ "$mode" = attach ]; then
-        run ssh "$host" "$remote attach $target --client $client --default-device $(default_device) $extra" || :
+        run ssh "$host" "$remote attach $target --client $client --default-device $(default_device)$version $extra" || :
     else
         run ssh "$host" "$remote open $target" || :
     fi
@@ -353,14 +497,16 @@ while :; do
         pause=60
         what='trying again'
     else
-        # Two transport failures in a row on the primary path: try the fallback path once it exists. (25 s: a connect
-        # that times out takes ConnectTimeout 20 — it must count, or a dead tailnet never reaches the fallback.)
+        # Two transport failures in a row on one path: the next path the ssh config defines (lanes -> lanes-ip ->
+        # lanes-public -> lanes). (25 s: a connect that times out takes ConnectTimeout 20 — it must count, or a dead
+        # tailnet never reaches a fallback.)
         if [ "$rc" = 255 ] && [ "$lasted" -lt 25 ]; then fails=$((fails + 1)); else fails=0; fi
-        if [ "$fails" -ge 2 ] && [ "$host" = "$primary" ] && fallback_defined; then
-            host=$fallback; fails=0; delay=1
-            printf '\r\n\033[2mlanes: %s unreachable, using %s\033[0m\r\n' "$primary" "$fallback"
-        elif [ "$fails" -ge 2 ] && [ "$host" = "$fallback" ]; then
-            host=$primary; fails=0
+        if [ "$fails" -ge 2 ]; then
+            next=$(next_host); fails=0
+            if [ "$next" != "$host" ] && [ "$next" != "$primary" ]; then
+                printf '\r\n\033[2mlanes: %s unreachable, using %s\033[0m\r\n' "$host" "$next"; delay=1
+            fi
+            host=$next
         fi
         printf '\r\n\033[2mlanes: connection ended (%s).\033[0m\r\n' "$rc"
         pause=$delay

package/payload/lanes/client/ssh.stanza.in

@@ -3,7 +3,15 @@
 # ~/.ssh/config; nothing else in your SSH setup is changed. Re-run the installer instead of editing this file.
 # Options that only some OpenSSH builds know (ObscureKeystrokeTiming, UseKeychain) are written ONLY when this
 # machine's ssh accepts them: an unknown option is a parse error for EVERY host, even inside a non-matching block.
-Host lanes
+# Every alias below pins the same host key: HostKeyAlias keys known_hosts by "@ALIAS@", whatever HostName says.
+#@IPALIAS@ # `lanes` names the server by its MagicDNS name (this machine resolved it at install time); lanes-ip is the
+#@IPALIAS@ # same server by its tailnet address, which lanes-launch falls back to after two immediate connect failures on
+#@IPALIAS@ # `lanes` (MagicDNS switched off later, say). OpenSSH keeps the FIRST value it reads for an option, so this
+#@IPALIAS@ # HostName wins over the one in the shared block below.
+#@IPALIAS@ Host lanes-ip
+#@IPALIAS@     HostName @IP@
+#@IPALIAS@ Host lanes lanes-ip
+#@NOIPALIAS@ Host lanes
     HostName @HOST@
     User @USER@
     HostKeyAlias @ALIAS@
@@ -31,7 +39,8 @@ Host lanes
     LogLevel ERROR
 #@PUBLIC@
 #@PUBLIC@ # Fallback path: the same sshd over the server's public address (key-only). lanes-launch uses it only after two
-#@PUBLIC@ # immediate connect failures on `lanes` (tailnet down); it goes back to the tailnet on the next healthy session.
+#@PUBLIC@ # immediate connect failures on `lanes` (and lanes-ip; tailnet down); it goes back to the tailnet on the next
+#@PUBLIC@ # healthy session.
 #@PUBLIC@ Host lanes-public
 #@PUBLIC@     HostName @PUBLIC_HOST@
 #@PUBLIC@     User @USER@

package/payload/lanes/docs/ARCHITECTURE.md

@@ -198,7 +198,9 @@ shim, so `EVAL_CLAUDE_REAL_BIN=<checkout>/.bw-tools/bin/claude eval-claude` comp
 The client installer creates an SSH alias and dedicated terminal configuration, using the selected profile's
 host key and the user's SSH key. `lanes-launch` reconnects its view and provides a helper channel for uploads.
 A background helper can serve the same channel when installed; on macOS it runs under the Lanes Helper app's
-identity so folder permissions work.
+identity so folder permissions work. On Linux it is a systemd user service that logs in through the SSH agent the
+user manager holds, looked up before every login, so an agent a desktop session hands over after boot is used
+without a restart. The installer's remembered `--no-uploads` / `--no-desktop` remove what an earlier install added.
 
 The sidebar sends an upload request naming paths, workspace and device. The client checks its folder allowlist,
 streams an archive over SSH, and reports original errors and progress. The host extracts data into that
@@ -206,11 +208,44 @@ workspace's `uploads/` folder without overwriting files; an optional paste place
 selected lane. Active transfers have an idle timeout, not a short total-duration limit. Credentials, `.git`
 metadata and disallowed folders cannot be uploaded through the helper.
 
+## Joining a site
+
+A machine whose key the server does not know (`lanes hello` refused with `Permission denied`) is authorized through
+the site's enrolment service, `lanes-enrold` (W8 Track A, loopback, behind Tailscale Serve and Caddy's `/enrol/*`),
+never by the client editing `authorized_keys`. The client half is in `install.sh` (`enrol`). It asks
+`https://<LANES_SERVER_NAME>:8443` with curl, or with python3's `http.client` when curl is absent. When the machine
+cannot resolve the name (MagicDNS off), it repeats the request against the profile's IPv4 `LANES_SERVER_HOST`
+(`--resolve NAME:PORT:ADDRESS`), so TLS still checks the certificate against the name. Request bodies go through stdin;
+curl runs with `-q` (no `~/.curlrc`) and `--noproxy '*'` (the service is on the tailnet only).
+
+Wire contract v1 is the one `lanes-enrold` serves (W8 A3; its RUNBOOK section "Enrolment service" and the data-model
+row DM-LANES-ENROL-WIRE are the authority; additive only, so the client ignores keys it does not know). The client
+reads JSON answers of at most 64 KiB; any status other than the success below is a refusal whose body may carry
+`{"error": "<word>"}` (for example `invalid-or-expired`, `requests-disabled`, `rate-limited`), which the client shows:
+
+| Call | Body the client sends | Success, and what the client reads of it |
+| --- | --- | --- |
+| `GET /enrol/site` | — | `200 {alias, host_name, host_key, version, request_mode, caller, source}`: `request_mode` (`true`\|`false`, always present) is what tells the service from a web page or any other JSON; `false` = invite only; `caller` is the tailnet login the service received (`null` outside request mode). `version` is the server's Lanes release, not a wire number: the client does not gate on it |
+| `POST /enrol/redeem` | `{"code", "pubkey": "ssh-ed25519 <base64>", "device", "client_version"}` | `200 {device, owner: {login, name, email} \| null, ssh_ready: true}`: the key is authorized now |
+| `POST /enrol/request` | `{"pubkey", "device", "client_version"}` | `202 {id, expires_at}` (the same device and key asked again: the same request); the client keeps `id` |
+| `GET /enrol/request/<id>` | — | `200 {id, state: pending\|approved\|denied\|expired, expires_at}`; `404` = the service does not know it (or it was filed by another login): the request is over |
+
+A verdict carries no owner: an approved request belongs to the login it was filed under, the `/site` `caller`, which
+is what the client names. The client sends the public key without its comment (the managed block writes
+`lanes:<device>`), never sends the code anywhere but the redeem body, and keeps an open request's id in
+`~/.config/lanes/enrol-request` (`SCHEMA=1`, `ID`, `URL`, `DEVICE`, `FILED`; mode 0600; read without executing it;
+removed once answered and by `--uninstall`). No service (no answer, a page, `502` from a Caddy whose enrold is down), a
+refusal, or no code and no terminal: the exit-3 text with the public key, unchanged — except a `409 {"error":
+"device-taken"|"key-taken"}`. enrold answers that only after a valid code (or to a request it would otherwise file),
+and nothing is used up, so the exit-3 text names the re-run that joins instead: another `--device NAME` (the invite is
+still valid) or a key of its own, and where a member looks (`lanes offboard <device> --yes`, `lanes keys list`).
+
 ## Web and phone
 
 Tailscale Serve terminates private HTTPS on 8443 and forwards to the dedicated Caddy user service on loopback
 8083. Caddy serves `web/` and forwards native assets, authentication and WebSockets to Zellij on loopback 8082.
-Zellij's existing token/cookie checks remain authoritative; the mobile layer adds no second login system.
+Zellij's existing token/cookie checks remain authoritative; the mobile layer adds no second login system. The one
+other route, `/enrol/*`, goes to the enrolment service on loopback 8184 (see Access).
 
 The phone shell uses the pinned client's window hooks for workspaces, panes, input and sizing. A visible
 **Type here** field holds the original terminal input. Programmatic input focus is blocked on phones, so a
@@ -251,3 +286,52 @@ and [host protection](HOST-GUARD.md) for those operations.
 The package uses Python's standard library and POSIX shell. Host binaries are versioned and checksum-pinned
 in `holders.lock`; Zellij's web assets are served by that binary and integrity-pinned in `web/index.html`.
 Deployment profiles, workspace catalogs and runtime state remain distinct from shared source code.
+
+## Access
+
+Clients log in to one Unix account over SSH (tailnet, or the `lanes-public` fallback). Who may do so is the
+`members/<device>.json` store in the lanes state directory, projected by `libexec/keys.py` (`lanes keys`) into one
+`# lanes-managed BEGIN` … `END` block of that account's `~/.ssh/authorized_keys`: one
+`restrict,pty ssh-ed25519 <key> lanes:<device>` line per member, re-rendered whole on every change, written
+atomically and only when the bytes change. Lines outside the block belong to the operator and are never edited
+(only `lanes keys adopt` moves plain hand-added `lanes:<device>` lines in, keeping a backup). The block never names a
+device the store does not hold: a member file is written before its line and a revoked line leaves the block before
+its member file does, so an interrupted change can leave a member without a line (no access) but never a line
+without a member, and running the same verb again finishes it. The options follow
+what the client does over that key: a forced TTY and plain commands with stdin pipes, no forwarding. The client
+installer never edits the server's file.
+
+Identity on the server is *device → owner*: a member record also names the owner `{login, name, email}` (the
+tailnet login), how the key arrived (`invite`, `request`, `manual`), who approved it and the workspaces it was
+invited to. `libexec/members.py` owns that store's file I/O and the one definition of a valid record's identity
+fields; `keys.py` owns the key fields. The Unix account stays shared. A view session takes its owner from the
+store (`create_session` and `lanes attach`, also from the machine's record for a window of that machine) and records
+it in `devices/<device>.json`: whenever a member record exists it decides (`members.owner_for`), so `lanes device
+list` agrees with `lanes keys list` and a handed-over machine follows its new owner; after a revoke the last owner is
+kept, like the base. Enrolment writes `members/` only, never `devices/`, because every device file is a view `lanes
+ensure` keeps alive. Every text field of a member is refused when it holds a control, format (bidi, zero-width),
+surrogate, private-use or unassigned character, since `device list` and `keys list` print them.
+
+Enrolment is a service, not an admin edit: `libexec/enrold.py` (`lanes-enrold.service`, loopback 8184, reached as
+`/enrol/*` through the same Tailscale Serve and Caddy as the browser view) adds a member either by redeeming a one-time
+invite code from `invites/` or by a request in `enrol-requests/` that a member approves on `/enrol/pending` (a member
+whose owner login is the caller's; `lanes keys owner` names the owner of a key added by hand). It writes
+through `keys.py` under the same lock as `lanes keys`, so the block stays a projection of `members/`. The caller's
+identity is the `Tailscale-User-Login` header Serve injects (a redeemed invite then belongs to that caller, whoever it
+was minted for; the invite's own name and email stay in the record as `invited_as`), trusted only in request mode —
+pinned by the operator with `lanes enrol mode request` after the header check (or forced by the unit's environment),
+else decided by the first request that came through Serve after a start. Serve replaces a forged header only on the tailnet path: any process that
+reaches the host's loopback can send one itself, so request mode is safe only where no account besides the workspace
+account and root can (DEF-1645, open; RUNBOOK "Trust boundary"). Every redeem failure is one indistinguishable
+answer, rate-limited per tailnet device (Caddy keeps the `X-Forwarded-For` Serve sets, by trusting its loopback peer),
+and the append-only `enrol.log` never holds a code. RUNBOOK "Enrolment service" has the wire contract.
+
+The operator's half is `libexec/enrol.py` behind three verbs. `lanes invite` writes `invites/<id>.json` — the code's
+hash, never the code, which is printed once and only to a terminal — and can mail the welcome kit and mint the
+tailnet invite, each through its own optional Lanes key file. `lanes enrol approve|deny` calls the service's own
+`decide()`, recording the SSH client address as the approver (over SSH every login is the same account; the phone
+path records the tailnet login); `lanes enrol mode` pins request mode. `lanes offboard` reverses an enrolment in a
+fixed order — key, device record, the machine's web login tokens (those `web-tokens.json` records for the device, its
+windows and the views minted with it as their machine: Zellij 0.45.1 names tokens `token_<n>`, so the record decides),
+view session — stopping at the first two when they fail, because a view ended while its device file or key remains is
+brought back.