@vibelord/lanes 1.1.1 → 1.3.0

package/README.md

@@ -30,6 +30,12 @@ which redeems it at the server's enrolment service: `invite: redeemed — this m
 <login> (device <device>)`. An unknown prefix is refused with the bundled list; `--site` given explicitly wins. The
 code is never printed, stored, or put on a command line. `LANES_INVITE` works like `--invite`.
 
+The code is redeemed by the server's own release: when the server (already reachable over the tailnet) runs a newer
+release than this package, the installer says `server runs 1.2.0: fetching that installer first` before it installs
+anything, and the wrapper runs `npx --yes @vibelord/lanes@1.2.0` with the same options (the code through the
+environment). Without npx and npm on the PATH, or when npm does not have that release yet, it says so in one line and
+this package installs as before. `LANES_NO_SELF_UPDATE=1` always installs this package.
+
 **Without a code:**
 
 ```sh
@@ -50,7 +56,8 @@ the server (a refused code, an unanswered request, or a server without the enrol
 the printed command again with `--device NAME` or a key of its own — the invite is still valid) · `4` installed, but
 this machine is not in the
 tailnet (the installer names the Tailscale install command, or opens `tailscale login` and waits up to 120 s) or the
-server is unreachable · `1` error.
+server is unreachable · `1` error. When the installer hands over to the server's release, the exit status is that
+release's installer's.
 
 ## Server
 
@@ -59,8 +66,17 @@ On the Linux x86_64 workspace host, as the workspace account:
 ```sh
 npx @vibelord/lanes --server --check
 npx @vibelord/lanes --server
+npx @vibelord/lanes@latest --server --update-only   # an update of an installed server: install, restart what runs, record the run
 ```
 
+The server install enables `lanes-update.timer`: every 30 minutes `lanes update --timer` asks npm for the newest release
+and installs it the same way (`--update-only`), with the npx this install ran with (recorded in
+`~/.local/state/lanes/update/npx`) — publishing a release deploys it. An update with `--update-only` enables nothing,
+the timer included: a server set up before 1.2.0 needs the full `npx @vibelord/lanes@latest --server` once (or
+`systemctl --user enable --now lanes-update.timer`). `lanes update --now` checks by hand, `lanes update --status` prints
+the record, `lanes update --rollback` goes back to the release before; `channel=stable` in `~/.config/lanes/update.conf`
+follows the `lanes-stable` dist-tag instead of `latest`.
+
 The server install also enables the enrolment service, `lanes-enrold`, that redeems invites and takes access
 requests. Once its operator check passes, pin request mode with `lanes enrol mode request` (`invite` for invites
 only), so no restart changes it. Members then invite from the server, in their own terminal, with `lanes invite <name>
@@ -71,10 +87,25 @@ says the server is older.
 
 ## What the wrapper does
 
-`lanes-install` copies the bundled tree to `~/.local/share/lanes/pkg/<version>/` (`$LANES_PKG_ROOT` overrides the
-parent) and runs `install.sh` from there. The server's systemd user units and `~/.local/share/lanes/current` name
-that stable path, never the npx cache. An identical tree is reused; the newest three versions and any version the
-server still runs from are kept.
+`lanes-install` copies the bundled tree to `~/.local/share/lanes/pkg/<version>/` (`$XDG_DATA_HOME/lanes/pkg/` when
+that is set; `$LANES_PKG_ROOT` overrides the parent, under any name — the stamp the wrapper writes into the tree marks
+it as staged) and runs `install.sh` from there. `~/.local/share/lanes/current`
+names that stable path, never the npx cache, and the server's systemd user units, `~/.local/bin/lanes` and view
+layouts name the link (moved last, in one step, by the server install; `current.previous` keeps the tree it named
+before); the link is always under your home directory, whatever `XDG_DATA_HOME` says. An identical tree is reused.
+Where that link does not exist (a client) the newest three versions are kept and older ones deleted; where it does
+(a server, even with a broken link) the wrapper deletes nothing — the server's `lanes gc` (daily) prunes its trees,
+keeping the newest three of each folder and every older one still in use: the tree `current` or `current.previous`
+names, one a view layout or a running daemon's run record names, one a process of the account uses.
+
+It runs `install.sh` with `LANES_WRAPPER_REPLY` naming a fresh temporary file. With an invite, `install.sh` asks the
+site's enrolment service for the server's release first; a newer one than this package ends that run before anything
+is installed (`update-to=<release>` in the file, exit 5). The wrapper then asks `npm view
+@vibelord/lanes@<release> version` with the npm beside npx and, when npm has it, runs `npx --yes
+@vibelord/lanes@<release>` with the same arguments, the code moved to `LANES_INVITE` and `LANES_NO_SELF_UPDATE=1`
+(that installer never hands over again), and ends with its status. Otherwise — no npx with its npm, a release npm
+does not have yet, npm not answering — `install.sh` runs once more from this package without the question.
+`LANES_NO_SELF_UPDATE` or `LANES_NO_AUTOUPDATE` (any value) turns the hand-over off.
 
 | Option | Effect |
 | --- | --- |

package/bin/lanes-install.mjs

@@ -5,14 +5,34 @@
 // The package carries the committed `lanes/` tree (payload/lanes) plus a manifest written at pack time. This
 // wrapper copies that tree to a STABLE, versioned directory and runs its own `install.sh` from there:
 //
-//   ~/.local/share/lanes/pkg/<version>/     (or $LANES_PKG_ROOT/<version>)
+//   ~/.local/share/lanes/pkg/<version>/     ($XDG_DATA_HOME/lanes/pkg/<version>/ when that is set, or
+//                                           $LANES_PKG_ROOT/<version>)
 //
-// A stable path matters for the server: `install/services.py` writes the resolved checkout path into the
-// systemd user units and links ~/.local/share/lanes/current to it, so the tree must outlive the npx cache.
-// Clients copy their commands out of the tree, so for them the location is incidental.
+// A stable path matters for the server: `install/services.py` links ~/.local/share/lanes/current to the resolved
+// tree and writes that link into the systemd user units, ~/.local/bin/lanes and (through lanes_lib.CURRENT) the view
+// layouts (W9 U1), so the tree must outlive the npx cache. That link is always under the home directory
+// (lanes_lib.CURRENT and prune() read it there, plan.mjs `currentLink`). The STAMP written into each staged tree is
+// what tells lanes_lib.staged_tree a staged tree from a checkout under a $LANES_PKG_ROOT of any name (DEF-1757).
+// Clients copy their commands out of the tree, so for them the location is incidental — and only there does this
+// wrapper prune old trees: where the link exists, `lanes gc` does (W9 U4, LNS-92).
 //
 // Nothing here touches SSH, keys or services itself — install.sh keeps that authority, its options and its
 // exit codes (0 ready · 3 key not yet authorized · 4 server unreachable · 1 error).
+//
+// The enrolment-first update (W9 K3, LNS-88): an invite is redeemed once, so the installer that redeems it should be
+// the server's own release. install.sh is run with LANES_WRAPPER_REPLY naming a fresh file; with an invite it asks the
+// site's enrolment service which release the server runs before it installs or sends anything, and a newer one than
+// this package ends that run with `update-to=<release>` in the file and exit 5. This wrapper then runs `npx --yes
+// @vibelord/lanes@<release>` with the same arguments (the code moved to LANES_INVITE) and LANES_NO_SELF_UPDATE=1, which
+// never hands over again, and ends with its status. When that cannot run — no npx with its npm on PATH, a release npm
+// does not have (yet), npm not answering, a reply that names no newer release — install.sh runs once more from this
+// package with LANES_NO_SELF_UPDATE=1: the run that handed over installed and redeemed nothing. LANES_NO_SELF_UPDATE or
+// LANES_NO_AUTOUPDATE (any value) keeps the hand-over off; an exit 5 without a reply is install.sh's own status.
+//
+// A server install records the npx it ran with (W9 U3, LNS-91): after `--server` (not --check or --help) ends 0 or 4
+// (installed), the npx on PATH — with its npm beside it, as the hand-over finds them — is written to
+// $LANES_STATE/update/npx (~/.local/state/lanes/update/npx). `lanes update` and lanes-update.timer, whose unit PATH holds
+// no Node.js, install the next release with exactly that npx.
 
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
@@ -20,7 +40,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { inferredSite, installArgs, platformError, prunable, splitArgs } from '../lib/plan.mjs';
+import {
+  currentLink, handOverReply, inferredSite, installArgs, npmAnswer, npxRecord, platformError, prunable, recordsNpx,
+  relayArgv, relayEnv, releaseNewer, splitArgs,
+} from '../lib/plan.mjs';
 
 const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const payload = path.join(packageDir, 'payload');
@@ -31,6 +54,15 @@ function fail(message, code = 1) {
   process.exit(code);
 }
 
+// Written at once (fs.writeSync): a line said before a blocking spawnSync must reach the terminal before the child's.
+function say(message) {
+  fs.writeSync(1, `lanes-install: ${message}\n`);
+}
+
+function note(message) {
+  fs.writeSync(2, `lanes-install: ${message}\n`);
+}
+
 function readManifest() {
   try {
     return JSON.parse(fs.readFileSync(path.join(payload, 'manifest.json'), 'utf8'));
@@ -87,19 +119,22 @@ function stage(manifest) {
   return target;
 }
 
+// A client only (W9 U4, LNS-92; DEF-1768): with the server's `current` link present — even dangling — nothing is
+// deleted here, since what still runs from an old tree is visible only on the server; `lanes gc` prunes it there.
 function prune(root, target) {
-  const inUse = new Set([target]);
-  const data = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local/share');
+  let server = false;
   try {
-    inUse.add(fs.realpathSync(path.join(data, 'lanes', 'current')));   // what the server units point at
-  } catch { /* no server install */ }
+    // install/services.py writes the link under $HOME whatever $XDG_DATA_HOME says (W9 U0, DEF-1783).
+    fs.lstatSync(currentLink(os.homedir()));
+    server = true;
+  } catch { /* no link: a client */ }
   const entries = [];
   for (const name of fs.readdirSync(root)) {
     const dir = path.join(root, name);
     if (name.startsWith('.') || !stampOf(dir)) continue;   // only trees this wrapper staged
     entries.push({ path: dir, mtimeMs: fs.statSync(dir).mtimeMs });
   }
-  for (const dir of prunable(entries, inUse)) fs.rmSync(dir, { recursive: true, force: true });
+  for (const dir of prunable(entries, new Set([target]), { server })) fs.rmSync(dir, { recursive: true, force: true });
 }
 
 function usage(manifest) {
@@ -118,12 +153,100 @@ Wrapper options
 
 Bundled site profiles: ${manifest.sites.join(', ') || 'none'} (or --site /path/to/site.conf)
 Invite prefixes: ${Object.entries(manifest.site_codes || {}).map(([p, site]) => `${p} → ${site}`).join(', ') || 'none'} (an explicit --site wins)
+With an invite, a server that runs a newer release gets that release's installer first (npx @vibelord/lanes@<release>,
+once npm has it); LANES_NO_SELF_UPDATE=1 installs this one.
 Every other option goes to install.sh; its own help follows.
 
 `);
 }
 
+// An executable regular file named `name` in an absolute PATH directory (never the working directory), or null.
+function onPath(name, searchPath = process.env.PATH || '') {
+  for (const dir of searchPath.split(path.delimiter)) {
+    if (!path.isAbsolute(dir)) continue;
+    const file = path.join(dir, name);
+    if (executable(file)) return file;
+  }
+  return null;
+}
+
+function executable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// install.sh handed over to `release` (W9 K3): run that release's installer through npx and return its status, or null
+// (said why) when it cannot run, so this package's installer runs instead. npx from PATH and the npm beside it (Node.js
+// installs them in one folder), as lanes-launch's self-update finds them; only a release npm has is run (npx would
+// fail on any other only after its own registry round trip: DEF-1786's lesson).
+function handOver(release, manifest, passthrough) {
+  const instead = `installing ${manifest.version} from this package instead`;
+  if (release === null) {
+    note(`install.sh asked for an update that names no release: ${instead}`);
+    return null;
+  }
+  if (!releaseNewer(release, manifest.version)) {
+    note(`install.sh asked for ${release}, which is not newer than this package: ${instead}`);
+    return null;
+  }
+  const npx = onPath('npx');
+  const npm = npx && path.join(path.dirname(npx), 'npm');
+  if (!npx || !executable(npm)) {
+    note(`the server runs ${release}, and no npx with its npm is on PATH to fetch that installer: ${instead}`);
+    return null;
+  }
+  const { argv, invite } = relayArgv(passthrough, process.env);
+  const env = relayEnv(process.env, invite, path.dirname(npx));
+  const asked = spawnSync(npm, ['view', `@vibelord/lanes@${release}`, 'version', '--fetch-retries=0'], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15000, env,
+  });
+  const answer = npmAnswer(asked, release);
+  if (answer.state === 'missing') {
+    note(`the server runs ${release}, which npm does not have (yet): ${instead}`);
+    return null;
+  }
+  if (answer.state === 'failed') {
+    note(`the server runs ${release}; asking npm for it failed (${answer.why}): ${instead}`);
+    return null;
+  }
+  say(`the server runs ${release}: npx --yes @vibelord/lanes@${release}, with the same options`);
+  const relayed = spawnSync(npx, ['--yes', `@vibelord/lanes@${release}`, ...argv], { stdio: 'inherit', env });
+  if (relayed.error) {
+    note(`could not run npx (${relayed.error.code || relayed.error.message}): ${instead}`);
+    return null;
+  }
+  return relayed.status ?? 1;
+}
+
+// Record the npx of this server install for `lanes update` (W9 U3); a failure to record is a note, never the install's.
+function recordNpx() {
+  const npx = onPath('npx');
+  const file = npxRecord(process.env, os.homedir());
+  if (!npx || !executable(path.join(path.dirname(npx), 'npm'))) {
+    note(`no npx with its npm on PATH: ${file} is not written, so lanes update cannot install the next release`);
+    return;
+  }
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${npx}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    note(`could not record npx in ${file} (${error.code || error.message}): lanes update cannot install the next release`);
+  }
+}
+
 function main() {
+  const status = installMain();
+  if (recordsNpx(splitArgs(process.argv.slice(2)), status)) recordNpx();
+  return status;
+}
+
+function installMain() {
   const platform = platformError(process.platform);
   if (platform) fail(platform);
   const manifest = readManifest();
@@ -156,9 +279,39 @@ function main() {
   }
   if (inferred) process.stdout.write(`site ${inferred.site}, inferred from the invite code's prefix ${inferred.prefix}\n`);
   // Run through the staged path (not the npx cache), so install.sh resolves its checkout to the stable tree.
-  const result = spawnSync('sh', [path.join(staged, 'install.sh'), ...args], { stdio: 'inherit', cwd: staged });
-  if (result.error) fail(`could not run install.sh: ${result.error.message}`);
-  return result.status ?? 1;
+  const install = (env) => {
+    const result = spawnSync('sh', [path.join(staged, 'install.sh'), ...args], { stdio: 'inherit', cwd: staged, env });
+    if (result.error) {
+      note(`could not run install.sh: ${result.error.message}`);
+      return 1;
+    }
+    return result.status ?? 1;
+  };
+  const plain = { ...process.env };
+  delete plain.LANES_WRAPPER_REPLY;
+  if (process.env.LANES_NO_SELF_UPDATE || process.env.LANES_NO_AUTOUPDATE) return install(plain);
+  let replyDir;
+  try {
+    replyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lanes-install-'));
+  } catch (error) {
+    note(`no hand-over file (${error.code || error.message}): the server's release is not asked for`);
+    return install(plain);
+  }
+  try {
+    const reply = path.join(replyDir, 'reply');
+    const status = install({ ...plain, LANES_WRAPPER_REPLY: reply });
+    if (status !== 5) return status;
+    let text = '';
+    try {
+      text = fs.readFileSync(reply, 'utf8');
+    } catch { /* no hand-over: install.sh's own exit 5 */ }
+    const asked = handOverReply(text);
+    if (!asked.asked) return status;
+    const relayed = handOver(asked.release, manifest, passthrough);
+    return relayed ?? install({ ...plain, LANES_NO_SELF_UPDATE: '1' });
+  } finally {
+    fs.rmSync(replyDir, { recursive: true, force: true });
+  }
 }
 
 process.exit(main());

package/lib/plan.mjs

@@ -4,6 +4,8 @@
 // that tree's own `install.sh`. These functions decide only the platform gate, the wrapper's own flags and how
 // the passthrough arguments are rewritten.
 
+import path from 'node:path';
+
 export const SUPPORTED_PLATFORMS = ['darwin', 'linux'];
 
 export function platformError(platform) {
@@ -90,9 +92,117 @@ export function resolveSite(value, stagedDir, sites) {
   return `${stagedDir}/site/${value}/site.conf`;
 }
 
-// Which staged version directories to delete: keep the newest `keep` (by mtime) and anything still in use.
-// Server user units name the resolved staged path, so a version a running service came from is kept.
-export function prunable(entries, inUse, keep = 3) {
+// The server's `current` link: install/services.py writes it under the HOME directory, never under $XDG_DATA_HOME (the
+// units are rendered from $HOME), and lanes_lib.CURRENT reads the same place — so this link, wherever the staged trees
+// themselves live, is what tells the wrapper it runs on a server (W9 U0, LNS-82; DEF-1783; W9 U4, LNS-92).
+export function currentLink(home) {
+  return path.join(home, '.local/share', 'lanes', 'current');
+}
+
+// Which staged version directories the wrapper deletes after staging one: on a client, the ones past the newest `keep`
+// (by mtime) that are not in `inUse` (the tree just staged) — a client copies its commands out of the tree, so nothing
+// runs from an old one. On a server (`server`: the `current` link exists, even dangling) none: what still runs from an
+// old tree there — `current.previous` (the rollback target), a view layout built before W9 U1 naming `pkg/<version>`,
+// a process started through `current` before the last flip — is visible only on the server itself, so `lanes gc`
+// prunes it (bin/lanes staged_tree_plan, with the same newest-three rule; W9 U4, LNS-92, DEF-1768).
+export function prunable(entries, inUse, { keep = 3, server = false } = {}) {
+  if (server) return [];
   const sorted = [...entries].sort((a, b) => b.mtimeMs - a.mtimeMs);
   return sorted.slice(keep).filter((entry) => !inUse.has(entry.path)).map((entry) => entry.path);
 }
+
+// ---- the enrolment-first update (W9 K3, LNS-88) ---------------------------------------------------------------------
+// With an invite, install.sh asks the site's enrolment service which release the server runs before it installs or
+// sends anything. A newer one than this package ends that run: install.sh writes `update-to=<release>` to the file the
+// wrapper named in LANES_WRAPPER_REPLY and exits 5, and the wrapper runs `npx --yes @vibelord/lanes@<release>` with the
+// same arguments instead — the code moved to LANES_INVITE — and LANES_NO_SELF_UPDATE=1, so it never hands over again.
+
+// A release as `lanes hello` (bin/lanes version_key) and install.sh (release_key) read one: major.minor.patch, an
+// optional -/+ suffix that is not compared, at most 32 characters, each number at most 9 digits (install.sh's bound,
+// so the two client halves agree exactly). [major, minor, patch], or null for anything else.
+const RELEASE = /^([0-9]{1,9})\.([0-9]{1,9})\.([0-9]{1,9})(?:[-+][A-Za-z0-9.]+)?$/;
+
+export function releaseKey(text) {
+  if (typeof text !== 'string' || text.length > 32) return null;
+  const match = RELEASE.exec(text);
+  return match ? match.slice(1, 4).map(Number) : null;
+}
+
+// Whether `server` is a newer release than `mine`: both are releases, and major.minor.patch is higher as numbers.
+export function releaseNewer(server, mine) {
+  const a = releaseKey(server);
+  const b = releaseKey(mine);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+// install.sh's hand-over file: {asked: false} without an `update-to=` line (an exit 5 that is install.sh's own status),
+// else {asked: true, release} — release null when the value is no release (it is never shown then).
+export function handOverReply(text) {
+  const line = String(text ?? '').split('\n').find((each) => each.startsWith('update-to='));
+  if (line === undefined) return { asked: false, release: null };
+  const release = line.slice('update-to='.length).trim();
+  return { asked: true, release: releaseKey(release) ? release : null };
+}
+
+// The relayed command line: the same arguments without the invite code, which moves to LANES_INVITE — install.sh and
+// this wrapper read it there the same way (the last `--invite CODE`, else LANES_INVITE) — so the code is on no
+// command line of the second installer's processes (a process list shows any user's argv, never another's environment).
+export function relayArgv(passthrough, env = {}) {
+  const invite = inviteCode(passthrough, env);
+  const argv = [];
+  for (let i = 0; i < passthrough.length; i += 1) {
+    if (passthrough[i] === '--invite') {
+      i += 1;
+      continue;
+    }
+    argv.push(passthrough[i]);
+  }
+  return { argv, invite };
+}
+
+// The environment of `npm view` and the relayed npx: this one, with LANES_NO_SELF_UPDATE=1 (the newer installer never
+// hands over again), the code in LANES_INVITE, npx's folder first on PATH (node lives beside it), and without this run's
+// hand-over file or the options of the npx that started this wrapper — `npx -p <pkg>` exports npm_config_package and
+// `npx -c` npm_config_call (npm reads either case), with which the nested npx runs `@vibelord/lanes@<v>` as a command
+// (exit 127) or refuses (EUSAGE). MEASURED with npm 11; user configuration such as npm_config_registry stays.
+export function relayEnv(env, invite, npxDir) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key === 'LANES_WRAPPER_REPLY' || /^npm_config_(call|package)$/i.test(key)) continue;
+    out[key] = value;
+  }
+  out.LANES_NO_SELF_UPDATE = '1';
+  if (invite !== null && invite !== undefined) out.LANES_INVITE = invite;
+  if (npxDir) out.PATH = [npxDir, env.PATH].filter(Boolean).join(path.delimiter);
+  return out;
+}
+
+// What `npm view @vibelord/lanes@<release> version --fetch-retries=0` said, read as lanes-launch's self-update reads it
+// (on_npm, W9 K2): it printed exactly the release → 'has'; npm 10's `code E404`, or an earlier npm's empty exit 0 → 'missing'
+// (not published, yet); anything else → 'failed', with why (exit status and npm's error code, or the 15 s bound).
+export function npmAnswer({ status, stdout, stderr, error }, release) {
+  const printed = String(stdout ?? '');
+  if (printed.split('\n').some((line) => line.trim() === release)) return { state: 'has' };
+  const code = /\bcode (E[A-Z0-9_]+)/.exec(String(stderr ?? ''))?.[1] ?? null;
+  if (code === 'E404' || (!error && status === 0 && !printed.trim())) return { state: 'missing' };
+  if (error) return { state: 'failed', why: error.code === 'ETIMEDOUT' ? 'no answer within 15 s' : (error.code || error.message) };
+  return { state: 'failed', why: `exit ${status ?? 'by signal'}${code ? `, ${code}` : ''}` };
+}
+
+// ---- lanes update's npx (W9 U3, LNS-91) -----------------------------------------------------------------------------
+// `lanes update` (and lanes-update.timer, whose unit PATH holds no Node.js) installs the next release with the npx a
+// server install ran with, which the wrapper records once that install installed something: `--server` (whatever its
+// position: installArgs moves it first), neither `--check` (changes nothing) nor `--help`, and none of the wrapper's own
+// flags (each ends the run before install.sh), ending 0 (installed, or ok) or 4 (an update that installed and then ended
+// partial). `split` is splitArgs' {own, passthrough}.
+export function recordsNpx({ own, passthrough }, status) {
+  return own.size === 0 && passthrough.includes('--server')
+    && !['--check', '--help', '-h'].some((flag) => passthrough.includes(flag)) && (status === 0 || status === 4);
+}
+
+// Where: install.sh's state directory ($LANES_STATE, else ~/.local/state/lanes — host-install.sh's `state`), update/npx.
+export function npxRecord(env, home) {
+  return path.join(env.LANES_STATE || path.join(home, '.local/state/lanes'), 'update', 'npx');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibelord/lanes",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Installer for Lanes: shared agent terminals over SSH with Zellij views, registry sync, uploads and a phone interface.",
   "license": "MIT",
   "type": "module",

package/payload/lanes/README.md

@@ -114,37 +114,49 @@ The installer starts an empty catalog safely; it does not assume anyone's contai
 
 | Action | Command or control |
 | --- | --- |
-| Join a site from a new machine | `npx @vibelord/lanes --invite <code>` with the code from a member's invite: installs the client, authorizes this machine, then `lanes-launch`, `lanes-launch web phone`, `lanes-launch web laptop`. Without a code the installer asks the site's members for access ([guide](docs/USERGUIDE.md#2-join-a-site)) |
+| Join a site from a new machine | `npx @vibelord/lanes --invite <code>` with the code from a member's invite: installs the client, authorizes this machine, then `lanes-launch`, `lanes-launch web phone`, `lanes-launch web laptop`. When the server runs a newer release (and npm has it), that release's installer runs first and redeems the code (`LANES_NO_SELF_UPDATE=1`: the package you ran). Without a code the installer asks the site's members for access ([guide](docs/USERGUIDE.md#2-join-a-site)) |
 | Open desktop view | `lanes-window` or the Lanes app; `lanes-launch` inside any terminal |
 | Independent second view | `lanes-window 2` |
 | Two or three panes per workspace | `lanes-window w2` / `lanes-window w3` |
 | Switch workspace | Ctrl–Alt–Left / Right |
 | Next or previous lane | Ctrl–Alt–Down / Up (the focused pane moves to the next / previous lane of its workspace; nothing is typed, the focus stays), or tap the sidebar |
-| Plain-ASCII glyphs, light or dark tokens | `lanes-window --ascii`, `lanes-window --light` / `--dark` (remembered per device in `devices/<device>.json`; a running sidebar picks it up within one tick) |
-| Lock the view (plain keys and Zellij's mode keys reach the lane) | Ctrl–Alt–G, again to unlock; the bar shows LOCKED in red. The Ctrl–Alt keys of `zellij/config.kdl`'s `shared` block (←/→/↓/↑, `/`, U, C, S, PageUp/PageDown/End) stay active while locked. Ctrl–G itself always reaches the lane (Claude Code's editor key) |
+| Plain-ASCII glyphs, light or dark tokens | `lanes-window --ascii`, `lanes-window --light` / `--dark`. On a device with an owner the theme, colours and glyphs go to that person's profile, which every sidebar of all their devices paints within a tick (as a Done lane opened on one leaves Done on all); `lanes-window --light --device-only` keeps the look on this device (`devices/<device>.json`, where every look of a device without an owner goes), and a running sidebar picks it up within one tick. A terminal without 24-bit colour: `lanes attach <device> --color 256` (the fixed xterm-256 set; `--color 16` uses your terminal's own palette, `--color none` glyphs only) ([guide](docs/USERGUIDE.md#9-appearance)) |
+| Lock the view (plain keys and Zellij's mode keys reach the lane) | Ctrl–Alt–G, again to unlock; the bar shows LOCKED in red. The Ctrl–Alt keys of `zellij/config.kdl`'s `shared` block (←/→/↓/↑, `/`, U, L, C, S, PageUp/PageDown/End) stay active while locked. Ctrl–G itself always reaches the lane (Claude Code's editor key) |
 | Zellij modes | Ctrl–Alt–P pane · Ctrl–Alt–T tab · Ctrl–Alt–N resize · Ctrl–Alt–H move · Ctrl–Alt–F scroll · Ctrl–Alt–O session (`d` detaches) · Ctrl–Alt–B tmux-style; Esc returns to normal. Every key: [user guide](docs/USERGUIDE.md#keybindings) |
-| Search lanes | Ctrl–Alt–/, or `/` in the sidebar: fuzzy (the letters in order, substring and prefix matches first); Enter opens the match under the cursor, Esc clears |
+| Search lanes | Ctrl–Alt–/ (from anywhere in the tab: the focus moves to the sidebar and its filter starts; nothing is typed into the lane), or `/` in the sidebar: fuzzy (the letters in order, substring and prefix matches first); Enter opens the match under the cursor, Esc clears |
+| Focus the sidebar | Ctrl–Alt–L; while the sidebar has the keyboard its footer says ` ▌ keys go to sidebar · Esc → lane` (Esc, or any action, gives it back to the lane) |
 | Select a lane for pane 2 or 3 | `2` / `3` in the sidebar of a wide view |
 | Open one lane directly | `lanes-launch lane <lane-id>`; find IDs with `lanes-launch ls` |
+| Your settings on every device you own | Once a device has an owner (enrolled through an invite or a request, or `lanes device claim <device> --login <login>` for one from before), your look, the lanes you have opened, your board order and hidden boards and your pinned and hidden lanes live in one profile on the server, `users/<login>.json`, shared by all your devices; `--device-only` keeps a look on one device, and `--notify` / `--dim` always stay per device. `lanes user show <login>` prints it ([guide](docs/USERGUIDE.md#your-profile)) |
+| Pick up where you left off on another device | `lanes-launch here` shows in this machine's view the lane you opened last on any of your devices (its tab comes to the front); asked for, never automatic. On the server `lanes here <device>` |
+| Arrange your boards and lanes on all your devices | `lanes workspaces hide\|show\|order <id…>` and `lanes lane pin\|unpin\|hide\|show <lane-id>` on the server, each `--device <your device>` (or `--login <login>`): kept in your profile, which every device you own reads ([guide](docs/USERGUIDE.md#your-profile)) |
 | Read a markdown file a lane mentioned | Ctrl–Alt–M opens a floating **Preview** pane over the focused lane: the `.md` paths it printed in its last 300 lines that exist in its container (relative ones resolved against its working directory). One is shown at once; several give a numbered menu, newest first (Enter = the newest, `q` closes). Rendered by `glow` in the view's dark/light theme (the server installer adds a pinned glow unless the view server's PATH — `~/.local/share/lanes/bin`, the checkout's `bin`, `/usr/local/bin`, `/usr/bin`, `/bin` — already has one; a glow only in `~/.local/bin` or `~/go/bin` does not count), else `less -R`; `lanes doctor` names which (`preview renderer:`); quitting the pager closes the pane |
+| Edit a lane's AGENTS.md, CLAUDE.md or .env.local | Ctrl–Alt–E opens a floating **Edit** pane over the focused lane: the AGENTS.md and CLAUDE.md of its git checkout (and of the main checkout when it works in a worktree) and the main checkout's .env.local, each a key (`1`–`5`; Enter when only one is there; `q`/Esc closes; a missing file is shown `not present`, none is created). The key starts an editor inside the lane's container as its own user (`lanes attach <device> --editor micro\|hx\|nvim\|vim` picks it per device, or `lanes-launch <device> --editor E` from your machine; else the first of micro, hx, nvim, vim and vi there: Lanes installs none, vi is the floor); quitting the editor closes the pane. One Edit pane per view: pressing it again goes back to the open editor (or names the tab it is in) and never opens a second one on the same file. Off while the view is locked, like Ctrl–Alt–M |
 | Create a persistent workspace shell | The **+ New shell** row under **Unregistered** (desktop sidebar and phone picker), or `+` in the sidebar |
 | Register an existing session | **+** beside an unregistered session, or select it and press `a`; choose a workspace (`lanes register <lane-id> [workspace]` on the server) |
-| Declare a session in the repository | `P` in the sidebar, then `y`: writes the session's binding into the workspace's one repository `terminals.json`, so it becomes a repository lane `<workspace>--<slug>` |
-| Rename a lane | `R` in the sidebar (Enter saves, Esc cancels), or `lanes rename <lane-id> <name>` on the server; the lane id never changes |
+| Unregister a session you added | `u` in the sidebar (or `lanes unregister <lane-id>` on the server): it moves back to **Unregistered**, still running, same id and name, and the cursor goes with it; ` Unregistered ‘name’ · z undo` — `z` within 10 s adds it back (refused if the session was replaced meanwhile). A lane declared in a repository's `terminals.json` leaves that file (its terminal is removed, the session keeps running and is listed under **Unregistered** after the sync `u` starts; no `z`: the file's `.bak-<UTC>` copy keeps it), refused for the file's last terminal; `x` on any registered lane says ` registered: u to unregister first` |
+| Declare a session in the repository | `P` in the sidebar: the name is asked first (prefilled; Enter accepts, or edit it), then `y` and Enter (any other key cancels). Writes the session's binding into the workspace's one repository `terminals.json` under that name, so it becomes a repository lane `<workspace>--<slug>`; the row stays put with a dim `…` until the sync lists the lane, then moves into the list with the cursor on it |
+| Rename a lane | `R` in the sidebar (Enter saves, Esc cancels; arrows and Tab type nothing in the name, a click on the list cancels it first), or `lanes rename <lane-id> <name>` on the server; the lane id never changes, and your name wins over a `displayName` the repository's `terminals.json` declares |
 | Add a workspace (board) | `lanes workspaces add <id> --container <name> --repo /home/coder/<repo> [--title T]` on the server prints the catalog and manifest diff; add `--write` to apply, then `lanes sync` ([install](docs/INSTALL.md#2-configure-workspaces-and-editor-sync)) |
 | Onboard a user's container | `lanes onboard <login> --container <name> --workspace <id> --repo /home/coder/<repo>` on the server prints every step (board, contract, Claude and Codex hooks, Throttle attachment, canonical recipes, sync, doctor); add `--write` to apply them and keep a receipt ([install](docs/INSTALL.md#onboard-a-users-container)) |
-| See which agents need you | The sidebar sorts **Needs you** (◆ approval, ✗ error, ◇ waiting for a prompt), **Working** (▸) and **Done** (✓, until you open the lane) above the rest; the header counts them in the same glyphs (`◆1 ◇2 ▸6 ✓1`, zeros left out; `N lanes` when no lane runs an agent) |
-| Read a sidebar row | `▌` cursor · agent glyph · `›` the lane this pane shows (`²`/`³`: shown in pane 2/3) · the name (`·` per other viewer, `…` when clipped) · an **age column** on every row (agent turn, else last output: `45s`, ` 3m`, ` 2h`, ` 4d`; amber in **Needs you**) · stream glyph · one tail cell by priority (`?` not observed right now > `⚠` starving: producing output but no request for over 10 min, or a 429 > `↓` downgraded > `$` mostly paid — the economy cells need the opt-in economy poller; a dim `⚠`/`↓` is a frozen last-known figure, not a live alarm) · `×` close. `⋮ N more` ends a list that continues below |
-| End an unregistered session and its jobs | **×** beside the session, or select it and press `x`; confirm with `y` (any other key cancels) |
-| Every sidebar key | `?` replaces the list with the key sheet until the next key (that key only closes it). The footer legend says ` ⏎ open · / find · x close · ? keys`; prompts share one shape (` › close ‘name’? y/n`, ` › Rename: …█`, ` › Register ‘name’? y/n`) and a filter counts its matches (` /abc · 3 matches`) |
-| Jump to the next lane that needs you | `Tab` / `Shift-Tab` in the sidebar (cycles **Needs you** from the lane the pane shows; the pane title carries the counts and a lane that starts needing you raises one OSC 9 desktop notification on desktop layouts — `LANES_NOTIFY=0` in the sidebar's environment silences it, see the [user guide](docs/USERGUIDE.md#9-appearance) for how environment variables reach a sidebar) |
+| Let an agent see and manage its lanes | The container's agents get the Lanes MCP server, `lane-mcp`, from `lanes install-container <name>` (on by default; `--no-mcp` leaves it out). `lanes_whoami`, `lanes_list`, `lanes_status` and `lanes_capture` read the lanes of that container. `lanes_register`, `lanes_rename`, `lanes_unregister` and `lanes_new` change a lane's declaration, shown on the boards within about 15 s. `lanes_send` types into a sibling lane, `lanes_signal` reports the agent's own status, and `lanes_publish` puts a file on the docs page (`lane publish <file>` in a shell). Ending, interrupting or attaching a lane stays yours ([architecture](docs/ARCHITECTURE.md#agent-api), [guide](docs/USERGUIDE.md#agent-tools-mcp)) |
+| See which agents need you | The sidebar sorts **Needs you** (◆ approval, ✗ error, ◇ waiting for a prompt), **Working** (▸) and **Done** (✓, until you open the lane) above the rest; the header counts them in the same glyphs (`◆1 ◇2 ▸6 ✓1`, zeros left out; `N lanes` when no lane runs an agent). The queue holds still: each section keeps the order its lanes entered it, a lane moves up a section at once but down only after the new state has held 8 s (leaving Needs you) or 5 s (leaving Working or Done), so an agent that asks again within seconds of an answer does not jump; the Needs you and Working headers stay drawn, `(0)` included, and the cursor stays on its lane ([how](docs/ARCHITECTURE.md#attention-queue)) |
+| Read a sidebar row | `▌` cursor · agent glyph · `›` the lane this pane shows (`²`/`³`: shown in pane 2/3; `▲` pinned) · the name (`·` per other viewer, `…` when clipped) · an **age column** on every row (agent turn, else last output: `45s`, ` 3m`, ` 2h`, ` 4d`; amber in **Needs you**) · stream glyph · one tail cell by priority (`?` not observed right now > `⚠` starving: producing output but no request for over 10 min, or a 429 > `↓` downgraded > `$` mostly paid — the economy cells need the opt-in economy poller; a dim `⚠`/`↓` is a frozen last-known figure, not a live alarm) · `×` close. `⋮ N more` ends a list that continues below |
+| End an unregistered session and its jobs | **×** beside the session, or select it and press `x`: ` › close ‘name’ — y⏎ confirm · Esc cancel`; `y` arms (` — ⏎ confirm`), Enter closes; any other key cancels (typed text closes nothing unless it is `x`, `y`, Enter in a row) |
+| Every sidebar key | `?` replaces the list with the key sheet until the next key (that key only closes it): the short form of the [user guide's table](docs/USERGUIDE.md#the-sidebar), first `lanes <installed> · view <running>`, then companion keys on one line (`J K`, `Tab S-Tab`, `+ U d`, `u z`, `p h`, `H o`, `r ?`; `d` shows the cursor lane's docs link), ending with Ctrl–Alt–L, the chord that brings the keyboard to the sidebar from a lane. The footer legend says ` ⏎ open · / find · x close · ? keys`; one prompt at a time, in one shape on the desktop and the phone (` › close ‘name’ — y⏎ confirm · Esc cancel`, ` › Rename: …█`, ` › Register as: …█` then ` › register ‘name’ — y⏎ confirm`) and a filter counts its matches (` /abc · 3 matches`). What an action says in the footer (` Closed sh`, ` Cancelled`, why it failed) stays 3 s or until your next action, not just until the next key. After an action — a close, rename, register, cancel, `Esc`, `r`, closing `?`, a click that opens no lane — the keyboard goes back to the lane, so what you type next reaches the lane, not the sidebar; a prompt, the filter and the armed upload strip keep it |
+| Pin, hide | `p` pins the cursor lane (it leads its section, `▲`, and never falls below `⋮ N more`), `h` hides it, `o` shows the hidden lanes again (faint), `H` then `y` `Enter` hides the whole workspace — its tab closes, its lanes keep running. They are yours, not the device's: every device you own follows your profile on its next tick; a session under **Unregistered** is never hidden ([guide](docs/USERGUIDE.md#the-sidebar)) |
+| Jump to the next lane that needs you | `Tab` / `Shift-Tab` in the sidebar (cycles **Needs you** from the lane the pane shows; the pane title carries the counts and a lane that starts needing you raises one OSC 9 desktop notification on desktop layouts — `lanes-launch <device> --notify 0` (or `lanes attach <device> --notify 0` on the server) silences it for that device, live; `LANES_NOTIFY=0` in the shell that creates a view session does the same for it, see the [user guide](docs/USERGUIDE.md#9-appearance)) |
 | Other workspaces that need you | The row above the footer rule: ` ◆1 Worlds · ◇2 Code` (blank and absent when none; panes of 18 rows or more) |
 | What the fleet spends | With the opt-in economy poller ([RUNBOOK](docs/RUNBOOK.md#economy-projection-opt-in)) the same row is the fleet economy strip instead: ` $8.5k/16k 53% · F2 S1 · spill 76% · free 3/19` — overflow spend against the daily cap (amber at the alert level), new upstream 429s, this workspace's lanes by model tier (`F` fable, `O` opus, `S` sonnet, `H` haiku, `G` gpt), the pool's spill fraction, free accounts and the next 5 h reset, whole parts dropped from the end to fit; a leading `?` means the figures are frozen — the poller could not reach the daemon, or it stopped (no rewrite for over 3 min) |
-| Upload | Click the one-row upload strip above the footer (` ↑ uploads · click, then drop  (U)`) or press `U`, then drop anywhere on the window; or use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
+| Upload | Click the one-row upload strip above the footer (` ↑ uploads · click, then drop  (U)`), press `U` in the sidebar or Ctrl–Alt–U from anywhere in the tab, then drop anywhere on the window; or use `~/Lanes Uploads/<workspace>/`, or `lanes-upload <files>` |
+| See what an agent published, or upload from a phone | The Docs page, `https://<server>:8443/lanes-docs/`, open only to your own tailnet login: **More → Docs** on a phone or tablet, **Docs** in the laptop's Lanes bar, a ⌘/Ctrl-click on the sidebar's ` ↑ uploads · ▤ docs N` strip, or `d` on a lane for its own link. An agent publishes with `lanes_publish` (or `~/.lz/bin/lane publish <file>` in a lane's shell): Markdown with Mermaid diagrams rendered, HTML and SVG opened in a sandbox, any other file a download, each with a sha256 receipt; the page's drop area lands files in the workspace's `uploads/` with the same receipt. It answers nobody until the operator pins the Serve header check (`lanes enrol mode request`) ([user guide](docs/USERGUIDE.md#docs)) |
 | Phone view from a client | `lanes-launch web phone` in your own terminal: prepares `<your device>-phone` (phone layout), makes Tailscale Serve forward private HTTPS 8443 when the mapping is missing, prints the private URL with a QR code of it and a login token; scan the code or open the URL in Safari. `sh install/enable-phone.sh --host lanes` is the older one-shot for the device `phone` ([guide](docs/USERGUIDE.md#phone-safari-home-screen)) |
 | Laptop or tablet browser view | `lanes-launch web laptop` (`<your device>-web`, desktop layout) or `lanes-launch web <device> [--desktop\|--mobile]` from a client; on the server `lanes web <device> [--desktop\|--mobile] [--viewports N] [--token \| --print-only]` (prepares the view, enables the loopback web services, adds the Tailscale Serve `https:8443` mapping when missing, prints the private URL) ([guide](docs/INSTALL.md#laptop-and-tablet-browser)) |
 | Web login tokens | `lanes token list` (each token with the device it was created for), `lanes token revoke <device>`, `lanes token revoke-all --yes` ([runbook](docs/RUNBOOK.md#login-tokens)) |
-| Update the client | `lanes-launch update` (the newest client from npm with your remembered install options; flags you add win). A client older than the server says so in one dim line when it attaches |
+| Update the client | Automatic: before a window connects, at most every 6 h, a client older than the server installs exactly the server's release once npm has it (`npx --yes @vibelord/lanes@<version>` with your remembered install options) and starts again, once; a release npm does not have yet is only logged and asked about again 6 h later; a failure is one dim line and the window goes on, and closing the window ends the whole install (`LANES_NO_AUTOUPDATE=1`: off; a checkout's client never does). By hand: `lanes-launch update` (the newest client from npm with your remembered install options; flags you add win). A client older than the server says so in one dim line when it attaches |
+| Update the server | Automatic on an npm-installed server: `lanes-update.timer` (enabled by the full server install; `--update-only` never enables it, so on a server set up before 1.2.0 run `npx @vibelord/lanes@latest --server` once, or `systemctl --user enable --now lanes-update.timer`; `lanes doctor` warns while it is off) checks npm 15 min after a boot and every 30 min and installs a newer release (`npx --yes @vibelord/lanes@<version> --server --update-only` with the npx the install recorded; never a downgrade; `channel=stable` in `~/.config/lanes/update.conf` follows the `lanes-stable` tag). By hand: `lanes update --now`; `lanes update --status` prints the record of the last check and update; `lanes update --rollback` goes back to the release before and marks the one left bad. A checkout server updates with `git pull` ([guide](docs/USERGUIDE.md#update)) |
+| Which release the server runs | `lanes version` on the server: `lanes 1.2.0 (39998ed) · tree pkg/1.2.0 · current ✓ · statusd runs 1.1.0 ✗` — the release, its tree, whether `current` names it, and `✗` for each service whose last start ran an older tree or, on a checkout, came before its `git pull` (`started before its tree changed ✗`): restart it; `--json` for scripts. `lanes doctor` judges the same facts (only processes that run now; a daemon or sidebar with no record started from an older release) and adds the device layouts and the units, each `✗` with its fix ([user guide](docs/USERGUIDE.md#versions)) |
+| Which release this client or phone runs | `lanes-launch --version` (`lanes-launch 1.2.0`); its connecting line says it too (`lanes 1.2.0: connecting to lanes…`). On a phone or tablet, **More** shows the server's release above **Text size** (**Lanes v1.2.0**) |
 | Switch workspace or lane in a laptop browser | The **Lanes** chip (top right) opens the workspace and lane pickers |
 | Invite a teammate, approve a machine, remove one | On the server, in your own terminal: `lanes invite <name> --email <addr>` prints a five-line welcome kit with a one-time code (shown once, on a terminal only); `lanes enrol list` / `lanes enrol approve <id>` decide machines that asked without a code; `lanes enrol mode request` pins request mode once the Serve header check passed; `lanes offboard <device> --yes` revokes a machine's key, signs its browsers and phones out and ends its view ([guide](docs/USERGUIDE.md#invite-a-user-administrator), [install](docs/INSTALL.md#offboard-a-machine)) |
 | Detach | Close the window, or Ctrl–Alt–O then `d`; the agents keep running |
@@ -156,6 +168,9 @@ session reuses it; closing a view leaves it running. Registered lanes have no **
 **Add to workspace** keeps the session running and moves it into the selected workspace's registered list.
 The picker offers workspaces using the same container. Registration keeps its name and open views, persists
 across sync/reconnects, and removes its close control. On a phone, tap the **+** and a workspace; no typing is needed.
+`u` takes it out again (the session keeps running under **Unregistered**); `z` within 10 seconds undoes that.
+Closing from the phone needs no keyboard either: tap **×**, and while the picker asks, a short `⏎ y Esc` key row sits
+above the dock (`y` then `⏎` closes, `Esc` cancels).
 
 On iPhone, open the printed private HTTPS URL in Safari and choose **Share → Add to Home Screen**.
 The interface provides Workspaces, Lanes and Panes controls, safe areas, portrait/landscape layout and adjustable
@@ -174,9 +189,9 @@ long (agent since-time, or last output). Glyph then ASCII twin (`LANES_GLYPHS=as
 
 | Agent (column 2) | | Terminal (column 33) | | Marks |
 | --- | --- | --- | --- | --- |
-| `◆` `!` needs approval | `◇` `?` needs input | `●` `*` output in the last 20 s | `○` `o` quiet | `▌` `\|` cursor · `›` `=` viewing · `²` `2` / `³` `3` shown in viewport 2/3 |
-| `▸` `>` working | `✓` `v` done (until viewed) | `–` `-` no session right now | `!` `!` pane dead | `·` `.` viewers · `…` `~` clipped · `×` `x` close |
-| `✗` `X` errored | `_` `_` shell · `·` `.` idle | `✗` `x` container down | `?` `?` not observed · `·` `.` helper | `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now |
+| `◆` `!` needs approval | `◇` `?` needs input | `●` `*` output in the last 20 s | `○` `o` quiet | `▌` `\|` cursor · `›` `=` viewing · `²` `2` / `³` `3` shown in viewport 2/3 · `▲` `^` pinned |
+| `▸` `>` working | `✓` `v` done (until viewed) | `–` `-` no session right now | `!` `!` pane dead | `·` `.` viewers · `…` `~` clipped (end of a name) or on its way — closing, registering, a new shell (column 3, dim) · `×` `x` close |
+| `✗` `X` errored | `_` `_` shell · `·` `.` idle | `✗` `x` container down | `?` `?` not observed · `·` `.` helper | `⋮` `:` more rows · `↑` `^` uploads · `↓` `v` drop now · `▤` `#` docs |
 
 Column 34 is one tail cell: `?` stale (last known state shown) > `⚠` `!` starving > `↓` `v` downgraded > `$` mostly
 paid. Colour is reinforcement, never the only signal; `LANES_COLOR=none` keeps every glyph. Full tables, tokens and
@@ -239,13 +254,22 @@ See [workspace configuration](workspaces.example/README.md) and the [architectur
 
 After `git pull`, clients re-run `./install.sh` (it repeats the options remembered in
 `~/.config/lanes/install-options`); servers re-run `./install.sh --server` from their installed checkout. npm
-client installations update with `lanes-launch update` (`npx @vibelord/lanes@latest` with those options given again
-as flags); a server updates with `npx @vibelord/lanes@latest --server` on the host. After a server
-update, restart `lanes-statusd.service` (and `lanes-web`/`lanes-mobile` when their units or the pinned Zellij
-changed); existing views keep their layout until `lanes rebuild <device>`. `lanes hello` prints the server's
-version ([user guide](docs/USERGUIDE.md#update)). The server installer resolves the checkout's actual path,
-including `bw-tools/lanes`; no `~/lanes` clone is required. It preserves configured workspaces and existing agent
-sessions.
+client installations update themselves to the server's release when a window opens (at most every 6 h, once npm has it), or by hand
+with `lanes-launch update` (`npx @vibelord/lanes@latest` with those options given again as flags); an npm-installed server updates itself (`lanes-update.timer`, which the full `--server` install enables and `--update-only` never does: `lanes update --timer` every 30 min installs each newer npm release; `lanes update --now` by hand, `lanes update --rollback` back one release) with `npx @vibelord/lanes@<version> --server --update-only`, which you can also run on the host, and which
+then restarts statusd and every optional service that runs, re-installs the container contract, asks the viewports to
+reload, rebuilds each view whose layout changed and that no client is attached to (one you are looking at says
+`update ready · reload (r)` in its sidebar footer) and records the run in `~/.local/state/lanes/update/last.json` — every step runs even when one before it
+failed ([user guide](docs/USERGUIDE.md#update)). After a full `--server` install instead, restart
+`lanes-statusd.service` (and `lanes-web`/`lanes-mobile` when their units or the pinned Zellij changed); existing
+views keep their layout until `lanes rebuild <device>` — one built by 1.2.0 or later runs its
+sidebar and viewports through `~/.local/share/lanes/current`, so each starts the new release when it next starts,
+and `lanes sync` keeps recognising the tabs of either kind. `lanes version` prints the server's
+version and marks `✗` each service whose last start ran an older tree or, on a checkout, came before the pull
+(`lanes hello` prints the version alone; [user guide](docs/USERGUIDE.md#versions)); `lanes doctor` names what still
+runs older code — processes, view layouts, units — with the fix for each. `lanes-launch --version` prints a client's.
+The server installer resolves
+the checkout's actual path, including `bw-tools/lanes`; no `~/lanes` clone is required. It preserves configured
+workspaces and existing agent sessions.
 
 ```sh
 ./install.sh --check                       # client connectivity

package/payload/lanes/VERSION

@@ -1 +1 @@
-1.1.1
+1.3.0