@vibelord/lanes 1.1.0 → 1.2.0

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,23 +1,155 @@
 #!/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, `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) prints as before and records nothing.
+# 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
@@ -31,8 +163,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,21 +193,46 @@ 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
 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

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)

package/payload/lanes/install.sh

@@ -4,6 +4,8 @@
 #
 #   ./install.sh                 install or update the client on this machine
 #   ./install.sh --server        install or update the Linux workspace server
+#   ./install.sh --server --update-only   update it: every step after the switch runs whatever the one before it
+#                returned; the run is recorded in ~/.local/state/lanes/update/last.json (exit 0 · 4 · 3 · 1)
 #   ./install.sh --check         verify terminal, SSH path, key and server (changes nothing)
 #   ./install.sh --uninstall     remove what the installer added (your SSH key and ~/Lanes Uploads are kept)
 #
@@ -41,9 +43,14 @@
 # :8443/enrol/) authorizes it — at once for an invite code; without one, on a terminal, the installer offers to ask the
 # site's members and waits up to 10 min (LANES_ENROL_WAIT) for an approval. The client never edits authorized_keys.
 # No service, a refused code, or no code and no terminal: the public key is printed for the admin (exit 3), as before.
+# Run by the npm wrapper with an invite, the installer first asks that service which release the server runs: a newer
+# one than this installer ends the run before anything is installed or redeemed (exit 5), and the wrapper runs the
+# server's release with the same options, which redeems the invite (LANES_NO_SELF_UPDATE=1: never asked).
 #
 # Exit status: 0 ready to use · 3 installed, but this machine's key is not authorized on the server yet ·
 #              4 installed, but not in the tailnet, or the server is not reachable or did not answer in time (busy?) ·
+#              5 nothing installed: the server runs a newer release (only when LANES_WRAPPER_REPLY names the npm
+#                wrapper's hand-over file; the wrapper then runs that release) ·
 #              1 error
 set -eu
 here=$(cd "$(dirname "$0")" && pwd)
@@ -81,7 +88,7 @@ while [ $# -gt 0 ]; do
         --palette) palette=1 ;;
         --no-palette) palette=0 ;;
         --yes|-y) assume_yes=1 ;;
-        -h|--help) sed -n '2,47p' "$0"; exit 0 ;;
+        -h|--help) sed -n '2,54p' "$0"; exit 0 ;;
         *) echo "install.sh: unknown option $1 (see --help)" >&2; exit 1 ;;
     esac
     shift
@@ -1142,7 +1149,7 @@ report_key_taken() {
 # and nobody at a terminal to ask: report_server's exit-3 text, unchanged — except a 409 (the device name or the key is
 # already a member's), which names the re-run that joins instead (report_device_taken, report_key_taken). The code
 # goes in a request body on stdin: never on a command line, in a file or in the output.
-enrol_file=$config/enrol-request enrol_caller= enrol_conflict= enrol_via=
+enrol_file=$config/enrol-request enrol_caller= enrol_conflict= enrol_via= enrol_base= enrol_resolve=
 invite_problem() {   # CODE -> why it is not an invite code for this profile, or nothing. Names the prefix at most.
     ip_bad='not an invite code (letters, digits and dashes, like LN-xxxx-xxxxxxxxxxxx)'
     case "$1" in ''|-*|*-|*--*|*[!A-Za-z0-9-]*) printf '%s' "$ip_bad"; return 0 ;; *-*) ;; *) printf '%s' "$ip_bad"; return 0 ;; esac
@@ -1169,14 +1176,18 @@ json_get() {   # PATH -> the value at that path of $http_body (strings unquoted)
 }
 # -> enrol_base (scheme://host[:port]), enrol_host, enrol_port, enrol_ip (the tailnet address to use when this machine
 # cannot resolve the name: an IPv4 LANES_SERVER_HOST); 1 + enrol_note when there is no service to ask.
-# LANES_ENROL_URL replaces the base (development and tests); the name and address logic stays the same.
+# LANES_ENROL_URL replaces the base (development and tests); the name and address logic stays the same. Called again in
+# the same run (the K3 question before the install, then enrol), it keeps the --resolve the first calls learned for the
+# same base: a name this machine cannot resolve is not tried again (each try costs up to curl's 5 s to connect).
 enrol_target() {
-    enrol_base=${LANES_ENROL_URL:-} enrol_resolve= enrol_note=
+    et_known=$enrol_base
+    enrol_base=${LANES_ENROL_URL:-} enrol_note=
     if [ -z "$enrol_base" ]; then
         if [ -z "$server_name" ]; then enrol_note='this site profile names no LANES_SERVER_NAME (its enrolment service answers under that name)'; return 1; fi
         enrol_base=https://${server_name%.}:8443
     fi
     enrol_base=${enrol_base%/}
+    [ "$enrol_base" = "$et_known" ] || enrol_resolve=
     et_hostport=${enrol_base#*://}
     case "$enrol_base" in http://*|https://*) ;; *) enrol_note='LANES_ENROL_URL is not an http(s) URL'; return 1 ;; esac
     case "$et_hostport" in ''|*/*|*[!A-Za-z0-9.:-]*) enrol_note='LANES_ENROL_URL is not scheme://host[:port]'; return 1 ;; esac
@@ -1289,7 +1300,8 @@ enrol_site() {   # GET /enrol/site -> 0, request_mode and enrol_caller; or 1 and
     # (a server without the service hands /enrol/site to its web client: a page, not this document)
     if ! enrol_json; then enrol_note="no enrolment service at $enrol_base/enrol/ (the answer is not JSON)"; return 1; fi
     # lanes-enrold's /site always says request_mode, true or false: that is what tells it from any other JSON. Its
-    # `version` is the server's Lanes release, not a wire number (wire v1 is additive only, and none is served).
+    # `version` is the server's Lanes release, not a wire number (wire v1 is additive only, and none is served): only
+    # enrol_preflight reads it, to hand an invite over to that release's installer; no admission ever depends on it.
     request_mode=$(json_get /request_mode)
     case "$request_mode" in
         true|false) ;;
@@ -1298,6 +1310,55 @@ enrol_site() {   # GET /enrol/site -> 0, request_mode and enrol_caller; or 1 and
     # The tailnet login the service received (null outside request mode): the owner a request is filed under.
     enrol_caller=$(enrol_clean "$(json_get /caller)")
 }
+# ---- the server's release first (W9 K3, LNS-88) ---------------------------------------------------------------------
+# An invite is redeemed once, so the installer that redeems it should be the server's own release. Run by the npm
+# wrapper (which names a file in LANES_WRAPPER_REPLY) with an invite (--invite or LANES_INVITE), the installer asks the
+# enrolment service which release the server runs — /enrol/site's `version` — BEFORE anything is installed, sent or
+# redeemed. A newer one than this tree's VERSION ends the run: `update-to=<release>` into that file, one line, exit 5.
+# The wrapper then runs `npx --yes @vibelord/lanes@<release>` with the same options (the code moved to LANES_INVITE)
+# and LANES_NO_SELF_UPDATE=1, which skips this question: one hand-over at most. Anything else changes nothing and the
+# install goes on with this tree: no invite; LANES_NO_SELF_UPDATE (any value); a tailnet site this machine is not in
+# yet (one `tailscale status`, no login — the install's own Tailscale step follows); no service or no answer (one
+# bounded call, as enrol_call makes every call); an equal, older or unparseable release on either side. Without the
+# wrapper (a checkout's ./install.sh) a newer server is one line and the install goes on.
+release_key() {   # RELEASE -> "MAJOR MINOR PATCH", nothing for what is no release
+    # The rule `lanes hello` compares by (bin/lanes version_key): major.minor.patch, an optional -/+ suffix that is not
+    # compared, at most 32 characters — and here each number at most 9 digits, so test(1) compares it exactly.
+    case "$1" in ''|*[!A-Za-z0-9.+-]*) return 0 ;; esac
+    [ "${#1}" -le 32 ] || return 0
+    printf '%s\n' "$1" | sed -n 's/^\([0-9]\{1,9\}\)\.\([0-9]\{1,9\}\)\.\([0-9]\{1,9\}\)\([-+][A-Za-z0-9.]\{1,\}\)\{0,1\}$/\1 \2 \3/p'
+}
+release_newer() {   # SERVER MINE -> 0 when both are releases and SERVER's major.minor.patch is the higher, as numbers
+    rn_server=$(release_key "$1") rn_mine=$(release_key "$2")
+    [ -n "$rn_server" ] && [ -n "$rn_mine" ] || return 1
+    # shellcheck disable=SC2086
+    set -- $rn_server $rn_mine                       # (digits only: no glob, no blank inside a number)
+    if [ "$1" -ne "$4" ]; then [ "$1" -gt "$4" ]; return; fi
+    if [ "$2" -ne "$5" ]; then [ "$2" -gt "$5" ]; return; fi
+    [ "$3" -gt "$6" ]
+}
+enrol_preflight() {
+    [ -n "$invite" ] && [ -z "${LANES_NO_SELF_UPDATE:-}" ] || return 0
+    if tailnet_site; then
+        ts=$(tailscale_bin) || return 0
+        tailscale_look
+        [ "$ts_state" = Running ] && [ "$ts_online" = true ] || return 0
+    fi
+    enrol_target && enrol_site || return 0
+    pf_server=$(json_get /version)
+    pf_mine=dev; if [ -r "$here/VERSION" ]; then pf_mine=$(tr -cd 'A-Za-z0-9._+-' < "$here/VERSION"); fi
+    release_newer "$pf_server" "$pf_mine" || return 0
+    if [ -z "${LANES_WRAPPER_REPLY:-}" ]; then
+        say "server runs $pf_server; this installer is $pf_mine — going on with $pf_mine"
+        return 0
+    fi
+    if ! { printf 'update-to=%s\n' "$pf_server" > "$LANES_WRAPPER_REPLY"; } 2>/dev/null; then
+        warn "server runs $pf_server; this installer is $pf_mine, and the npm wrapper's hand-over file cannot be written — going on with $pf_mine"
+        return 0
+    fi
+    say "server runs $pf_server: fetching that installer first (this one is $pf_mine; nothing is installed yet, and the invite is kept for it)"
+    exit 5
+}
 enrol_key() {   # -> enrol_pubkey "ssh-ed25519 <base64>" (enrold writes its own comment); 1, said, for any other key
     enrol_pubkey= kt= kb=
     if [ -r "$key.pub" ]; then read -r kt kb _ < "$key.pub" || :; fi
@@ -1451,7 +1512,7 @@ enrol() {
 do_install() {
     command -v ssh >/dev/null 2>&1 || die 'OpenSSH (ssh) is required'
     case "$os" in Darwin|Linux) ;; *) die "unsupported system: $os (macOS and Linux only)" ;; esac
-    resolve_options; load_site; check_invite; src=$here/client
+    resolve_options; load_site; check_invite; enrol_preflight; src=$here/client
     head_ "lanes client $(cat "$here/VERSION" 2>/dev/null || echo dev) -> $server_user@$server_alias"
     choose_device; choose_key; ensure_key
     install_client; src=$target
@@ -1488,7 +1549,7 @@ do_install() {
             say 'Open the window:   lanes-window          (Omarchy: Super+Shift+L · macOS: the Lanes app)'
             say 'In any terminal:   lanes-launch          one lane only: lanes-launch lane <id> · list: lanes-launch ls'
             say 'Phone or browser:  lanes-launch web phone · lanes-launch web laptop   (in your own terminal: a login token)'
-            say 'Keys:  Ctrl-Alt-←/→ board · Ctrl-Alt-↑/↓ lane · Ctrl-Alt-/ find · Ctrl-Alt-u upload box · close the window to detach'
+            say 'Keys:  Ctrl-Alt-←/→ board · Ctrl-Alt-↑/↓ lane · Ctrl-Alt-/ find · Ctrl-Alt-u upload box · Ctrl-Alt-l sidebar · close the window to detach'
             exit 0 ;;
         unauthorized) exit 3 ;;
         *) exit 4 ;;