@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/holders.lock

@@ -16,3 +16,8 @@ glow 3.0.0 13e05e4b2acc18d2aee44291aefe6325b077ec321b631a0cfa780e8e3bc33f78 http
 # 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>
+# mermaid 11.17.2 (the docs page's diagrams, plan W10 W6, LNS-107): the npm tarball, 17,796,365 B, whose sha512 is the
+# registry's dist.integrity; the member is the classic-script (IIFE) build, 3,572,661 B, that web/docs.js loads with
+# this digest as its SRI. Both sha256s measured 2026-10-08. install/enable-docs.sh installs it into
+# ~/.local/share/lanes/vendor/; to bump it see docs/RUNBOOK.md "Mermaid pin".
+mermaid 11.17.2 6ad2f42c3fc26bbf9e45cbb6d11898972573ea52b33a5f4ff51952899f950ffd https://registry.npmjs.org/mermaid/-/mermaid-11.17.2.tgz opt-in package/dist/mermaid.min.js 581ed7d74bd9048d0e3a91363927d72ef22942d7722546b27f7cc29e35390eb8

package/payload/lanes/install/enable-docs.sh

@@ -0,0 +1,78 @@
+#!/bin/sh
+# The docs page's pinned Mermaid (plan W10 W6, LNS-107; docs/RUNBOOK.md "Mermaid pin"). Every server install runs it
+# right after lanes-docsd's restart and every update (--update-only) as the post-commit step `enable-docs` (W8, LNS-109:
+# host-install.sh, libexec/update.py DOCS_STEP), never fatally; it runs by hand as well. As the workspace account, never
+# root. Reads holders.lock's `mermaid` opt-in pin, downloads its npm tarball into a temporary
+# directory, checks the tarball's sha256, extracts ONLY the pinned member (never a link), checks the member's sha256,
+# and installs it as $LANES_SHARE/vendor/mermaid-<version>.min.js (0644, by rename) with the relative link
+# mermaid.min.js -> that file. Caddy serves the directory at /lanes-assets/vendor/ (web/Caddyfile); web/docs.js
+# loads the versioned name with the member digest as its SRI. Idempotent: an installed file whose digest is the pin's
+# is kept and nothing is downloaded; one that differs is replaced from a verified download. Older versions stay.
+# Exit status: 0 installed, or already present; 1 a prerequisite is missing or the download failed; 2 usage;
+# 3 refused — holders.lock has no valid mermaid pin, a digest differs, or the member is missing or not a regular file.
+# A refusal or failure installs nothing.
+set -eu
+repo=$(cd "$(dirname "$0")/.." && pwd)
+usage='usage: enable-docs.sh [--help]'
+case "$#:${1:-}" in
+    0:) ;;
+    1:-h|1:--help)
+        echo "$usage"
+        echo 'Installs the Mermaid that holders.lock pins (opt-in line `mermaid`) into ~/.local/share/lanes/vendor/'
+        echo '($LANES_SHARE/vendor), after checking the sha256 of the npm tarball and of its member.'
+        echo 'Exit status: 0 installed or already present; 1 a prerequisite is missing or the download failed;'
+        echo '2 usage; 3 refused (no valid pin, a sha256 mismatch, the member missing or not a regular file).'
+        exit 0 ;;
+    *) echo "$usage" >&2; exit 2 ;;
+esac
+[ "$(id -u)" != 0 ] || { echo 'Run as the workspace account, not root.' >&2; exit 1; }
+for command in curl tar sha256sum install mktemp; do
+    command -v "$command" >/dev/null 2>&1 || { echo "Missing prerequisite: $command (see docs/INSTALL.md)" >&2; exit 1; }
+done
+share=${LANES_SHARE:-$HOME/.local/share/lanes}
+lock=$repo/holders.lock
+refuse() { echo "enable-docs: refused, nothing was installed: $*" >&2; exit 3; }
+hex64() { [ "${#1}" -eq 64 ] && case $1 in *[!0-9a-f]*) false ;; esac; }
+
+# The pin: exactly one `mermaid` line of the 7-field opt-in grammar (holders.lock's header; studio_host.parse_lock).
+pins=$(grep -v '^[[:space:]]*#' "$lock" | awk '$1 == "mermaid"') || :
+[ -n "$pins" ] || refuse "$lock has no mermaid line"
+[ "$(printf '%s\n' "$pins" | wc -l)" -eq 1 ] || refuse "$lock pins mermaid more than once"
+# shellcheck disable=SC2086 # the line's words are the fields; no pathname expansion of them
+set -f
+set -- $pins
+set +f
+[ "$#" -eq 7 ] && [ "$5" = opt-in ] || refuse "$lock: the mermaid line is not 'name version sha256 url opt-in member sha256'"
+version=$2 sha=$3 url=$4 member=$6 member_sha=$7
+case $version in ''|*[!A-Za-z0-9._-]*) refuse "$lock: mermaid version '$version' is not a plain word" ;; esac
+hex64 "$sha" || refuse "$lock: the mermaid tarball digest is not 64 lowercase hex"
+hex64 "$member_sha" || refuse "$lock: the mermaid member digest is not 64 lowercase hex"
+case $url in https://*) ;; *) refuse "$lock: the mermaid url is not https" ;; esac
+case /$member/ in //*|*/../*|*/./*|*//*) refuse "$lock: member '$member' is not a plain relative path" ;; esac
+
+vendor=$share/vendor
+target=$vendor/mermaid-$version.min.js
+if [ -f "$target" ] && [ ! -L "$target" ] && [ "$(sha256sum "$target" | cut -d' ' -f1)" = "$member_sha" ]; then
+    ln -sfn "mermaid-$version.min.js" "$vendor/mermaid.min.js"
+    echo "ok  mermaid $version ($target)"
+    exit 0
+fi
+
+temporary=$(mktemp -d)
+trap 'rm -rf "$temporary"' EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM HUP
+curl -fsSL --retry 3 -o "$temporary/mermaid.tgz" "$url" || { echo "enable-docs: download failed: $url" >&2; exit 1; }
+actual=$(sha256sum "$temporary/mermaid.tgz" | cut -d' ' -f1)
+[ "$actual" = "$sha" ] || refuse "sha256 mismatch for the mermaid $version tarball: $actual, pinned $sha"
+mkdir "$temporary/x"
+tar -xzf "$temporary/mermaid.tgz" -C "$temporary/x" "$member" 2>/dev/null || refuse "the tarball has no $member"
+file=$temporary/x/$member
+[ -f "$file" ] && [ ! -L "$file" ] || refuse "$member in the tarball is not a regular file"
+actual=$(sha256sum "$file" | cut -d' ' -f1)
+[ "$actual" = "$member_sha" ] || refuse "sha256 mismatch for $member: $actual, pinned $member_sha"
+mkdir -p "$vendor"
+install -m 0644 "$file" "$vendor/.mermaid-$version.min.js.$$"
+mv -f "$vendor/.mermaid-$version.min.js.$$" "$target"
+ln -sfn "mermaid-$version.min.js" "$vendor/mermaid.min.js"
+echo "installed $target (sha256 $member_sha)"

package/payload/lanes/install/enable-web.sh

@@ -21,6 +21,8 @@ case "$device" in -*|*[!A-Za-z0-9_.-]*) echo 'invalid device name' >&2; exit 2 ;
 command -v caddy >/dev/null 2>&1 || { echo 'Install Caddy first (see docs/INSTALL.md).' >&2; exit 1; }
 export XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
 "$repo/bin/lanes" prepare "$device" "$layout"
+# A re-render, never --install: the units of the release `current` names, every link left as it is — run from
+# a tree an update moved past, this must not put the old release back (install/services.py, DEF-1835).
 python3 "$repo/install/services.py"
 systemctl --user daemon-reload
 systemctl --user enable --now lanes-web.service lanes-mobile.service

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

@@ -1,27 +1,170 @@
 #!/bin/sh
 # Linux server install/update. Called by ./install.sh --server. Never runs as root.
+#
+# --update-only (plan W9 U2, LNS-90) is the update `npx @vibelord/lanes@<release> --server --update-only` runs (by
+# hand, or by `lanes update` and its timer, plan W9 U3) on a server a full install set up. It goes through three phases:
+#   pre-commit   preflight (prerequisites, the user manager, Docker, an installed release: an update restarts what the
+#                full install enabled and enables nothing, so with no `current` it is refused), the pinned binaries
+#                (sha256), terminfo, the catalog: a failure here leaves the installed release running exactly as it was;
+#   commit       install/services.py --install: every unit, then current.previous, then the flip of `current` (W9 U1);
+#   post-commit  libexec/update.py post-commit, from the tree just installed: daemon-reload, `lanes sync`, restart
+#                lanes-statusd, try-restart each optional service (right after lanes-docsd's, install/enable-docs.sh:
+#                the docs page's pinned Mermaid, a warning when it is skipped or refused, W10 W8), `lanes
+#                install-container` per container, `lanes reload-views`, `lanes ensure --if-layout-changed` — each step
+#                runs whatever the one before it returned (`lanes sync` exiting 1 — a board with an error — is a warning
+#                in the record, which leaves the result `ok`; never the end of the update).
+# Every run is recorded in $LANES_STATE/update/last.json (DM-LANES-UPDATE-RECORD: result ok | partial | refused |
+# failed, each phase and step with its exit status) and logged in full to update/last.log; the terminal or the journal
+# gets one line per phase and step. A full install (no --update-only) records nothing; it runs enable-docs.sh right
+# after lanes-docsd's restart, never fatally, and its summary names the Mermaid outcome.
+# One install or update at a time: every run but --check first takes the run lock $LANES_STATE/update/.lock and holds
+# it to its end (fd 9); a run that finds it held writes nothing — no log, no record — and exits 3.
+# A full install enables lanes-update.timer with the other timers (plan W9 U3, LNS-91): `lanes update --timer`, 15 min
+# after a boot and every 30 min, runs this --update-only for each newer npm release, with the npx the npm wrapper
+# recorded in $LANES_STATE/update/npx (a checkout install is left alone: it updates with git pull). --update-only
+# enables nothing, that timer included: a server set up before 1.2.0 and updated only with --update-only has it off
+# until a full install or `systemctl --user enable --now lanes-update.timer` (`lanes doctor` warns; fix cycle 1 of U3).
 set -eu
 repo=$(cd "$(dirname "$0")/.." && pwd)
-start=1 check=0
+start=1 check=0 update_only=0
 for argument in "$@"; do
     case "$argument" in
         --no-start) start=0 ;;
         --check) check=1 ;;
+        --update-only) update_only=1 ;;
         -h|--help)
-            echo 'usage: ./install.sh --server [--check | --no-start]'
+            echo 'usage: ./install.sh --server [--check | --no-start | --update-only]'
             echo 'Installs pinned binaries and user services. --check changes nothing; --no-start only installs files.'
+            echo '--update-only: an update. After the switch to this release every step runs, whatever the one before it'
+            echo 'returned; the run is recorded in ~/.local/state/lanes/update/last.json and logged in update/last.log.'
+            echo 'It updates a server a full install set up: with no installed release it is refused. A full install'
+            echo 'enables lanes-update.timer, whose `lanes update --timer` runs it for each newer npm release;'
+            echo '--update-only enables nothing, that timer included (on a server set up before 1.2.0: run the full'
+            echo 'install once, or systemctl --user enable --now lanes-update.timer).'
+            echo 'Exit status of --update-only: 0 ok, 4 partial (installed; a step after the switch failed), 3 refused'
+            echo '(a prerequisite, no installed release or another install said no; nothing changed), 1 failed (nothing'
+            echo 'was installed). One install or update runs at a time: another one finding it running exits 3.'
             exit 0 ;;
         *) echo "unknown server option: $argument" >&2; exit 2 ;;
     esac
 done
+if [ "$update_only" = 1 ] && [ "$start$check" != 10 ]; then
+    echo '--update-only restarts what it installs: it takes neither --check nor --no-start' >&2; exit 2
+fi
 [ "$(uname -s)/$(uname -m)" = Linux/x86_64 ] || {
     echo 'The pinned server binaries require Linux x86_64. macOS/Linux desktops use ./install.sh --site FILE.' >&2; exit 1;
 }
 [ "$(id -u)" != 0 ] || { echo 'Run as the workspace user, not root.' >&2; exit 1; }
+share=${LANES_SHARE:-$HOME/.local/share/lanes}
+state=${LANES_STATE:-$HOME/.local/state/lanes}
+# One install or update at a time (fix cycle 1 of W9 U2): the run lock, taken before anything is written — the update's
+# log and record included — and held by this shell on fd 9 until it exits, however it ends. Two runs could otherwise
+# truncate each other's log, run the post-commit twice over (every service restarted twice, two install-container
+# copies into one volume) and race on update/last.json. A run that finds it held changes and records nothing: exit 3.
+# No child of this shell may keep fd 9 (it would hold the lock after the run): those that can leave a process behind
+# (`lanes sync`, libexec/update.py) get `9>&-`, and update.py runs each post-commit step with no descriptor but its
+# stdio. --check changes nothing: no lock.
+if [ "$check" = 0 ]; then
+    command -v python3 >/dev/null 2>&1 || { echo 'Missing prerequisite: python3 (see docs/INSTALL.md)' >&2; exit 1; }
+    mkdir -p "$state/update"
+    exec 9>>"$state/update/.lock"
+    lock_status=0
+    if [ "$update_only" = 1 ]; then
+        python3 "$repo/libexec/update.py" lock --state "$state" --fd 9 --mode update || lock_status=$?
+    else
+        python3 "$repo/libexec/update.py" lock --state "$state" --fd 9 --mode install >&2 || lock_status=$?
+    fi
+    case $lock_status in
+        0) ;;
+        3) exit 3 ;;
+        *) echo "could not take the run lock $state/update/.lock (exit $lock_status)" >&2; exit 1 ;;
+    esac
+fi
+# The phases of --update-only. `phase NAME`: the phase before it ended with exit 0 (reported and kept for the record);
+# NAME runs next, under a `== NAME` line in the log. A full install only names them.
+phase=preflight steps='' committed=0
+phase() {
+    if [ "$update_only" = 1 ]; then
+        steps="$steps --step $phase=0"
+        printf 'ok    %s\n' "$phase" >&3
+        printf '== %s\n' "$1"
+    fi
+    phase=$1
+}
+# --update-only, before the commit: whatever ends the run is recorded (`set -e`, an `exit`, a signal). refused: the
+# preflight (no installed release among its checks), or install/services.py's refusal (exit 3: another install holds
+# its lock, a link that is no symlink);
+# failed: anything else — unless the flip happened before services.py failed (its command link), which is installed
+# but not restarted: partial. After the commit the post-commit records its own outcome.
+update_ended() {
+    status=$1
+    set +e
+    trap - EXIT HUP INT TERM
+    [ "$committed" = 0 ] || exit "$status"
+    result=failed code=1
+    case $phase in
+        preflight) result=refused code=3 ;;
+        commit)
+            if [ "$status" = 3 ]; then result=refused code=3
+            elif [ "$(readlink -e "$HOME/.local/share/lanes/current")" = "$tree" ] && [ "$before" != "$tree" ]; then
+                result=partial code=4
+            fi ;;
+    esac
+    printf 'FAIL  %s (exit %s)\n' "$phase" "$status" >&3
+    # the last lines the failing phase wrote (after its `== NAME` line in the log)
+    awk '/^== /{n=0; next} {line[n++]=$0} END{for (i = (n > 5 ? n - 5 : 0); i < n; i++) print "      " line[i]}' \
+        "$log" >&3
+    # shellcheck disable=SC2086 # $steps is `--step NAME=RC` words
+    python3 "$repo/libexec/update.py" record --result "$result" --state "$state" --tree "$tree" --before "$before" \
+        --log "$log" --started "$started" $steps --step "$phase=$status" 9>&- ||
+        printf 'could not write %s\n' "$state/update/last.json" >&3
+    case $result in
+        refused)
+            if [ -n "$before" ]; then printf 'refused: nothing changed; %s still runs — log %s\n' "$before" "$log" >&3
+            else printf 'refused: nothing changed; no release is installed here — log %s\n' "$log" >&3
+            fi ;;
+        partial) printf 'partial: %s is installed, nothing was restarted — log %s\n' "$tree" "$log" >&3 ;;
+        *) printf 'failed: nothing was installed; %s still runs — log %s\n' "${before:-the installed release}" "$log" >&3 ;;
+    esac
+    exit "$code"
+}
+if [ "$update_only" = 1 ]; then
+    tree=$(cd "$repo" && pwd -P)        # as install/services.py resolves it for the link
+    log=$state/update/last.log
+    : > "$log"
+    # From here on the run's own output goes to the log (appended: the post-commit appends to it too); fd 3 is the
+    # terminal or the journal.
+    exec 3>&1 >>"$log" 2>&1
+    before=$(readlink -e "$HOME/.local/share/lanes/current" || :)
+    started=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    trap 'update_ended $?' EXIT
+    trap 'exit 129' HUP
+    trap 'exit 130' INT
+    trap 'exit 143' TERM
+    printf 'lanes update: %s -> %s (log %s)\n' "${before:-nothing installed}" "$tree" "$log" >&3
+    echo '== preflight'
+    # An update restarts what a full install enabled — statusd, the timers, the enrolment service — and enables
+    # nothing; with no installed release it would end `ok` on a server where none of that runs, or ever starts again
+    # after a reboot (fix cycle 1 of W9 U2). Refused, before anything is fetched or installed.
+    if [ -z "$before" ]; then
+        echo "no release is installed here: $HOME/.local/share/lanes/current names no tree"
+        echo 'an update only restarts what a server install set up: install it first, without --update-only'
+        exit 3
+    fi
+fi
 for command in python3 curl tar sha256sum infocmp tic install systemctl docker tmux; do
     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")'
+# --- docs store encryption at rest (W10 W5, LNS-106) ------------------------------------------------------------
+# LANES_DOCS_AGE_RECIPIENT in lanes-docsd.service's drop-in encrypts each document's docs-store copy with `age -r`
+# (default off; RUNBOOK "Docs service", encryption at rest). Set where no `age` binary is on PATH, every upload and
+# publish would fail: refused here, before anything is installed, with libexec/docs_store.py's reason.
+check_docs_age() {
+    python3 "$repo/libexec/docs_store.py" check-age || exit 1
+}
+check_docs_age
+# --- end docs store encryption at rest -------------------------------------------------------------------------
 export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
 if [ "$start" = 1 ]; then
     systemctl --user show-environment >/dev/null
@@ -31,8 +174,7 @@ if [ "$check" = 1 ]; then
     echo 'Server prerequisites: ready'
     exit 0
 fi
-share=${LANES_SHARE:-$HOME/.local/share/lanes}
-state=${LANES_STATE:-$HOME/.local/state/lanes}
+phase binaries
 mkdir -p "$share/bin" "$share/dl" "$state/flags"
 # 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.
@@ -62,29 +204,77 @@ grep -v '^#' "$repo/holders.lock" | while read -r name version sha url flag _res
     trap - EXIT HUP INT TERM
     echo "installed $target"
 done
+phase terminfo
 if ! infocmp xterm-lanesview >/dev/null 2>&1; then
     infocmp -x xterm-256color | sed '1,3s/^xterm-256color|/xterm-lanesview|/' > "$share/dl/xterm-lanesview.ti"
     tic -x -o "$HOME/.terminfo" "$share/dl/xterm-lanesview.ti"
 fi
+# Before the commit: nothing here depends on the release that is installed.
+phase catalog
 [ -e "$state/registry.json" ] || touch "$state/flags/coexist"
-python3 "$repo/install/services.py"
 catalog=$HOME/.config/lanes/workspaces/catalog.json
 if [ ! -e "$catalog" ] && [ ! -d "$repo/workspaces" ] && [ -z "${LANES_WORKSPACES:-}" ]; then
     mkdir -p "$(dirname "$catalog")"
     printf '{"version":1,"workspaces":[]}\n' > "$catalog"
 fi
+phase commit
+# --install: the server installer is the one caller that makes its own tree the installed release (`current`);
+# the enable steps re-render the release `current` names (install/services.py, DEF-1835).
+python3 "$repo/install/services.py" --install
+committed=1
+if [ "$update_only" = 1 ]; then
+    phase post-commit
+    # The post-commit of the release just installed records the outcome itself (`partial` before its first step);
+    # its stdout is the terminal or the journal, its steps write to the log.
+    status=0
+    # shellcheck disable=SC2086 # $steps is `--step NAME=RC` words
+    python3 "$repo/libexec/update.py" post-commit --state "$state" --tree "$tree" --before "$before" --log "$log" \
+        --started "$started" $steps >&3 3>&- 9>&- || status=$?
+    case $status in
+        0|4) exit "$status" ;;
+        *) printf 'partial: the post-commit ended with exit %s (log %s)\n' "$status" "$log" >&3; exit 4 ;;
+    esac
+fi
+mermaid="not installed (--no-start) — sh $repo/install/enable-docs.sh installs it"
 if [ "$start" = 1 ]; then
     systemctl --user daemon-reload
-    "$repo/bin/lanes" sync
-    systemctl --user enable --now lanes-statusd.service lanes-sync.timer lanes-ensure.timer lanes-gc.timer
+    # A failing sync (a board's container down, a registry it cannot read) is reported; the services still start.
+    "$repo/bin/lanes" sync 9>&- || echo 'warning: lanes sync failed (above); the services start anyway (run: lanes sync)' >&2
+    # lanes-update.timer (W9 U3): its OnBootSec is past on a running host, so it checks once now — refused while this
+    # install holds the run lock — then every 30 min. On a checkout install `lanes update` does nothing. Only this full
+    # install enables it: --update-only (above) never does, and `lanes doctor` names a timer that is off.
+    systemctl --user enable --now lanes-statusd.service lanes-sync.timer lanes-ensure.timer lanes-gc.timer \
+        lanes-update.timer
     # The enrolment service (libexec/enrold.py) runs the code of THIS install: enable, then (re)start it.
     systemctl --user enable lanes-enrold.service
     systemctl --user restart lanes-enrold.service
+    # The docs service (libexec/docsd.py, W10 W3) likewise; it refuses every request until `lanes enrol mode request`
+    # pins the Serve header check.
+    systemctl --user enable lanes-docsd.service
+    systemctl --user restart lanes-docsd.service
+    # --- the docs page's pinned Mermaid (W10 W8, LNS-109) ---------------------------------------------------------
+    # install/enable-docs.sh (RUNBOOK "Mermaid pin"), never fatal: the install goes on whatever it exits, and the
+    # summary below names the outcome — 0 ok (installed, or already present with the pinned digest: no download),
+    # 1 skipped (a prerequisite or the download), 3 refused (no valid pin, a digest mismatch: nothing installed), any
+    # other status failed. An update (--update-only) runs it as a post-commit step (libexec/update.py DOCS_STEP).
+    mermaid_rc=0
+    mermaid_said=$(sh "$repo/install/enable-docs.sh" 2>&1 9>&-) || mermaid_rc=$?
+    [ -z "$mermaid_said" ] || printf '%s\n' "$mermaid_said"
+    mermaid_reason=$(printf '%s\n' "$mermaid_said" | awk 'NF { line = $0 } END { print line }')
+    [ -n "$mermaid_reason" ] || mermaid_reason="exit $mermaid_rc, no output"
+    case $mermaid_rc in
+        0) mermaid='ok' ;;
+        1) mermaid="skipped ($mermaid_reason) — diagrams show as source until sh $repo/install/enable-docs.sh succeeds" ;;
+        3) mermaid="refused ($mermaid_reason) — nothing was installed; see RUNBOOK \"Mermaid pin\"" ;;
+        *) mermaid="failed (exit $mermaid_rc: $mermaid_reason) — sh $repo/install/enable-docs.sh" ;;
+    esac
+    # --- end the docs page's pinned Mermaid -----------------------------------------------------------------------
     # A running web frontend reads the Caddyfile of the tree it was started from; an npm update stages a new tree,
     # so a reload would keep the old routes (/enrol/ included): restart it, only when it runs. Clients reconnect.
     systemctl --user try-restart lanes-mobile.service
 fi
 printf '\nServer installed from %s\n' "$repo"
+echo "Mermaid for the docs page: $mermaid"
 echo 'Configure boards in ~/.config/lanes/workspaces/; see workspaces.example/README.md.'
 echo 'Next: lanes install-container CONTAINER; lanes sync; lanes doctor'
 echo 'Web access and host cleanup/guard timers remain opt-in; see docs/INSTALL.md.'

package/payload/lanes/install/services.py

@@ -1,18 +1,52 @@
 #!/usr/bin/env python3
-"""Register this checkout's user services without starting or restarting them."""
+"""Register this checkout's user services without starting or restarting them.
+
+    python3 install/services.py --install    the server installer (install/host-install.sh): this tree becomes `current`
+    python3 install/services.py              a re-render (install/enable-web.sh): the units of the tree `current` names
+
+The units, LANES_REPO and ~/.local/bin/lanes name the `current` link (~/.local/share/lanes/current), never the tree
+it points at (plan W9 U1, LNS-89), and the link is moved last, in one rename(2): the update's commit point. Before it
+every unit is written — naming the link, so its text does not change with the release and nothing runs differently
+yet — and `current.previous` records the tree the link named (the rollback target, plan W9 U3). After it
+~/.local/bin/lanes is made to point through the link. A failure before the flip leaves the installed release as it
+was; services are never started or restarted here (install/host-install.sh does that).
+
+Only the server installer moves `current` off a tree it names (`--install`, register(install=True)). Every other
+caller re-renders: the enable steps (install/enable-web.sh, libexec/studio_host.py step 6) run from whatever tree
+their shell found, and after an update that can be the old one — so a re-render renders the templates of the tree
+`current` names and leaves every link as it is; it writes `current` only where none names a tree yet. Installs and
+re-renders take one exclusive lock, ~/.local/share/lanes/.install.lock, and read `current` inside it, so neither acts
+on a link the other has since moved (fix cycle 1 of W9 U1, DEF-1835)."""
+import contextlib
+import fcntl
 import json
 import os
+import secrets
 import shutil
 import sys
 import subprocess
+import time
 from pathlib import Path
 import tempfile
 
 
+class Refusal(Exception):
+    """A refusal raised before anything is written; the command line exits 3 for it (plan W9 U2: host-install.sh
+    --update-only records `refused`). Each concrete refusal is also the ValueError or RuntimeError callers catch."""
+
+
+class RefusedValue(Refusal, ValueError):
+    pass
+
+
+class RefusedLock(Refusal, RuntimeError):
+    pass
+
+
 def unit_value(value, command=False):
     value = str(value)
     if any(c in value for c in '\r\n\0'):
-        raise ValueError('installation paths must not contain control characters')
+        raise RefusedValue('installation paths must not contain control characters')
     value = value.replace('\\', '\\\\').replace('"', '\\"').replace('%', '%%')
     return value.replace('$', '$$') if command else value
 
@@ -115,8 +149,79 @@ def manager_unit_dir(home):
     return default
 
 
-def register(repo, home, share, state, workspaces=None, economy=None, notify=None, xdg=None, units_dir=None):
+def linked_tree(link):
+    """The existing directory `link` names, resolved; None when `link` is no symlink, dangles (a pruned tree) or loops."""
+    if not link.is_symlink():
+        return None
+    try:
+        target = link.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return None
+    return target if target.is_dir() else None
+
+
+def swap_link(link, target):
+    """Point `link` at `target` in one rename(2): a new symlink made beside it (same directory, so the rename is
+    atomic), then os.replace over it. A reader sees the old link or the new one, never none — unlink-then-symlink left
+    a moment without `current` and, interrupted, no link at all."""
+    link.parent.mkdir(parents=True, exist_ok=True)
+    temporary = link.parent / f'.{link.name}.{os.getpid()}.{secrets.token_hex(4)}'
+    os.symlink(str(target), str(temporary))
+    try:
+        os.replace(str(temporary), str(link))
+    except BaseException:
+        try:
+            os.unlink(str(temporary))
+        except OSError:
+            pass
+        raise
+
+
+# The install lock: beside the `current` link it guards (under the home, as the link is), held from the refusal check
+# through the command link. Never removed: unlinking a flock file lets the next caller lock a new inode while a
+# waiter still holds the old one. LOCK_WAIT bounds the wait — register itself runs no command and waits on nothing
+# else, so a holder that keeps it longer is stuck, and an install says so rather than hang.
+INSTALL_LOCK = '.install.lock'
+LOCK_WAIT = 60
+
+
+def install_lock_path(home):
+    return Path(home) / '.local/share/lanes' / INSTALL_LOCK
+
+
+@contextlib.contextmanager
+def install_lock(home):
+    """Hold the install lock (an exclusive flock(2), released when the descriptor closes — by a crash too)."""
+    path = install_lock_path(home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
+    try:
+        deadline = time.monotonic() + LOCK_WAIT
+        while True:
+            try:
+                fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise RefusedLock(f'another install holds {path} (waited {LOCK_WAIT:g} s); nothing was changed — '
+                                       'run the install again once it has finished') from None
+                time.sleep(0.1)
+        yield
+    finally:
+        os.close(descriptor)
+
+
+def register(repo, home, share, state, workspaces=None, economy=None, notify=None, xdg=None, units_dir=None,
+             install=False):
+    """Render every unit and point the links. install=True: the server installer (or a rollback) — `repo` becomes the
+    installed release. install=False: a re-render — when `current` names another existing tree, that tree's templates
+    are rendered and no link moves (DEF-1835); `current` is written only where it names no tree."""
     repo, home, share, state = (Path(p).resolve() for p in (repo, home, share, state))
+    with install_lock(home):
+        _register(repo, home, share, state, workspaces, economy, notify, xdg, units_dir, install)
+
+
+def _register(repo, home, share, state, workspaces, economy, notify, xdg, units_dir, install):
     if xdg is None:
         ambient = {name: os.environ[name] for name in XDG_ROOTS if os.environ.get(name)}
         xdg = recorded_xdg(state)
@@ -127,12 +232,24 @@ def register(repo, home, share, state, workspaces=None, economy=None, notify=Non
                   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}
+    # Under the home, never $XDG_DATA_HOME: lanes_lib.current_tree and the npm wrapper's prune (plan.mjs currentLink)
+    # read the link here (W9 U0, DEF-1783).
     current = home / '.local/share/lanes/current'
-    links = ((current, repo), (home / '.local/bin/lanes', repo / 'bin/lanes'))
-    for link, _ in links:
+    previous = current.with_name('current.previous')
+    command = home / '.local/bin/lanes'
+    for link in (current, previous, command):
         if link.exists() and not link.is_symlink():
-            raise ValueError(f'{link} already exists and is not a symlink')
-    settings = [('LANES_REPO', repo), ('LANES_SHARE', share), ('LANES_STATE', state)]
+            raise RefusedValue(f'{link} already exists and is not a symlink')
+    # Read under the install lock: an install that lands between this read and the flip below cannot exist.
+    before = linked_tree(current)
+    if not install and before is not None and before != repo:
+        print(f'services.py: {current} names {before}, not this tree ({repo}): the units are rendered from {before} '
+              'and no link moves — only the server installer installs a release (npx @vibelord/lanes --server, or '
+              './install.sh --server from a checkout)', file=sys.stderr)
+        repo = before
+    # W9 U1: the units name the link. A unit's text then no longer changes with the release, and the flip below moves
+    # every unit (and the Caddyfile root LANES_REPO feeds) to the new tree at once.
+    settings = [('LANES_REPO', current), ('LANES_SHARE', share), ('LANES_STATE', state)]
     if workspaces:
         settings.append(('LANES_WORKSPACES', Path(workspaces).resolve()))
     environment = ''.join(f'Environment="{name}={unit_value(value)}"\n' for name, value in settings)
@@ -147,7 +264,7 @@ def register(repo, home, share, state, workspaces=None, economy=None, notify=Non
     for source in sorted((repo / 'systemd').iterdir()):
         if source.name.startswith('.') or source.suffix not in ('.service', '.timer', '.slice') or not source.is_file():
             continue
-        content = source.read_text().replace('@REPO@', unit_value(repo, command=True))
+        content = source.read_text().replace('@REPO@', unit_value(current, 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))
@@ -170,16 +287,29 @@ def register(repo, home, share, state, workspaces=None, economy=None, notify=Non
         finally:
             if os.path.exists(temporary):
                 os.unlink(temporary)
-    for link, target in links:
-        link.parent.mkdir(parents=True, exist_ok=True)
-        if link.is_symlink():
-            link.unlink()
-        link.symlink_to(target)
+    # The commit point. The tree `current` named becomes `current.previous` when it still exists and is not the tree
+    # being installed (a re-install, or a re-render — which installs the tree `current` names — must not make the
+    # rollback target itself; a pruned tree is no target, so the last one recorded stays). Then the flip; then the
+    # command, through the link, so a later flip (an update, a rollback) moves it too.
+    if before is not None and before != repo:
+        swap_link(previous, before)
+    swap_link(current, repo)
+    swap_link(command, current / 'bin/lanes')
 
 
 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'), economy_settings(os.environ), notify_settings(os.environ),
-             units_dir=manager_unit_dir(Path.home()))
+    if sys.argv[1:] not in ([], ['--install']):
+        print('usage: services.py [--install]', file=sys.stderr)
+        sys.exit(2)
+    # A refusal changes nothing — another install holds the lock, `current`, `current.previous` or the command is no
+    # symlink, or a path cannot be written into a unit (each raised before the first write) — and exits 3, which
+    # host-install.sh --update-only records as `refused` (plan W9 U2). Any other failure keeps its traceback, exit 1.
+    try:
+        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'), economy_settings(os.environ), notify_settings(os.environ),
+                 units_dir=manager_unit_dir(Path.home()), install=sys.argv[1:] == ['--install'])
+    except Refusal as error:
+        print(f'services.py: refused, nothing was changed: {error}', file=sys.stderr)
+        sys.exit(3)