visualproof 0.3.0 → 0.4.0

package/dist/server/film.js

@@ -0,0 +1,380 @@
+// The tips' tour film (UpdateSpec decision 14, the owner's of 2026-10-17): 3½–4 minutes at
+// 2560×1600, too large for the package and for git, so it is an asset of the repository's GitHub
+// prerelease `tour-1`, and the package pins it (assets/tips/tour.json: its file, sha256 and size).
+// The server fetches it the first time a page asks for it (GET /tips/tour.mp4), one download for
+// every request, checks its size and sha256, keeps it in the caches' root, and serves it from there
+// with byte ranges: no reader's browser reaches GitHub. Under `--updates off` it is never fetched,
+// and the page shows the tour's stills and captions alone.
+//
+//   <cache root>/media/                    the user's alone (0700), as versions/ is
+//   <cache root>/media/<sha256>.mp4        the film, checked, moved into place once whole
+//   <cache root>/media/.<sha256>.tmp-<pid> a download under way (that process's)
+//   <cache root>/media/pin-<pid>           the sha256 of the film a living server pins: kept
+//
+// Servers of different versions share the default cache root, each pinning its own film: a server
+// keeps the film it pins and those living servers' pins name, and removes the rest (an earlier
+// cut, a patch's film replaced) and the downloads of servers that died midway — as it starts, and
+// once its film is kept or confirmed; never while it downloads.
+//
+// VISUALPROOF_TOUR_FILM names a local file served in its place (a film being made: the checkout
+// that makes it); VISUALPROOF_MEDIA_BASE another address to fetch it from, honoured only where it is
+// a loopback address (the tests' asset server).
+import { createHash } from "node:crypto";
+import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { WEBFONTS } from "./pipeline.js";
+import { alive, private_ } from "./updates.js";
+/** where the film is published: the repository's prerelease `tour-1` */
+export const FILM_BASE = "https://github.com/LucianoXu/VisualProof/releases/download/tour-1/";
+/** the hosts a fetch of the film may be redirected to: GitHub's own, which keeps a release's
+ *  assets on its asset hosts (UpdateSpec decision 14) */
+export const FILM_HOSTS = new Set(["github.com", "objects.githubusercontent.com", "release-assets.githubusercontent.com", "github-releases.githubusercontent.com"]);
+/** The film the package pins: `film` of assets/tips/tour.json, or null. */
+export function filmPin(file = join(dirname(WEBFONTS), "tips", "tour.json")) {
+    try {
+        const f = JSON.parse(readFileSync(file, "utf8"))?.film;
+        if (!f || typeof f.file !== "string" || !/^[\w.-]+\.mp4$/.test(f.file) || typeof f.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(f.sha256) || !Number.isSafeInteger(f.size) || f.size <= 0)
+            return null;
+        return f;
+    }
+    catch {
+        return null;
+    }
+}
+const LOOPBACK = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?\//;
+/** The address the film is fetched from: VISUALPROOF_MEDIA_BASE where it is a loopback address (a
+ *  test's asset server), else the release's. */
+export function filmBase(env = process.env) {
+    const b = env.VISUALPROOF_MEDIA_BASE;
+    return b && LOOPBACK.test(b.endsWith("/") ? b : `${b}/`) ? (b.endsWith("/") ? b : `${b}/`) : FILM_BASE;
+}
+/** a download that got nothing for this long is given up */
+const IDLE_MS = 60_000;
+/** nor may a download take longer than this, whatever comes */
+const WHOLE_MS = 30 * 60_000;
+/** tried again after this, where it could not be had */
+export const RETRY_MS = 3600_000;
+/** and after this where what came was not the film (another size, another hash) */
+export const MISMATCH_RETRY_MS = 24 * 3600_000;
+/** Whether `url` is one a fetch of the film may go to: https on GitHub's hosts, or, where the film
+ *  is fetched from a loopback address (a test's), that address's host. */
+function allowed(url, base) {
+    if (LOOPBACK.test(base.href))
+        return url.host === base.host;
+    return url.protocol === "https:" && FILM_HOSTS.has(url.hostname);
+}
+/** The tour film, fetched once on demand, checked, kept and served (UpdateSpec decision 14). */
+export class Film {
+    o;
+    now;
+    base;
+    dir;
+    /** the one download (or the one check of what is kept) under way, which every request shares */
+    work = null;
+    failure = null;
+    /** checked in this process: what is kept is hashed once, then trusted */
+    checked = false;
+    constructor(o) {
+        this.o = o;
+        this.now = o.now ?? Date.now;
+        this.base = o.base ?? filmBase();
+        this.dir = join(o.cacheRoot, "media");
+    }
+    /** the film kept, where it is */
+    get kept() {
+        return this.o.pin ? join(this.dir, `${this.o.pin.sha256}.mp4`) : null;
+    }
+    status() {
+        const pin = this.o.pin;
+        if (this.o.local)
+            return { state: "local" };
+        if (!pin)
+            return { state: "none" };
+        const of = { sha256: pin.sha256, size: pin.size };
+        if (this.o.mode === "off")
+            return { state: "off", ...of };
+        if (this.work)
+            return { state: "fetching", ...of };
+        if (this.checked)
+            return { state: "cached", ...of };
+        if (this.failure && this.now() < this.failure.until)
+            return { state: "unavailable", ...of, why: this.failure.why, retry: new Date(this.failure.until).toISOString() };
+        return { state: "waiting", ...of };
+    }
+    /** The film's file, checked; null where there is none to serve now — `--updates off`, none
+     *  pinned, being fetched, or unavailable for a while. The first ask starts the one download (or
+     *  the one check of a film kept before), in the background: it outlives the request that started
+     *  it, and later asks share it. */
+    async file() {
+        if (this.o.local)
+            return existsSync(this.o.local) ? this.o.local : null;
+        const pin = this.o.pin;
+        const kept = this.kept;
+        if (!pin || !kept || this.o.mode === "off")
+            return null;
+        if (this.checked && existsSync(kept))
+            return kept;
+        this.checked = false;
+        if (this.work)
+            return null;
+        if (this.failure && this.now() < this.failure.until)
+            return null;
+        this.work = this.get(pin, kept).finally(() => {
+            this.work = null;
+            // the film kept or confirmed: what no living server pins goes
+            if (this.checked)
+                this.prune();
+        });
+        return null;
+    }
+    /** Begin, as the server serves: the film it pins marked as in use while it lives (`pin-<pid>`), and
+     *  what no living server pins removed. Nothing under `--updates off` (no film is served), or
+     *  without a pin. */
+    start() {
+        const pin = this.o.pin;
+        if (!pin || this.o.mode === "off" || this.ensure())
+            return;
+        const mark = join(this.dir, `pin-${process.pid}`);
+        try {
+            writeFileSync(mark, `${pin.sha256}\n`);
+            process.once("exit", () => {
+                try {
+                    unlinkSync(mark);
+                }
+                catch {
+                    // gone already
+                }
+            });
+        }
+        catch {
+            // unmarked: another server's prune may remove the film, which is fetched again
+        }
+        this.prune();
+    }
+    /** Remove the films no living server pins — this one's own pin kept, and every `pin-<pid>` of a
+     *  living process' — the pins of the dead, and the downloads of servers that died midway. Never
+     *  while this server downloads, nor in a folder another may write. */
+    prune() {
+        if (this.work || !private_(this.dir))
+            return;
+        let names = [];
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        const keep = new Set(this.o.pin ? [this.o.pin.sha256] : []);
+        for (const n of names) {
+            const m = /^pin-(\d+)$/.exec(n);
+            if (!m)
+                continue;
+            if (!alive(Number(m[1]))) {
+                rmSync(join(this.dir, n), { force: true });
+                continue;
+            }
+            try {
+                const sha = readFileSync(join(this.dir, n), "utf8").trim();
+                if (/^[0-9a-f]{64}$/.test(sha))
+                    keep.add(sha);
+            }
+            catch {
+                // gone meanwhile
+            }
+        }
+        for (const n of names) {
+            const film = /^([0-9a-f]{64})\.mp4$/.exec(n);
+            if (film && !keep.has(film[1])) {
+                rmSync(join(this.dir, n), { force: true });
+                this.o.log?.(`tour film: ${n} removed (no living server pins it)`);
+            }
+        }
+        this.sweep();
+    }
+    /** The download or check under way, done (for a test, and for whoever waits on it). */
+    async settled() {
+        await this.work;
+    }
+    fail(why, ms) {
+        this.failure = { why, until: this.now() + ms };
+        this.o.log?.(`tour film: ${why}; tried again ${ms >= MISMATCH_RETRY_MS ? "in a day" : "in an hour"}`);
+    }
+    /** What is kept, checked once; else the film fetched, checked and moved into place. */
+    async get(pin, kept) {
+        const bad = this.ensure();
+        if (bad)
+            return this.fail(bad, RETRY_MS);
+        if (existsSync(kept)) {
+            if (statSync(kept).size === pin.size && (await sha256Of(kept)) === pin.sha256) {
+                this.checked = true;
+                return;
+            }
+            rmSync(kept, { force: true });
+        }
+        this.sweep();
+        const tmp = join(this.dir, `.${pin.sha256}.tmp-${process.pid}`);
+        try {
+            const why = await this.download(pin, tmp);
+            if (why) {
+                rmSync(tmp, { force: true });
+                return this.fail(why.text, why.mismatch ? MISMATCH_RETRY_MS : RETRY_MS);
+            }
+            renameSync(tmp, kept);
+            this.checked = true;
+            this.failure = null;
+            this.o.log?.(`tour film: ${pin.file} fetched and checked (${(pin.size / 1e6).toFixed(1)} MB)`);
+        }
+        catch (e) {
+            rmSync(tmp, { force: true });
+            this.fail(`it could not be kept: ${e instanceof Error ? e.message : String(e)}`, RETRY_MS);
+        }
+    }
+    /** The folder made where it is not, the user's alone (0700); why it cannot be used, else null. */
+    ensure() {
+        try {
+            if (!existsSync(this.dir)) {
+                mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+                chmodSync(this.dir, 0o700);
+            }
+        }
+        catch (e) {
+            return `${this.dir} cannot be made: ${e.message}`;
+        }
+        return private_(this.dir) ? null : `${this.dir} is not this user's alone (another owns it, or others may write it)`;
+    }
+    /** Remove the downloads left by servers that died midway. */
+    sweep() {
+        let names = [];
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const m = /^\.[0-9a-f]{64}\.tmp-(\d+)$/.exec(n);
+            if (m && !alive(Number(m[1])))
+                rmSync(join(this.dir, n), { force: true });
+        }
+    }
+    /** Fetch the pinned file into `tmp`: redirects followed only to where the film may be (allowed),
+     *  at most five; no more bytes than the pin's size; given up after a minute with nothing or half
+     *  an hour in all; the size and sha256 checked. Why not, else null. */
+    async download(pin, tmp) {
+        const get = this.o.fetch ?? fetch;
+        const base = new URL(this.base);
+        let url = new URL(pin.file, base);
+        const stop = new AbortController();
+        const whole = setTimeout(() => stop.abort(new Error("it took more than half an hour")), WHOLE_MS);
+        let idle = null;
+        const quiet = () => {
+            if (idle)
+                clearTimeout(idle);
+            idle = setTimeout(() => stop.abort(new Error("nothing came for a minute")), IDLE_MS);
+        };
+        try {
+            quiet();
+            let res = null;
+            for (let hops = 0;; hops++) {
+                if (!allowed(url, base))
+                    return { text: `it was sent to ${url.origin}, which is not where the film is kept: not followed` };
+                res = await get(url, { redirect: "manual", signal: stop.signal, headers: { "user-agent": "VisualProof (the tips' tour film)" } });
+                if (res.status < 300 || res.status >= 400)
+                    break;
+                const to = res.headers.get("location");
+                await res.body?.cancel();
+                if (!to || hops >= 5)
+                    return { text: `${hops >= 5 ? "too many redirects" : "a redirect without an address"} at ${url.origin}` };
+                url = new URL(to, url);
+            }
+            if (!res.ok || !res.body)
+                return { text: `${url.origin} answered ${res.status}` };
+            const length = Number(res.headers.get("content-length"));
+            if (Number.isFinite(length) && length > 0 && length !== pin.size) {
+                await res.body.cancel();
+                return { text: `it is ${length} bytes, not the ${pin.size} pinned`, mismatch: true };
+            }
+            const hash = createHash("sha256");
+            let got = 0;
+            const out = createWriteStream(tmp, { mode: 0o600 });
+            const reader = res.body.getReader();
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    quiet();
+                    got += value.byteLength;
+                    // never more than the pin's size on the disk
+                    if (got > pin.size) {
+                        await reader.cancel();
+                        return { text: `more than the ${pin.size} bytes pinned came`, mismatch: true };
+                    }
+                    hash.update(value);
+                    if (!out.write(value))
+                        await new Promise((ok) => out.once("drain", () => ok()));
+                }
+            }
+            finally {
+                await new Promise((ok) => out.end(ok));
+            }
+            if (got !== pin.size)
+                return { text: `${got} bytes came, not the ${pin.size} pinned`, mismatch: true };
+            const sum = hash.digest("hex");
+            if (sum !== pin.sha256)
+                return { text: `its sha256 is ${sum.slice(0, 12)}…, not the ${pin.sha256.slice(0, 12)}… pinned`, mismatch: true };
+            return null;
+        }
+        catch (e) {
+            const why = stop.signal.aborted && stop.signal.reason instanceof Error ? stop.signal.reason.message : e instanceof Error ? e.message : String(e);
+            return { text: `it could not be fetched: ${why}` };
+        }
+        finally {
+            clearTimeout(whole);
+            if (idle)
+                clearTimeout(idle);
+        }
+    }
+}
+function sha256Of(file) {
+    return new Promise((ok, no) => {
+        const h = createHash("sha256");
+        createReadStream(file)
+            .on("data", (b) => h.update(b))
+            .on("end", () => ok(h.digest("hex")))
+            .on("error", no);
+    });
+}
+// ---------------------------------------------------------------- the server's one film
+let film = null;
+/** Set the server's film up (server/main.ts, as it serves): its cache, its mode, the package's pin,
+ *  VISUALPROOF_TOUR_FILM. */
+export function useFilm(o) {
+    film = new Film({ ...o, pin: o.pin === undefined ? filmPin() : o.pin, local: o.local === undefined ? process.env.VISUALPROOF_TOUR_FILM || null : o.local });
+    film.start();
+    return film;
+}
+/** The film's file to serve, or null (filmStatus says why): what GET /tips/tour.mp4 serves. */
+export function filmFile() {
+    return film ? film.file() : Promise.resolve(null);
+}
+export function filmStatus() {
+    return film ? film.status() : { state: "none" };
+}
+/** GET /tips/tour.mp4, whole (UpdateSpec decision 14): the film with byte ranges (`send`, the media
+ *  route's), or 503 with Retry-After while it is fetched (the first ask starts it), or 404 where
+ *  there is none to serve (`--updates off`, none pinned, unavailable for a while): the page shows
+ *  the stills and captions then. */
+export async function serveFilm(req, res, send) {
+    const file = await filmFile();
+    if (file)
+        return send(req, res, file);
+    const st = filmStatus();
+    const head = { "content-type": "application/json", "cache-control": "no-store" };
+    if (st.state === "fetching" || st.state === "waiting") {
+        res.writeHead(503, { ...head, "retry-after": "10" });
+        return void res.end(JSON.stringify({ film: st.state === "waiting" ? "fetching" : st.state }));
+    }
+    res.writeHead(404, head);
+    res.end(JSON.stringify({ film: st.state, ...(st.why ? { why: st.why } : {}) }));
+}

package/dist/server/history.js

@@ -28,6 +28,7 @@
 // deleted.
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { childEnv } from "./children.js";
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
@@ -58,7 +59,7 @@ export function buildTime(p) {
 }
 /** Git, read-only and taking no lock: its answer, or null where git or the repository is not there. */
 function git(root, ...args) {
-    const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5000, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" }, stdio: ["ignore", "pipe", "ignore"] });
+    const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout: 5000, env: childEnv({ GIT_OPTIONAL_LOCKS: "0" }), stdio: ["ignore", "pipe", "ignore"] });
     return r.status === 0 ? r.stdout.trim() : null;
 }
 /** The commit checked out now, and whether a `.lean` file differs from it. */
@@ -302,6 +303,14 @@ export class History {
     get(id) {
         return this.infos.get(id) ?? null;
     }
+    /** The VisualProof version that read the snapshot read last, where one says it. */
+    lastVersion() {
+        let last = null;
+        for (const i of this.infos.values())
+            if (i.tool && (!last || i.read > last.read))
+                last = i;
+        return last?.tool ?? null;
+    }
     /** The latest build's snapshot. */
     latest() {
         const l = this.list();
@@ -408,6 +417,7 @@ export class History {
             ...(o.imported || same?.imported ? { imported: true } : {}),
             ...(same?.renames ? { renames: same.renames } : {}),
             ...(texts ? { sources: texts } : {}),
+            ...(o.tool ? { tool: o.tool } : {}),
         };
         this.save(info);
         this.readOf(id).add(o.fingerprint);

package/dist/server/hover.js

@@ -23,6 +23,7 @@
 // with why; a question Lean does not answer in REQUEST_MS is answered that it did not; and what
 // Lean is doing is part of /api/status (`state`).
 import { spawn, spawnSync } from "node:child_process";
+import { childEnv, DETACH, end, grouped } from "./children.js";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -94,9 +95,9 @@ export class LeanHover {
         if (this.env)
             return this.env;
         const root = this.project.root;
-        const which = spawnSync("elan", ["which", "lean"], { cwd: root, encoding: "utf8", timeout: 60000 });
+        const which = spawnSync("elan", ["which", "lean"], { cwd: root, encoding: "utf8", timeout: 60000, env: childEnv() });
         const lean = which.status === 0 && which.stdout.trim() ? which.stdout.trim() : "lean";
-        const env = spawnSync("lake", ["env", "printenv", "LEAN_PATH"], { cwd: root, encoding: "utf8", timeout: 120000 });
+        const env = spawnSync("lake", ["env", "printenv", "LEAN_PATH"], { cwd: root, encoding: "utf8", timeout: 120000, env: childEnv() });
         if (env.status !== 0)
             throw new Error(`lake env failed: ${(env.stderr || env.stdout || "").trim().slice(0, 300)}`);
         this.env = { lean, leanPath: env.stdout.trim() };
@@ -109,7 +110,8 @@ export class LeanHover {
             const { lean, leanPath } = this.resolveEnv();
             if (!existsSync(this.dir))
                 mkdirSync(this.dir, { recursive: true });
-            const p = spawn(lean, ["--server"], { cwd: this.dir, env: { ...process.env, LEAN_PATH: leanPath }, stdio: ["pipe", "pipe", "pipe"] });
+            // a group of its own, which stopping ends with its workers (server/children.ts)
+            const p = grouped(spawn(lean, ["--server"], { cwd: this.dir, env: childEnv({ LEAN_PATH: leanPath }), stdio: ["pipe", "pipe", "pipe"], detached: DETACH }));
             this.proc = p;
             // what Lean writes is read here, in a callback no request waits on: nothing it writes may
             // throw out of it, or the server stops (read() skips what it cannot read)
@@ -141,7 +143,7 @@ export class LeanHover {
             if (init.error) {
                 const why = this.failure ?? init.error.message;
                 this.reset();
-                p.kill();
+                end(p);
                 throw new Error(why);
             }
             this.notify("initialized", {});
@@ -586,7 +588,8 @@ export class LeanHover {
         this.idle = null;
         const p = this.proc;
         this.reset();
-        p?.kill();
+        if (p)
+            end(p);
     }
 }
 /** Null after `ms`: what a question for Lean is raced against. */

package/dist/server/live.js

@@ -39,6 +39,8 @@ import { join } from "node:path";
 import { PROJECT, viewTitle } from "../shared/views.js";
 import { boardSet } from "../shared/board.js";
 import { derivesOn, existsIn } from "../shared/noteplace.js";
+import { packageVersion } from "./version.js";
+import { withoutReasons } from "../shared/timeline.js";
 const TICK = 1000;
 /** outputs quiet this long, and no compile running: the build is over */
 const SETTLE = 2500;
@@ -58,8 +60,6 @@ export const MAX_BUFFERED = 4 << 20;
 const PRESENCE_EVERY = 500;
 /** The graph's modules and their files (meta.modules), per graph read (agentviews.ts, graphOf). */
 const moduleFiles = new WeakMap();
-/** What a stream's page alone is told of it (`hello`). */
-const helloOf = (st) => ({ id: st.id, token: st.token, ...(st.private ? { private: true } : {}) });
 export class Live {
     project;
     /** the site directory and the project's caches (server/dirs.ts) */
@@ -85,6 +85,15 @@ export class Live {
     /** review changes not yet sent: those made in one turn of the event loop go out as one */
     reviewPending = [];
     version = 0;
+    /** this server's process, as its pages know it (UpdateSpec decision 8): the graph's versions are
+     *  counted again by another */
+    instance = randomBytes(6).toString("base64url");
+    /** the VisualProof version this server runs, read as it started */
+    toolVersion = packageVersion();
+    /** what a page is told of VisualProof's releases (server/updates.ts): everything, or the version
+     *  alone (`full` false: a read-only reader, an agent); null where nobody follows them (a test's
+     *  server) */
+    updateStatus = null;
     /** the review's logs (ReviewSpec.md, server/review.ts) */
     review;
     /** who has a page open (CollabSpec.md) */
@@ -140,7 +149,7 @@ export class Live {
         this.editor = editor;
         this.usage = new UsagePass(project, dirs, saved ? 0 : jobs, (l) => this.say(l));
         this.tracker = new BuildTracker(project);
-        this.timeline = new Timeline(dirs.site, (e) => this.send("activity", e));
+        this.timeline = new Timeline(dirs.site, (e) => this.sendActivity(e));
         this.tokens = new AgentTokens(dirs.site);
         this.invites = new Invites(dirs.site);
         // every page knows the names the people invited by a link go by, so that what each did shows
@@ -304,7 +313,7 @@ export class Live {
         // a private reader cannot be followed: what they asked is withdrawn
         if (priv)
             this.asks.withdraw(s.token);
-        this.write(s.res, "hello", helloOf(s));
+        this.write(s.res, "hello", this.helloOf(s));
         if (s.session) {
             if (priv)
                 this.views.hold(s.session, was ? [...(was.view ? [was.view] : []), ...was.tabs] : []);
@@ -660,7 +669,7 @@ export class Live {
                 written = found.written;
                 return found;
             };
-            const r = this.history.record(ex.graph, { at: buildTime(this.project), fingerprint: ex.fingerprint, commit, toolchain: this.project.toolchain, missing, sources });
+            const r = this.history.record(ex.graph, { at: buildTime(this.project), fingerprint: ex.fingerprint, commit, toolchain: this.project.toolchain, missing, sources, tool: this.toolVersion });
             if (!r.written)
                 return renamed;
             const s = r.info;
@@ -956,7 +965,53 @@ export class Live {
         if (!this.graph)
             return null;
         const { prep: _, ...info } = this.graph;
-        return info;
+        return { ...info, instance: this.instance };
+    }
+    /** What a stream's page alone is told of it (`hello`), and which server it is (UpdateSpec
+     *  decision 8): its version, and its process. */
+    helloOf(st) {
+        return { id: st.id, token: st.token, ...(st.private ? { private: true } : {}), server: { version: this.toolVersion, instance: this.instance } };
+    }
+    /** How many pages are open on the server (their event streams), read-only readers' too. */
+    get pages() {
+        return this.streams.size;
+    }
+    /** Whether the server is working on the build (an extraction, a re-layout, the usage pass):
+     *  no moment to restart in (UpdateSpec decision 6). */
+    get busy() {
+        return this.extracting || this.usage.status.state === "running";
+    }
+    /** What happened, to every page: a version set aside, without why, to those not told all
+     *  (UpdateSpec decision 11). */
+    sendActivity(e) {
+        if (e.kind !== "tool" || !e.setAside)
+            return this.send("activity", e);
+        const full = `event: activity\ndata: ${JSON.stringify(e)}\n\n`;
+        const slim = `event: activity\ndata: ${JSON.stringify(withoutReasons(e))}\n\n`;
+        for (const st of [...this.streams.values()])
+            this.push(st, st.toldAll ? full : slim);
+    }
+    /** What is known of VisualProof's releases changed: each page is told what it may know of it
+     *  (`toldAll`, as GET /api/updates says it). */
+    updatesChanged() {
+        const status = this.updateStatus;
+        if (!status)
+            return;
+        const full = `event: updates\ndata: ${JSON.stringify(status(true))}\n\n`;
+        const slim = `event: updates\ndata: ${JSON.stringify(status(false))}\n\n`;
+        for (const st of [...this.streams.values()])
+            this.push(st, st.toldAll ? full : slim);
+    }
+    /** The server stops (UpdateSpec decision 9): every page is told why — a restart into another
+     *  version (`update`), or a stop (`bye`) — and its stream ended, so that it comes back to the
+     *  server that answers next. */
+    end(why) {
+        const text = "update" in why ? `event: update\ndata: ${JSON.stringify(why.update)}\n\n` : `event: bye\ndata: ${JSON.stringify({ why: "stopped" })}\n\n`;
+        for (const st of [...this.streams.values()]) {
+            this.streams.delete(st.res);
+            this.byToken.delete(st.token);
+            st.res.end(text);
+        }
     }
     /** What /api/status says: enough for the loader and for a page that just connected. */
     status() {
@@ -981,7 +1036,7 @@ export class Live {
      *  it), `person` the personal link it came by. The stream is named by the server: the page is
      *  told its id, which everyone sees, and a secret for its heartbeats (`hello`); it is gone from
      *  presence when its stream closes. */
-    subscribe(res, session = null, person = null, readOnly = null) {
+    subscribe(res, session = null, person = null, readOnly = null, toldAll = readOnly === null) {
         if (session) {
             // a page that opens one more than a page needs (a reload whose old stream lingers) loses
             // its oldest
@@ -1001,12 +1056,14 @@ export class Live {
             connection: "keep-alive",
         });
         res.write("retry: 2000\n\n");
-        const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly };
+        const st = { res, id: randomBytes(9).toString("base64url"), token: randomBytes(24).toString("base64url"), session, private: false, person, readOnly, toldAll };
         this.streams.set(res, st);
         this.byToken.set(st.token, st);
         this.presence.open(st.id);
         res.on("close", () => this.close(st));
-        this.write(res, "hello", helloOf(st));
+        this.write(res, "hello", this.helloOf(st));
+        if (this.updateStatus)
+            this.write(res, "updates", this.updateStatus(st.toldAll));
         this.write(res, "presence", this.presence.list());
         this.write(res, "private", { count: this.presence.privateCount() });
         this.write(res, "people", this.invites.people());