@vibelord/lanes 1.1.1 → 1.2.0

package/payload/lanes/libexec/update.py

@@ -0,0 +1,972 @@
+#!/usr/bin/env python3
+"""A server update after its commit point, and the record of every update run (plan W9 U2, LNS-90). Python 3 stdlib.
+
+  python3 libexec/update.py post-commit --state DIR --tree DIR --log FILE [--before DIR] [--started UTC] [--step NAME=RC …]
+  python3 libexec/update.py record --result refused|failed|partial --state DIR --tree DIR --log FILE [--before DIR]
+                                   [--started UTC] [--step NAME=RC …]
+  python3 libexec/update.py lock --state DIR --fd N --mode update|install
+
+`install/host-install.sh --update-only` (what `npx @vibelord/lanes@<release> --server --update-only` runs) installs a
+release in three phases. pre-commit: preflight (prerequisites, the user manager, Docker, and a release installed
+already: an update restarts what a full server install enabled), the pinned binaries (sha256-verified), terminfo, the
+catalog — a failure there leaves the installed release running as it was. commit: `install/services.py --install`
+(every unit, `current.previous`, then the flip of `current`; W9 U1). post-commit: this module, run from the tree just
+installed. Its steps run in this order, each whatever the ones before it returned, each bounded by STEP_TIMEOUT seconds
+(its whole process group is stopped when it does not finish):
+  systemctl --user daemon-reload · lanes sync · systemctl --user restart lanes-statusd.service ·
+  systemctl --user try-restart <unit> for each optional service in TRY_RESTART (restarted only when it runs) ·
+  lanes install-container <name> for each container `lanes sync` recorded with a home volume (containers.json) ·
+  lanes reload-views (the viewports; sidebars swap by themselves, W9 U5) · lanes ensure --if-layout-changed (W9 U6).
+Step output goes to the log (`update/last.log`); stdout gets one line per step and a summary.
+
+The record, `<state>/update/last.json` (DM-LANES-UPDATE-RECORD), is one JSON object {checked_at, latest, installed,
+previous, result, steps: [{name, rc[, warning]}], log}. result: `ok` every phase and step exited 0 or only warned;
+`partial` the release is installed but a step after the commit failed (also while the post-commit runs: it is written
+before the first step); `refused` a prerequisite, no installed release, or another install holding the install lock
+said no and nothing changed; `failed` nothing was installed. A warning (WARN_RC) is a step's own report of a condition
+the update neither caused nor can mend — `lanes sync` exiting 1 for a board with an error — recorded with its rc and
+`"warning": true`, never a failure. Keys it does not own (a rollback's mark, plan W9 U3) are kept. host-install.sh
+writes `refused`, `failed` and a `partial` commit through `record`; `post-commit` writes its own.
+
+The run lock, `<state>/update/.lock` (fix cycle 1 of W9 U2): every server install and update takes it before it writes
+anything — the log and the record included — and holds it to its end, so two runs never interleave a post-commit or
+race on the record. host-install.sh opens the file on a descriptor of its own and `lock` takes an flock(2) on that
+descriptor without waiting: the lock belongs to the open file, so it is held for as long as the installer's shell
+lives (by nothing it starts: the shell closes the descriptor for its long-running children, and run_step closes every
+descriptor but the step's stdio), and a crash releases it. A run that finds it held writes nothing and exits 3. `lanes
+update` (plan W9 U3) runs host-install.sh, so it must not hold this lock while that runs; a rollback that calls
+post_commit() itself takes it with take_run_lock(). Exit: post-commit 0 ok, 4 partial; record 0; lock 0 taken, 3 held
+by another run (one line on stdout says which); 2 usage.
+
+`lanes update` (plan W9 U3, LNS-91; update_main, below) is what lanes-update.timer runs every 30 min (`--timer`): one
+at a time (the flock `<state>/locks/update.lock`), from an npm-installed server only (`current` names a tree the npm
+wrapper staged). A last run that ended `partial` gets its post-commit again first, from the tree `current` names; then,
+unless a check answered less than INTERVAL ago (`--now` asks anyway), the registry is asked which release the channel's
+dist-tag names (`latest`, or `lanes-stable` with `channel=stable` in ~/.config/lanes/update.conf). A release newer than
+the installed one, and not the one a rollback left (`bad`), is installed with the npx the npm wrapper recorded at
+install (`<state>/update/npx`): `npx --yes @vibelord/lanes@<release> --server --update-only`, with the run lock
+released meanwhile (host-install.sh takes it), the check handed over in LANES_UPDATE_LATEST and LANES_UPDATE_CHECKED_AT,
+and the settings the installed units carry (LANES_WORKSPACES, LANES_THROTTLE_*, LANES_NOTIFY_CONF) given again when this
+environment lacks them, so a timer's update renders the units as the install that set them up did. `--rollback`
+installs the tree `current.previous` names again in place (install/services.py of this tree; no network), marks the
+release it left `bad` in the same write that records the flip (`partial` until the post-commit has run; SIGINT, SIGTERM
+and SIGHUP wait for the flip and that write), then runs its post-commit; `--status` prints the record. Every check is
+recorded in the record's `check` (DM-LANES-UPDATE-RECORD) — when, what the registry said and what came of it — and a
+rollback's `bad`, a re-run's `rerun`; the install's own keys stay the installer's. `lanes doctor`'s update line
+(doctor_line) reads the record and whether lanes-update.timer is enabled (its timers.target.wants link)."""
+import argparse
+import calendar
+import contextlib
+import fcntl
+import importlib.util
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import signal
+import stat
+import subprocess
+import sys
+import time
+import traceback
+
+import lanes_lib as L
+
+STEP_TIMEOUT = 300          # seconds per post-commit step; then its process group is stopped and the step is rc 124
+STOP_WAIT = 5               # seconds between SIGTERM and SIGKILL of a step's process group, and after it
+# The optional services a post-commit restarts only when they run (`systemctl try-restart`), in this order. Each keeps
+# its enable state: an update never switches on a unit the operator left off (economy, notify, web: operator gates).
+TRY_RESTART = ('lanes-economy.service', 'lanes-notify.service', 'lanes-enrold.service', 'lanes-mobile.service',
+               'lanes-web.service', 'lanes-studio-host.service')
+RESULTS = ('ok', 'partial', 'refused', 'failed')
+OWNED = ('checked_at', 'latest', 'installed', 'previous', 'result', 'steps', 'log')   # the keys every record rewrites
+PARTIAL = 4                 # post-commit's exit status when a step failed (host-install.sh --update-only's as well)
+REFUSED = 3                 # `lock`'s exit status when another run holds the run lock (host-install.sh's refusal)
+# The steps whose exit status here is their own report of a condition the update neither caused nor can mend: a
+# warning, recorded with its rc and `"warning": true`, which leaves the result as it is (plan W9 U2: `lanes sync ||
+# warn`). `lanes sync` exits 1 whenever one board's registry has an error — a container docker no longer knows, a
+# terminals.json it cannot read — after publishing every other board and keeping that one's previous lanes (bin/lanes
+# cmd_sync: `return 1 if failed`); counted as a failure, it would make every update `partial` for as long as such a
+# board exists, and `lanes update` re-run the whole post-commit on every tick (fix cycle 1 of W9 U2). Any other status
+# of the step — 124 no answer, 127 could not start, 128+N a signal — is a failure like any other.
+WARN_RC = {'sync': 1}
+LOCK = 'update/.lock'       # the run lock, under the state directory
+MODES = ('update', 'install')
+RELEASE = re.compile(r'[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.+-]+)?\Z')
+UTC = re.compile(r'[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\Z')
+STEP = re.compile(r'([a-z][a-z0-9-]*)=([0-9]{1,3})\Z')
+
+
+def record_path(state):
+    return Path(state) / 'update' / 'last.json'
+
+
+def lock_path(state):
+    return Path(state) / LOCK
+
+
+def utc(at=None):
+    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(at))
+
+
+def step_entry(step):
+    """A record's step from (name, rc) or (name, rc, warning): {name, rc}, plus `"warning": true` for a warning."""
+    name, rc, *rest = step
+    entry = {'name': name, 'rc': int(rc)}
+    if rest and rest[0]:
+        entry['warning'] = True
+    return entry
+
+
+def failed_steps(steps):
+    """The names of the steps that failed: a non-zero rc that is no warning."""
+    return [entry['name'] for entry in map(step_entry, steps) if entry['rc'] and not entry.get('warning')]
+
+
+def warned_steps(steps):
+    return [entry['name'] for entry in map(step_entry, steps) if entry.get('warning')]
+
+
+def installed_tree(home=None):
+    """The existing tree the `current` link names now (resolved), else None."""
+    try:
+        tree = L.current_link(home).resolve(strict=True)
+    except (KeyError, OSError, RuntimeError):
+        return None
+    return tree if tree.is_dir() else None
+
+
+def write_record(state, result, steps, tree, before, log, started=None, environ=None, home=None, keys=None):
+    """Write `<state>/update/last.json` atomically -> the document. `steps` is [(name, rc)] or [(name, rc, warning)] in
+    run order; `tree` the tree this run installs, `before` the tree `current` named when it started (None: none). latest =
+    $LANES_UPDATE_LATEST (the release `lanes update` found, plan W9 U3) when it is a release, else this tree's VERSION;
+    checked_at = $LANES_UPDATE_CHECKED_AT when it is a UTC stamp, else `started`, else now; installed = the VERSION of
+    the tree `current` names now; previous = the VERSION of `before`. `keys`: keys outside OWNED set in the same write,
+    None removing one (a rollback's `bad` and `rerun`, written with the record of its flip: fix cycle 1 of W9 U3)."""
+    if result not in RESULTS:
+        raise ValueError(f'unknown result {result!r}')
+    if any(key in OWNED for key in keys or {}):
+        raise ValueError(f'keys the installer owns: {sorted(set(keys) & set(OWNED))}')
+    environ = os.environ if environ is None else environ
+    latest, checked = environ.get('LANES_UPDATE_LATEST', ''), environ.get('LANES_UPDATE_CHECKED_AT', '')
+    installed = installed_tree(home)
+    document = {
+        'checked_at': checked if UTC.match(checked) else started if started and UTC.match(started) else utc(),
+        'latest': latest if RELEASE.match(latest) else L.tree_version(tree),
+        'installed': L.tree_version(installed) if installed else None,
+        'previous': L.tree_version(before) if before else None,
+        'result': result,
+        'steps': [step_entry(step) for step in steps],
+        'log': str(log),
+    }
+    old = L.read_json(record_path(state))
+    if isinstance(old, dict):
+        document.update((key, value) for key, value in old.items() if key not in OWNED)
+    for key, value in (keys or {}).items():
+        if value is None:
+            document.pop(key, None)
+        else:
+            document[key] = value
+    L.atomic_write(record_path(state), json.dumps(document, indent=2) + '\n')
+    return document
+
+
+def stop(child):
+    """Stop a step's whole process group: SIGTERM, a bounded wait, SIGKILL, one more bounded wait."""
+    for signum in (signal.SIGTERM, signal.SIGKILL):
+        try:
+            os.killpg(child.pid, signum)
+        except (ProcessLookupError, PermissionError):
+            return
+        try:
+            child.wait(STOP_WAIT)
+            return
+        except subprocess.TimeoutExpired:
+            continue
+
+
+def run_step(argv, log, timeout):
+    """Run one step with its output appended to `log` (an open file) -> its exit status: 128+N when signal N ended it,
+    124 when it did not finish in `timeout` seconds (its process group is stopped), 127 when it could not start.
+    Its own session, so a timeout stops its children too; stdin is /dev/null."""
+    log.write(f'== {shlex.join(argv)}\n')
+    log.flush()
+    try:
+        child = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT,
+                                 start_new_session=True)
+    except OSError as error:
+        log.write(f'-> could not start: {error}\n')
+        log.flush()
+        return 127
+    try:
+        rc = child.wait(timeout)
+    except subprocess.TimeoutExpired:
+        stop(child)
+        log.write(f'-> no answer in {timeout:g} s: stopped\n')
+        log.flush()
+        return 124
+    except BaseException:
+        stop(child)
+        raise
+    rc = 128 - rc if rc < 0 else rc
+    log.write(f'-> exit {rc}\n')
+    log.flush()
+    return rc
+
+
+def recorded_containers(state):
+    """The containers `lanes sync` recorded with a home volume in `<state>/containers.json`, sorted. install-container
+    writes into that volume, so a container docker said does not exist (no home) is left out: sync reported it."""
+    document = L.read_json(Path(state) / 'containers.json', {})
+    if not isinstance(document, dict):
+        return []
+    return sorted(name for name, info in document.items()
+                  if L.IDENT.match(name) and isinstance(info, dict) and info.get('home'))
+
+
+def describe(rc, timeout):
+    return {124: f'no answer in {timeout:g} s', 127: 'could not start'}.get(rc, f'exit {rc}')
+
+
+def interrupted_rc(error):
+    return error.code if isinstance(error, SystemExit) and isinstance(error.code, int) else 130
+
+
+def count(names, noun):
+    return f"{len(names)} {noun}{'' if len(names) == 1 else 's'}"
+
+
+def post_commit(tree, state, log, steps=(), before=None, started=None, out=None, run=None, timeout=STEP_TIMEOUT,
+                systemctl='systemctl', environ=None, home=None):
+    """Run the post-commit steps from `tree` (whose bin/lanes runs them) -> the record written. `steps` are the phases
+    that ran before, [(name, rc)]. The record says `partial` before the first step, so a run killed half-way stays
+    `partial`; after the last step (or an interrupt: a SystemExit or KeyboardInterrupt is recorded as the step's rc,
+    then raised again) it says `ok` when every phase and step exited 0 or only warned (WARN_RC), else `partial`."""
+    out = sys.stdout if out is None else out
+    run = run_step if run is None else run
+    steps = list(steps)
+    lanes = str(Path(tree) / 'bin' / 'lanes')
+    write_record(state, 'partial', steps, tree, before, log, started, environ, home)
+    finished = False
+    Path(log).parent.mkdir(parents=True, exist_ok=True)
+    with open(log, 'a') as handle:
+        def step(name, argv):
+            try:
+                rc = run(argv, handle, timeout)
+            except (KeyboardInterrupt, SystemExit) as error:
+                steps.append((name, interrupted_rc(error)))
+                print(f'FAIL  {name} (interrupted)', file=out, flush=True)
+                raise
+            warning = rc != 0 and WARN_RC.get(name) == rc
+            steps.append((name, rc, warning))
+            print('ok    ' + name if rc == 0 else f"{'WARN' if warning else 'FAIL'}  {name} ({describe(rc, timeout)})",
+                  file=out, flush=True)
+        try:
+            step('daemon-reload', [systemctl, '--user', 'daemon-reload'])
+            step('sync', [lanes, 'sync'])
+            step('restart lanes-statusd', [systemctl, '--user', 'restart', 'lanes-statusd.service'])
+            for unit in TRY_RESTART:
+                step('try-restart ' + unit[:-len('.service')], [systemctl, '--user', 'try-restart', unit])
+            for container in recorded_containers(state):
+                step('install-container ' + container, [lanes, 'install-container', container])
+            step('reload-views', [lanes, 'reload-views'])
+            step('ensure', [lanes, 'ensure', '--if-layout-changed'])
+            finished = True
+        finally:
+            ok = finished and not failed_steps(steps)
+            document = write_record(state, 'ok' if ok else 'partial', steps, tree, before, log, started, environ, home)
+    failed, warned = failed_steps(steps), warned_steps(steps)
+    was = f" (was {document['previous']})" if document['previous'] else ''
+    warnings = f"; {count(warned, 'warning')}: {', '.join(warned)}" if warned else ''
+    if ok and not warned:
+        print(f"ok: lanes {document['installed']} installed{was}; every step ran — {record_path(state)}", file=out)
+    elif ok:
+        print(f"ok: lanes {document['installed']} installed{was}; every step ran{warnings} — log {log}", file=out)
+    else:
+        print(f"partial: lanes {document['installed']} installed{was}; {count(failed, 'step')} failed: "
+              f"{', '.join(failed)}{warnings} — log {log}", file=out)
+    return document
+
+
+def take_run_lock(descriptor, path, mode, pid=None):
+    """Take the run lock (an exclusive flock(2), without waiting) on `descriptor`, an open file that must be the
+    regular file `path` (never a link to another) -> None when taken, with this run written into it ({pid, mode,
+    started}; `pid` defaults to the parent's: host-install.sh's shell), else the one-line refusal naming the run that
+    holds it. The lock is the open file's: it lasts while any descriptor of it is open, the caller's included."""
+    try:
+        opened, named = os.fstat(descriptor), os.lstat(path)
+    except OSError as error:
+        return f'refused: cannot use the run lock {path}: {error.strerror}; nothing changed'
+    if not stat.S_ISREG(named.st_mode) or (opened.st_dev, opened.st_ino) != (named.st_dev, named.st_ino):
+        return f'refused: the run lock {path} is not a regular file of its own; nothing changed'
+    try:
+        fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        holder = L.read_json(path)
+        held = (f"another lanes {holder['mode']} is running (pid {holder['pid']}, since {holder['started']})"
+                if isinstance(holder, dict) and holder.get('mode') in MODES and isinstance(holder.get('pid'), int)
+                and UTC.match(str(holder.get('started', ''))) else 'another lanes install or update is running')
+        return (f'refused: {held}; it holds {path}. Nothing was changed or recorded — run this again once it has '
+                'ended')
+    os.ftruncate(descriptor, 0)
+    os.pwrite(descriptor, (json.dumps({'pid': os.getppid() if pid is None else pid, 'mode': mode,
+                                       'started': utc()}) + '\n').encode(), 0)
+    return None
+
+
+# ------------------------------------------------------------------ lanes update (plan W9 U3, LNS-91)
+PACKAGE = '@vibelord/lanes'
+REGISTRY = 'https://registry.npmjs.org/@vibelord/lanes'
+# The abbreviated document npm itself asks for (name, dist-tags, versions, modified): 4.8 KB where the full one is
+# 20 KB (MEASURED 2026-10-07, @vibelord/lanes at 1.1.1, `{"latest": "1.1.1"}`).
+ACCEPT = 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*'
+CURL_TIMEOUT = 20           # curl --max-time; run_bounded gives it 10 s more
+CHANNELS = {'latest': 'latest', 'stable': 'lanes-stable'}   # update.conf `channel=` -> the dist-tag it follows
+CONF = Path('.config/lanes/update.conf')                    # under the home
+# A check that answered less than this ago is not repeated (`--now` asks anyway). Below the timer's 30 min (plus up to
+# 5 min of RandomizedDelaySec, and a re-run post-commit before the check), so a tick after a tick always asks; only a
+# tick soon after a check by hand, or after a reboot, is skipped.
+INTERVAL = 20 * 60
+STALE = 2 * 60 * 60         # doctor: no check for this long means the timer does not run
+NPX_TIMEOUT = 50 * 60       # the whole install through npx; lanes-update.service stops everything after 1 h
+NPX_RECORD = 'update/npx'   # the npx a `--server` install ran with (npm/lanes/bin/lanes-install.mjs recordNpx)
+UPDATE_LOCK = 'locks/update.lock'
+OUTCOMES = ('current', 'older', 'bad', 'unanswered', 'refused', 'installing', 'installed', 'failed')
+OK, FAILED, USAGE = 0, 1, 2
+UPDATE_USAGE = 'usage: lanes update [--now | --timer | --status | --rollback]'
+INSTALLED_RC = {'ok': OK, 'partial': PARTIAL, 'refused': REFUSED, 'failed': FAILED}   # the installer's result -> exit
+UNIT_SETTING = re.compile(r'Environment="([A-Z][A-Z0-9_]*)=((?:[^"\\]|\\.)*)"\Z')
+# The interrupts a rollback's flip and its record wait for (deferred_interrupts): Ctrl-C, `kill`/systemd's stop, and
+# the hangup of a dropped SSH session.
+INTERRUPTS = (signal.SIGINT, signal.SIGTERM, signal.SIGHUP)
+# The timer, as `lanes doctor` checks it (fix cycle 1 of W9 U3): `systemctl --user enable` links it from
+# <unit folder>/timers.target.wants/ (its [Install] WantedBy=timers.target). Only the full server install enables it;
+# an update (`--update-only`) enables nothing — on a server set up before 1.2.0 and since updated that way it is off.
+TIMER = 'lanes-update.timer'
+TIMER_WANTS = 'timers.target.wants'
+ENABLE_TIMER = f'systemctl --user enable --now {TIMER}'
+
+
+def parse_utc(text):
+    """Epoch seconds of a stamp utc() wrote, else None."""
+    if not isinstance(text, str) or not UTC.match(text):
+        return None
+    try:
+        return calendar.timegm(time.strptime(text, '%Y-%m-%dT%H:%M:%SZ'))
+    except ValueError:
+        return None
+
+
+def ago(seconds):
+    seconds = max(0, int(seconds))
+    if seconds < 90:
+        return f'{seconds} s'
+    if seconds < 90 * 60:
+        return f'{seconds // 60} min'
+    if seconds < 36 * 3600:
+        return f'{seconds // 3600} h'
+    return f'{seconds // 86400} d'
+
+
+def printable(text, limit=300):
+    """One line for a record, a journal and a terminal: each control character a blank, blank runs one blank."""
+    return ' '.join(re.sub(r'[\x00-\x1f\x7f-\x9f]', ' ', str(text)).split())[:limit]
+
+
+def read_record(state):
+    document = L.read_json(record_path(state))
+    return document if isinstance(document, dict) else {}
+
+
+def write_keys(state, **keys):
+    """Set record keys the installer does not own (`check`, `rerun`), keeping every other key -> the record. Only under
+    the run lock: the installer writes the same file under it. (A rollback's `bad` goes into the record of its flip:
+    write_record's `keys`.)"""
+    document = read_record(state)
+    document.update(keys)
+    L.atomic_write(record_path(state), json.dumps(document, indent=2) + '\n')
+    return document
+
+
+def linked_tree(link):
+    """The existing tree `link` names (resolved), else None (no link, a dangling one, a loop)."""
+    try:
+        tree = Path(link).resolve(strict=True)
+    except (OSError, RuntimeError):
+        return None
+    return tree if tree.is_dir() else None
+
+
+def previous_link(home):
+    return L.current_link(home).with_name('current.previous')
+
+
+def read_conf(home):
+    """(channel, tag) from <home>/.config/lanes/update.conf: `channel=stable` follows the dist-tag `lanes-stable`,
+    `channel=latest` (or no file, no such line) `latest`; `#` comments and other keys are ignored. A channel that is
+    neither, or a file that cannot be read, is a ValueError: an update never guesses which releases were meant."""
+    path = Path(home) / CONF
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        text = ''
+    except (OSError, ValueError) as error:
+        raise ValueError(f'{path} cannot be read ({getattr(error, "strerror", None) or error})') from None
+    channel = 'latest'
+    for line in text.splitlines():
+        name, equals, value = line.partition('=')
+        if equals and not line.lstrip().startswith('#') and name.strip() == 'channel':
+            channel = value.strip()
+    if channel not in CHANNELS:
+        raise ValueError(f'channel={printable(channel, 40)} in {path} is neither stable nor latest')
+    return channel, CHANNELS[channel]
+
+
+def ask_registry(tag, run=None):
+    """The release the npm registry's dist-tag `tag` names -> (release, None), or (None, why): curl got no answer or an
+    HTTP error (-f), or the answer names no release under that tag."""
+    run = L.run_bounded if run is None else run
+    rc, out, err = run(['curl', '-fsS', '--max-time', str(CURL_TIMEOUT), '-H', f'Accept: {ACCEPT}', REGISTRY],
+                       CURL_TIMEOUT + 10)
+    if rc != 0:
+        said = printable((err or '').strip().splitlines()[-1] if (err or '').strip() else '', 200)
+        return None, (f'no answer in {CURL_TIMEOUT + 10} s' if rc is None else
+                      f'curl exit {rc}' + (f': {said}' if said else ''))
+    try:
+        document = json.loads(out)
+    except ValueError:
+        return None, f'{REGISTRY} answered no JSON'
+    tags = document.get('dist-tags') if isinstance(document, dict) else None
+    release = tags.get(tag) if isinstance(tags, dict) else None
+    if release is None:
+        return None, f'the registry names no {tag} release of {PACKAGE}'
+    if not isinstance(release, str) or len(release) > 32 or not RELEASE.match(release):
+        return None, f'the registry\'s {tag} is no release'
+    return release, None
+
+
+def recorded_npx(state):
+    """The npx the npm wrapper recorded at the last `--server` install (`<state>/update/npx`, one absolute path) ->
+    (path, None), or (None, why) when there is none or it is gone (a Node.js moved by nvm: the plan's no self-heal)."""
+    path = Path(state) / NPX_RECORD
+    try:
+        lines = path.read_text().splitlines()
+    except FileNotFoundError:
+        return None, (f'no npx is recorded in {path} — the npm wrapper records the one a server install runs with: '
+                      'install once with npx @vibelord/lanes --server --update-only')
+    except (OSError, ValueError) as error:
+        return None, f'{path} cannot be read ({getattr(error, "strerror", None) or error})'
+    npx = lines[0] if len(lines) == 1 else ''
+    if not npx.startswith('/') or printable(npx, 4096) != npx:
+        return None, f'{path} names no absolute path'
+    if not (os.path.isfile(npx) and os.access(npx, os.X_OK)):
+        return None, (f'the recorded npx {npx} is gone or not executable (Node.js moved or upgraded?) — install once '
+                      'with npx @vibelord/lanes --server --update-only from a shell whose npx works')
+    return npx, None
+
+
+def services_module(repo=None):
+    """install/services.py of `repo` (default this tree) as a module: the units' settings and, for a rollback, the
+    install of another tree (`register(..., install=True)`)."""
+    spec = importlib.util.spec_from_file_location('lanes_update_services',
+                                                  Path(repo if repo is not None else L.REPO) / 'install/services.py')
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def carried_names(services):
+    """The settings an install renders into the units from ITS environment (services.py), which a timer's environment
+    or another shell does not carry."""
+    return ('LANES_WORKSPACES',) + tuple(services.ECONOMY_SETTINGS) + tuple(services.NOTIFY_SETTINGS)
+
+
+def carried_settings(units_dir, names, environ):
+    """{name: value} for each of `names` an installed lanes unit in `units_dir` sets (`Environment="NAME=VALUE"`,
+    unescaped as services.unit_value escaped it) and `environ` does not: an update installs with the settings the
+    running units have, never without them (the economy poller's control URL, the notifier's config path)."""
+    found = {}
+    for unit in sorted(Path(units_dir).glob('lanes*.service')):
+        try:
+            lines = unit.read_text().splitlines()
+        except (OSError, ValueError):
+            continue
+        for line in lines:
+            match = UNIT_SETTING.match(line)
+            if match and match.group(1) in names and match.group(1) not in found:
+                found[match.group(1)] = re.sub(r'\\(.)', r'\1', match.group(2).replace('%%', '%'))
+    return {name: value for name, value in found.items() if not environ.get(name)}
+
+
+def npx_environment(npx, environ, carried, latest, checked_at):
+    """The environment of the npx an update runs: this one, with the settings carried from the units, npx's folder first
+    on PATH (npx is `#!/usr/bin/env node`, and node lives beside it — a unit's PATH has neither), the check handed to
+    the installer's record (LANES_UPDATE_LATEST, LANES_UPDATE_CHECKED_AT), and without the options of an npx that
+    started this process (`npx -c` / `-p` export npm_config_call / npm_config_package, which a nested npx obeys)."""
+    env = {name: value for name, value in environ.items()
+           if not re.fullmatch(r'npm_config_(call|package)', name, re.IGNORECASE)}
+    env.update(carried)
+    env['PATH'] = os.pathsep.join([str(Path(npx).parent), environ.get('PATH') or '/usr/local/bin:/usr/bin:/bin'])
+    env['LANES_UPDATE_LATEST'] = latest
+    env['LANES_UPDATE_CHECKED_AT'] = checked_at
+    return env
+
+
+def run_npx(argv, env, output=None, timeout=NPX_TIMEOUT):
+    """Run the install through npx in its own session -> its exit status (128+N for signal N, 124 when it did not end
+    in `timeout` s, 127 when it could not start). Its output goes to this process's (`output`: a file instead). An
+    interrupt here (Ctrl-C, SIGTERM) stops its whole process group first, so the installer records it."""
+    try:
+        child = subprocess.Popen(argv, stdin=subprocess.DEVNULL, stdout=output, stderr=output, env=env,
+                                 start_new_session=True)
+    except OSError:
+        return 127
+    try:
+        rc = child.wait(timeout)
+    except subprocess.TimeoutExpired:
+        stop(child)
+        return 124
+    except BaseException:
+        stop(child)
+        raise
+    return 128 - rc if rc < 0 else rc
+
+
+@contextlib.contextmanager
+def update_lock(state):
+    """One `lanes update` at a time: an exclusive flock(2), without waiting, on `<state>/locks/update.lock`, held to the
+    end of the run -> yields None when taken (this pid written into it), else the one line naming the run that holds
+    it. Distinct from the run lock: that one is released while npx runs the installer, which takes it."""
+    path = Path(state) / UPDATE_LOCK
+    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:
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            held = None
+        except BlockingIOError:
+            holder = L.read_json(path)
+            held = ('another lanes update is running'
+                    + (f" (pid {holder['pid']}, since {holder['started']})"
+                       if isinstance(holder, dict) and isinstance(holder.get('pid'), int)
+                       and UTC.match(str(holder.get('started', ''))) else '')
+                    + f'; it holds {path}')
+        if held is None:
+            os.ftruncate(descriptor, 0)
+            os.pwrite(descriptor, (json.dumps({'pid': os.getpid(), 'started': utc()}) + '\n').encode(), 0)
+        yield held
+    finally:
+        os.close(descriptor)
+
+
+@contextlib.contextmanager
+def run_lock(state):
+    """The run lock (`<state>/update/.lock`), as host-install.sh takes it, for the parts of `lanes update` that write the
+    record or run a post-commit themselves -> yields None when taken, else take_run_lock's refusal."""
+    path = lock_path(state)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_CLOEXEC, 0o600)   # as `exec 9>>`
+    try:
+        yield take_run_lock(descriptor, path, 'update', pid=os.getpid())
+    finally:
+        os.close(descriptor)
+
+
+@contextlib.contextmanager
+def recorded_interrupts():
+    """SIGTERM and SIGHUP raise SystemExit while a post-commit or npx runs here, so post_commit records the step they
+    stopped and run_npx stops the installer's group (as main() does for `update.py post-commit`)."""
+    saved = {signum: signal.signal(signum, raise_exit) for signum in (signal.SIGTERM, signal.SIGHUP)}
+    try:
+        yield
+    finally:
+        for signum, handler in saved.items():
+            signal.signal(signum, handler)
+
+
+@contextlib.contextmanager
+def deferred_interrupts():
+    """SIGINT, SIGTERM and SIGHUP wait while the body runs: one that arrives is noted, and once the body has ended the
+    handlers it found are put back and the first one noted is raised again (signal.raise_signal: KeyboardInterrupt for
+    SIGINT, recorded_interrupts' SystemExit for the others, the default action where nothing handles it). A rollback's
+    flip and the record that says so are one step this way: no interrupt lands between `current` moving and the
+    release left being marked `bad` (fix cycle 1 of W9 U3). The wait is that of install/services.py's register and the
+    record's write (milliseconds; at most its 60 s install-lock wait and systemctl's 10 s). Python handlers, never the
+    signal mask: a child the body starts gets the default handlers when it execs, not a blocked signal."""
+    noted = []
+    saved = {signum: signal.signal(signum, lambda signum, _frame: noted.append(signum)) for signum in INTERRUPTS}
+    try:
+        yield
+    finally:
+        for signum, handler in saved.items():
+            signal.signal(signum, handler)
+    if noted:
+        signal.raise_signal(noted[0])
+
+
+class Update:
+    """One `lanes update` run (update_main). `key` is bin/lanes version_key: the one comparison of releases."""
+
+    def __init__(self, key, timer=False, out=None, environ=None, home=None, clock=None, output=None):
+        self.key, self.timer = key, timer
+        self.out = sys.stdout if out is None else out
+        self.environ = os.environ if environ is None else environ
+        self.home = Path.home() if home is None else Path(home)
+        self.clock = time.time if clock is None else clock
+        self.output = output                # where npx writes (None: this process's stdout and stderr)
+        self.state = L.STATE
+        self.log = record_path(self.state).with_name('last.log')
+
+    def say(self, text):
+        print(f'lanes update: {text}', file=self.out, flush=True)
+
+    def refused(self, text):
+        """A run that does nothing: exit 3 by hand; 0 under the timer, whose unit then fails only when an update did."""
+        self.say(text)
+        return OK if self.timer else REFUSED
+
+    def run(self, flag):
+        with update_lock(self.state) as held:
+            if held:
+                return self.refused(f'{held}; this run does nothing')
+            tree = installed_tree(self.home)
+            if tree is None:
+                return self.refused(f'no release is installed here ({L.current_link(self.home)} names no tree): '
+                                    'install the server first — npx @vibelord/lanes --server')
+            if not L.staged_tree(tree):
+                return self.refused(f'this server runs the checkout {tree}, not an npm release: update it with git '
+                                    'pull, then ./install.sh --server --update-only')
+            if L.tree_version(tree) is None or self.key(L.tree_version(tree)) is None:
+                return self.refused(f'the installed tree {tree} names no release in its VERSION: re-run the server '
+                                    'installer')
+            with recorded_interrupts():
+                return self.rollback(tree) if flag == '--rollback' else self.update(tree, force=flag == '--now')
+
+    def fresh_log(self, header):
+        self.log.parent.mkdir(parents=True, exist_ok=True)
+        self.log.write_text(f'== {header}\n')
+
+    @staticmethod
+    def kept(record):
+        """The record's own check (top-level `latest`, `checked_at`), handed to write_record unchanged by a run that
+        did not ask the registry: a re-run, a rollback."""
+        return {'LANES_UPDATE_LATEST': str(record.get('latest') or ''),
+                'LANES_UPDATE_CHECKED_AT': str(record.get('checked_at') or '')}
+
+    def rerun(self, tree, record):
+        """A last run that ended `partial`: the post-commit of the tree `current` names, again -> OK or PARTIAL."""
+        installed = L.tree_version(tree)
+        self.say(f'the last update of {installed} ended partial: its post-commit again, from {tree} (log {self.log})')
+        self.fresh_log(f'lanes update: the post-commit of {tree} again (the last run ended partial)')
+        document = post_commit(tree, self.state, self.log, (), linked_tree(previous_link(self.home)),
+                               utc(self.clock()), out=self.out, environ=self.kept(record), home=self.home)
+        write_keys(self.state, rerun=installed)
+        return OK if document['result'] == 'ok' else PARTIAL
+
+    def update(self, tree, force):
+        installed, code = L.tree_version(tree), OK
+        with run_lock(self.state) as refusal:
+            if refusal:
+                return self.refused(refusal)
+            record = read_record(self.state)
+            if record.get('result') == 'partial':
+                if self.timer and record.get('rerun') == installed:
+                    # Once per release from the timer: a post-commit that fails the same way every 30 min would
+                    # restart every service each time. The run still exits 4 (the unit fails) until a person acts.
+                    self.say(f'the last update of {installed} ended partial again after its post-commit was run '
+                             f'once more: lanes update (by hand) runs it again — log {self.log}')
+                    code = PARTIAL
+                else:
+                    code = self.rerun(tree, record)
+                    record = read_record(self.state)
+            last = record.get('check') if isinstance(record.get('check'), dict) else {}
+            asked, now = parse_utc(last.get('at')), self.clock()
+            if not force and last.get('latest') and asked is not None and 0 <= now - asked < INTERVAL:
+                self.say(f"checked {ago(now - asked)} ago ({last.get('tag')} names {last.get('latest')}): the next "
+                         f'check is due {ago(asked + INTERVAL - now)} from now — lanes update --now asks now')
+                return code
+            at = utc(now)
+            check = {'at': at, 'by': 'timer' if self.timer else 'hand', 'channel': None, 'tag': None,
+                     'latest': None, 'installed': installed}
+            try:
+                check['channel'], check['tag'] = read_conf(self.home)
+            except ValueError as error:
+                return self.finish(check, 'refused', f'{error}: nothing was asked or installed',
+                                   code or (OK if self.timer else REFUSED))
+            tag = check['tag']
+            latest, why = ask_registry(tag)
+            if latest is None or self.key(latest) is None:
+                return self.finish(check, 'unanswered', f'{why or f"{tag} names {latest}, no release"}; nothing '
+                                   'changed', code or FAILED)
+            check['latest'] = latest
+            new, old = self.key(latest), self.key(installed)
+            if new == old:
+                return self.finish(check, 'current', f'{tag} names {latest}: installed', code)
+            if new < old:
+                return self.finish(check, 'older', f'{tag} names {latest}, older than the installed {installed}: '
+                                   'not installed (an update never goes back; lanes update --rollback does)', code)
+            if latest == record.get('bad'):
+                return self.finish(check, 'bad', f'{tag} names {latest}, the release a rollback left (bad): not '
+                                   'installed until a newer one is published', code)
+            npx, why = recorded_npx(self.state)
+            if npx is None:
+                return self.finish(check, 'failed', f'{tag} names {latest}, not installed: {why}', code or FAILED)
+            argv = [npx, '--yes', f'{PACKAGE}@{latest}', '--server', '--update-only']
+            self.finish(check, 'installing', f'{installed} -> {latest} ({tag}): {shlex.join(argv)}', code)
+        return self.install(check, argv)
+
+    def finish(self, check, outcome, said, code):
+        """Record the check (`check` in the record, under the run lock) and say it -> code."""
+        check.update(outcome=outcome, said=printable(said))
+        write_keys(self.state, check=check)
+        self.say(check['said'])
+        return code
+
+    def install(self, check, argv):
+        """npx runs the installer (`--server --update-only`) with the run lock released -> the installer's result as an
+        exit status (FAILED when it recorded no run: npx or the wrapper failed before it)."""
+        services = services_module()
+        carried = carried_settings(services.manager_unit_dir(self.home), carried_names(services), self.environ)
+        if carried:
+            self.say(f"with {', '.join(sorted(carried))} from the installed units")
+        rc = run_npx(argv, npx_environment(argv[0], self.environ, carried, check['latest'], check['at']), self.output)
+        with run_lock(self.state) as refusal:
+            record = read_record(self.state)
+            recorded = record.get('checked_at') == check['at'] and record.get('latest') == check['latest']
+            result = record.get('result') if recorded and record.get('result') in INSTALLED_RC else None
+            if result:
+                outcome, said = 'installed', f"npx exit {rc}: the update to {check['latest']} ended {result}"
+            else:
+                outcome, said = 'failed', (f"npx exit {rc} before the installer recorded a run: {check['latest']} is "
+                                           'not installed (npx\'s own output says why: the terminal, or journalctl '
+                                           '--user -u lanes-update.service)')
+            check.update(outcome=outcome, said=said, exit=rc)
+            if refusal:
+                self.say(f'{said} (not recorded: {refusal})')
+            else:
+                write_keys(self.state, check=check)
+                self.say(said)
+        code = INSTALLED_RC[result] if result else FAILED
+        return OK if self.timer and code == REFUSED else code
+
+    def rollback(self, tree):
+        """`current` back to the tree `current.previous` names, the release left marked `bad`, then its post-commit.
+        The flip and its record are one step no interrupt splits (deferred_interrupts): once `current` names the tree
+        rolled back to, one write records `partial` (the post-commit has not run yet, so the next `lanes update` runs
+        it) with the release left as `bad`, before the post-commit starts. A Ctrl-C, or the SIGHUP of a dropped SSH
+        session, during the post-commit or the flip therefore never leaves that release unmarked for the next timer
+        tick to install again (fix cycle 1 of W9 U3: the mark used to be written after the post-commit)."""
+        with run_lock(self.state) as refusal:
+            if refusal:
+                return self.refused(refusal)
+            link, bad = previous_link(self.home), L.tree_version(tree)
+            previous = linked_tree(link)
+            if previous is None or previous == tree:
+                return self.refused(f'nothing to roll back to: {link} names ' + (
+                    'no tree' if previous is None else 'the installed tree') + ' (the install that last moved '
+                    '`current` records the release before it there)')
+            target, record = L.tree_version(previous), read_record(self.state)
+            if record.get('bad') is not None and target == record.get('bad'):
+                return self.refused(f'{link} names {target}, the release the last rollback left (bad): nothing to roll '
+                                    f'back to — to install it again: npx @vibelord/lanes@{target} --server --update-only')
+            started, kept = utc(self.clock()), self.kept(record)
+            self.say(f'{bad} -> {target}: installing {previous} again (log {self.log})')
+            self.fresh_log(f'lanes update --rollback: {tree} -> {previous}')
+            with deferred_interrupts():
+                rc = self.flip(previous)
+                if installed_tree(self.home) != previous:
+                    result = 'refused' if rc == REFUSED else 'failed'
+                    write_record(self.state, result, [('rollback', rc)], previous, tree, self.log, started, kept,
+                                 self.home)
+                    print(f'FAIL  rollback (exit {rc})', file=self.out)
+                    self.say(f'{result}: nothing changed; {bad} still runs — log {self.log}')
+                    return REFUSED if result == 'refused' else FAILED
+                # The commit point of the rollback, recorded in one write: `partial` until the post-commit has run,
+                # the release left `bad`, and no `rerun` — that mark belongs to an earlier post-commit of this release,
+                # and kept it would stop the timer re-running the one this rollback starts, should it be cut short.
+                write_record(self.state, 'partial', [('rollback', rc)], previous, tree, self.log, started, kept,
+                             self.home, keys={'bad': bad, 'rerun': None})
+                print('ok    rollback' if rc == OK else f'FAIL  rollback (exit {rc})', file=self.out, flush=True)
+                self.say(f'{bad} is marked bad: no update installs it again; a newer release is installed as usual')
+            document = post_commit(previous, self.state, self.log, [('rollback', rc)], tree, started, out=self.out,
+                                   environ=kept, home=self.home)
+            return OK if document['result'] == 'ok' else PARTIAL
+
+    def flip(self, previous):
+        """Install `previous` again as the server installer's commit does — every unit rendered from ITS templates,
+        `current.previous` then the tree being left, then `current` — with this tree's install/services.py (no network,
+        no npx: a rollback works while npm does not) and the settings the installed units carry -> OK, REFUSED (a
+        services.Refusal: nothing written) or FAILED (anything else; the traceback is in the log)."""
+        services = services_module()
+        with open(self.log, 'a') as log, contextlib.redirect_stderr(log):
+            log.write(f'== install/services.py of {L.REPO}: install {previous}\n')
+            log.flush()
+            try:
+                units = services.manager_unit_dir(self.home)
+                env = dict(self.environ, **carried_settings(units, carried_names(services), self.environ))
+                services.register(previous, self.home, L.SHARE, self.state, env.get('LANES_WORKSPACES'),
+                                  services.economy_settings(env), services.notify_settings(env), units_dir=units,
+                                  install=True)
+            except services.Refusal as error:
+                log.write(f'services.py: refused, nothing was changed: {error}\n')
+                return REFUSED
+            except Exception:                   # noqa: BLE001 — every other failure is the log's to say
+                log.write(traceback.format_exc())
+                return FAILED
+        return OK
+
+
+def show_status(state, out):
+    """`lanes update --status`: the record as it is on disk -> 0, or 1 when there is none yet."""
+    path = record_path(state)
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        print(f'lanes update: no update is recorded yet ({path})', file=out)
+        return FAILED
+    except (OSError, ValueError) as error:
+        print(f'lanes update: {path} cannot be read ({getattr(error, "strerror", None) or error})', file=out)
+        return FAILED
+    out.write(text if text.endswith('\n') else text + '\n')
+    return OK
+
+
+def update_main(args, key, out=None, environ=None, home=None, clock=None, output=None):
+    """`lanes update [--now | --timer | --status | --rollback]` (bin/lanes cmd_update) -> the exit status: 0 nothing to
+    do, or done and ok (under --timer also a run that did nothing: another update running, a checkout, no installed
+    release, a bad update.conf); 4 partial; 3 refused (by hand); 1 failed (the registry gave no release, npx could not
+    install, the install failed); 2 usage."""
+    out = sys.stdout if out is None else out
+    if len(args) > 1 or (args and args[0] not in ('--now', '--timer', '--status', '--rollback')):
+        print(UPDATE_USAGE, file=out)
+        return USAGE
+    flag = args[0] if args else None
+    if flag == '--status':
+        return show_status(L.STATE, out)
+    return Update(key, timer=flag == '--timer', out=out, environ=environ, home=home, clock=clock,
+                  output=output).run(flag)
+
+
+def timer_enabled(units):
+    """Whether lanes-update.timer is enabled in one of the unit folders `units`: `<folder>/timers.target.wants/
+    lanes-update.timer`, the link `systemctl --user enable` makes, names an existing unit. A file read, as every other
+    doctor line is (doctor never asks systemctl)."""
+    return any((Path(folder) / TIMER_WANTS / TIMER).exists() for folder in units)
+
+
+def doctor_line(state=None, home=None, now=None, units=None):
+    """`lanes doctor`'s update line -> (mark, text), mark ✓ | ✗ | ⚠ | '' (information), or None without an installed
+    release (doctor's `current` line says that already). From the record — the last check and its outcome, the last
+    install's result, a rollback's `bad` — and from whether lanes-update.timer is enabled in one of the unit folders
+    `units` (bin/lanes unit_dirs; default ~/.config/systemd/user): ⚠ at once when it is not (fix cycle 1 of W9 U3), not
+    only once no check has run for STALE."""
+    state = L.STATE if state is None else state
+    home = Path.home() if home is None else Path(home)
+    now = time.time() if now is None else now
+    units = [home / '.config/systemd/user'] if units is None else units
+    tree = installed_tree(home)
+    if tree is None:
+        return None
+    if not L.staged_tree(tree):
+        return ('', 'updates: this server runs a checkout, which lanes update and its timer leave alone: git pull, then '
+                    './install.sh --server --update-only')
+    record = read_record(state)
+    enable = ENABLE_TIMER
+    off = (f'{TIMER} is not enabled, so no newer release installs itself: {enable} (the full server install enables '
+           'it; an update with --update-only never does)')
+    timer = timer_enabled(units)
+    if not record:
+        if not timer:
+            return ('⚠', f'updates: none recorded yet — {off}; lanes update --now checks now')
+        return ('⚠', f'updates: none recorded yet — lanes-update.timer checks 15 min after a boot, then every 30 min '
+                     f'({enable}); lanes update --now checks now')
+    check = record.get('check') if isinstance(record.get('check'), dict) else {}
+    asked = parse_utc(check.get('at')) or parse_utc(record.get('checked_at'))
+    mark, parts = '✓', []
+    if check:
+        parts.append(f"checked {ago(now - asked) + ' ago' if asked else 'at an unknown time'}: "
+                     f"{printable(check.get('said') or check.get('outcome') or '?', 200)}")
+        if check.get('outcome') == 'failed':
+            mark = '✗'
+        elif check.get('outcome') in ('unanswered', 'refused', 'installing'):
+            mark = '⚠'
+    result = record.get('result')
+    if result in INSTALLED_RC:
+        steps = [entry.get('name') for entry in record.get('steps') or ()
+                 if isinstance(entry, dict) and entry.get('rc') and not entry.get('warning')]
+        parts.append(f"last update {result}: {printable(record.get('previous') or '—', 40)} → "
+                     f"{printable(record.get('installed') or '—', 40)}"
+                     + (f" ({', '.join(printable(name, 60) for name in steps[:4])} failed)" if steps else '')
+                     + ('' if result == 'ok' else f" — log {printable(record.get('log') or '?', 200)}")
+                     + (' (lanes update runs its post-commit again)' if result == 'partial' else ''))
+        mark = '✗' if result in ('partial', 'failed') else '⚠' if result == 'refused' and mark == '✓' else mark
+    if record.get('bad'):
+        parts.append(f"{printable(record['bad'], 40)} marked bad by a rollback")
+    if not timer:
+        parts.append(off)
+        mark = '⚠' if mark == '✓' else mark
+    elif asked is None or now - asked > STALE:
+        parts.append((f'no check for {ago(now - asked)}' if asked else 'no check recorded')
+                     + f': is the timer on? {enable}')
+        mark = '⚠' if mark == '✓' else mark
+    return (mark, 'updates: ' + ' · '.join(parts))
+
+
+def step_argument(text):
+    match = STEP.match(text)
+    if not match or int(match.group(2)) > 255:
+        raise argparse.ArgumentTypeError(f'not NAME=RC: {text!r}')
+    return match.group(1), int(match.group(2))
+
+
+def parser():
+    top = argparse.ArgumentParser(prog='update.py', description='a server update after its commit point (W9 U2)')
+    commands = top.add_subparsers(dest='command', required=True)
+    for name in ('post-commit', 'record'):
+        command = commands.add_parser(name)
+        command.add_argument('--state', required=True)
+        command.add_argument('--tree', required=True)
+        command.add_argument('--log', required=True)
+        command.add_argument('--before', default='')
+        command.add_argument('--started', default='')
+        command.add_argument('--step', action='append', default=[], type=step_argument)
+        if name == 'record':
+            command.add_argument('--result', required=True, choices=('refused', 'failed', 'partial'))
+    lock = commands.add_parser('lock')
+    lock.add_argument('--state', required=True)
+    lock.add_argument('--fd', required=True, type=descriptor_argument)
+    lock.add_argument('--mode', required=True, choices=MODES)
+    return top
+
+
+def descriptor_argument(text):
+    if not text.isdigit() or not 3 <= int(text) <= 9:
+        raise argparse.ArgumentTypeError(f'not a descriptor 3-9: {text!r}')
+    return int(text)
+
+
+def raise_exit(signum, _frame):
+    raise SystemExit(128 + signum)
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    if args.command == 'lock':
+        refusal = take_run_lock(args.fd, lock_path(args.state), args.mode)
+        if refusal:
+            print(refusal, flush=True)
+            return REFUSED
+        return 0
+    before = Path(args.before) if args.before else None
+    if args.command == 'record':
+        write_record(args.state, args.result, args.step, Path(args.tree), before, args.log, args.started or None)
+        return 0
+    for signum in (signal.SIGTERM, signal.SIGHUP):   # a stopped update still writes its record (post_commit finally)
+        signal.signal(signum, raise_exit)
+    document = post_commit(Path(args.tree), args.state, args.log, args.step, before, args.started or None)
+    return 0 if document['result'] == 'ok' else PARTIAL
+
+
+if __name__ == '__main__':
+    sys.exit(main())