@edgehero/pi-dispatch 4.3.1 → 5.1.0

package/src/updates-cli.mjs

@@ -0,0 +1,61 @@
+/**
+ * `pi-dispatch updates look|reconcile`: what the worker runs as a child (issue #796). A person may run them too, to see them work on a host, and they do the same thing.
+ * Exit 0 ran, 1 could not reach what it needed, 2 was asked for something else. Names only on stdout.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { piVersionOf, resolvePiBinary } from "./chat-fork.mjs";
+import { piAiVersion } from "./pricing.mjs";
+import { workerName } from "./config.mjs";
+import { boundedJson, buildLook, hostPiFacts } from "./updates-look.mjs";
+import { reconcileUpdates } from "./updates-reconcile.mjs";
+import { publishLook } from "./updates.mjs";
+
+const defaultExec = promisify(execFile);
+
+/** Doctor's own one-shot client: connected before the first command, bounded, and always dropped. */
+async function defaultWithClient(url, fn) {
+	const { withDoctorClient } = await import("./doctor.mjs");
+	return await withDoctorClient(url, fn);
+}
+
+export async function runUpdatesCli(argv, { env = process.env, cwd = process.cwd(), out = (s) => process.stdout.write(s), err = (s) => process.stderr.write(s), withClient = defaultWithClient, exec = defaultExec, look = null, fetchJson = boundedJson } = {}) {
+	const [what, ...rest] = argv;
+	if (!["look", "reconcile"].includes(what) || rest.length > 0) {
+		err("usage: pi-dispatch updates look|reconcile\n");
+		return 2;
+	}
+	if (!env.VALKEY_URL) {
+		err("pi-dispatch updates: VALKEY_URL is not set\n");
+		return 1;
+	}
+	if (what === "look" && env.PI_UPDATES_LOOK !== "1") {
+		err("pi-dispatch updates look: the look is off until PI_UPDATES_LOOK=1\n");
+		return 2;
+	}
+	const host = workerName(env);
+	try {
+		return await withClient(env.VALKEY_URL, async (redis) => {
+			if (what === "look") {
+				const proxyUrl = env.PI_UPDATES_PROXY || null;
+				const tested = piAiVersion();
+				const record = await (look ?? buildLook)({
+					env, host, pinned: tested, get: (url) => fetchJson(url, { proxyUrl }),
+					hostPi: async () => hostPiFacts({ tested, resolvePi: () => resolvePiBinary({ env }), versionOf: (path) => piVersionOf(path, { env }) }),
+				});
+				await publishLook(redis, record);
+				out(`updates look: published for ${host}\n`);
+				return 0;
+			}
+			const done = await reconcileUpdates({ redis, host, env, cwd, exec, log: (event, fields) => out(`${JSON.stringify({ event, ...fields })}\n`) });
+			if (done.unreachable) {
+				err("pi-dispatch updates reconcile: Valkey did not answer\n");
+				return 1;
+			}
+			return 0;
+		});
+	} catch (error) {
+		err(`pi-dispatch updates ${what}: ${error?.code ?? "failed"}\n`);
+		return 1;
+	}
+}

package/src/updates-look.mjs

@@ -0,0 +1,127 @@
+/**
+ * The daily look (issue #796, `REQ-PACKAGE-UPDATES`): which pi and which staged extensions are newer, and whether this repository's checks on the
+ * newest pi hold. Free, and it changes nothing. It runs in a child the worker starts (`doctor-spawner.mjs`'s reason: it must stay off the loop that
+ * renews paid job locks), and never in a job. Off until `PI_UPDATES_LOOK=1`.
+ *
+ * Bounded as doctor's model proposals are: five seconds, 1 MiB, no redirects, and through `PI_UPDATES_PROXY` when one is declared, with no direct
+ * fallback. A failed read is **unknown, never passing**.
+ */
+import * as nodeFs from "node:fs";
+import { dirname, join } from "node:path";
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+import { readStageManifest } from "./packages.mjs";
+import { PINNED_PI_NEEDLES } from "./host-pi.mjs";
+import { compareVersions, parseLookRecord, UPDATES_LOOK_EVERY_HOURS } from "./updates.mjs";
+
+/** Public repository, public API, no token: this reads what anyone can read. */
+export const BUMP_CHECKS_REPO = "edgehero/pi-dispatch";
+export const BUMP_BRANCH = "chore/pi-bump";
+export const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const MAX_BYTES = 1024 * 1024;
+
+/**
+ * The members of pi's extension API the admin extension needs, by the names `USED_API` declares in `admin/src/index.ts`. A dependency points from admin
+ * to the worker, so this is a copy, bolted to that list by `admin/test/updates-view.test.mjs`. A look starts pi only to ask its version and loads no extension, so
+ * it can only say whether the host's pi still defines them: the real probe is the extension's own at load.
+ */
+export const ADMIN_USED_API = Object.freeze(["registerCommand", "registerTool", "sendMessage", "on"]);
+
+/** Refusals here are thrown and turn into `unknown` at the caller: nothing below this line decides a state. */
+export async function boundedJson(url, { proxyUrl = null, request = undiciFetch, timeoutMs = 5000, maxBytes = MAX_BYTES, headers = {}, ProxyAgentClass = ProxyAgent } = {}) {
+	const dispatcher = proxyUrl ? new ProxyAgentClass(proxyUrl) : undefined;
+	try {
+		const response = await request(url, { ...(dispatcher ? { dispatcher } : {}), redirect: "error", signal: AbortSignal.timeout(timeoutMs), headers: { accept: "application/json", "user-agent": "pi-dispatch-updates-look", ...headers } });
+		if (!response.ok) return { status: response.status, value: null };
+		const parts = [];
+		let length = 0;
+		for await (const part of response.body) {
+			length += part.length;
+			if (length > maxBytes) throw new Error("response too large");
+			parts.push(part);
+		}
+		return { status: response.status, value: JSON.parse(Buffer.concat(parts).toString("utf8")) };
+	} finally {
+		await dispatcher?.close();
+	}
+}
+
+/** The `latest` dist-tag only, so a pre-release is never offered. Reading the version document keeps it small and downloads no tarball. */
+export async function newestVersion(pkg, { get, registry = DEFAULT_REGISTRY }) {
+	const { value } = await get(`${registry}/${pkg.startsWith("@") ? pkg.replace("/", "%2f") : pkg}/latest`);
+	return typeof value?.version === "string" ? value.version : null;
+}
+
+/**
+ * The checks on the bump branch, as long as that branch is about this version. A branch still on an older bump would otherwise report that older pi's
+ * checks as this one's, which is how a passing word would come to mean nothing.
+ */
+export async function bumpChecks(version, { get, api = "https://api.github.com" }) {
+	const ref = encodeURIComponent(BUMP_BRANCH);
+	const commit = await get(`${api}/repos/${BUMP_CHECKS_REPO}/commits/${ref}`);
+	const subject = String(commit.value?.commit?.message ?? "").split("\n")[0];
+	if (subject !== `chore(pi): run on pi ${version}`) return "unknown";
+	const { value } = await get(`${api}/repos/${BUMP_CHECKS_REPO}/commits/${ref}/check-runs?per_page=100`);
+	const runs = value?.check_runs;
+	// Fewer listed than exist means an unread run could be failing, which is unknown rather than a verdict on the ones read.
+	if (!Array.isArray(runs) || runs.length === 0 || value.total_count !== runs.length) return "unknown";
+	if (runs.some((run) => ["failure", "timed_out", "cancelled", "action_required", "startup_failure", "stale"].includes(run?.conclusion))) return "failing";
+	if (runs.some((run) => run?.status !== "completed")) return "pending";
+	return runs.every((run) => ["success", "neutral", "skipped"].includes(run?.conclusion)) ? "passing" : "unknown";
+}
+
+/**
+ * This host's own pi against the version pi-dispatch is tested with, and whether what it mirrors still holds there. `resolvePi` and `versionOf` are
+ * `chat-fork.mjs`'s, the pi this account would run. `needles` are `PINNED_PI_NEEDLES`; `absent` means there is simply no pi here, which is a normal host.
+ */
+export function hostPiFacts({ tested, resolvePi, versionOf, fs = nodeFs, needles = PINNED_PI_NEEDLES, api = ADMIN_USED_API }) {
+	const found = resolvePi();
+	if (!found?.path) return { version: null, tested, state: "absent", needles: "unknown", extension: "unknown" };
+	const version = versionOf(found.path);
+	const state = !version || !tested ? "unknown" : compareVersions(version, tested) === 0 ? "same" : compareVersions(version, tested) > 0 ? "newer" : "older";
+	const root = piPackageRoot(found.path, fs);
+	if (!root) return { version, tested, state, needles: "unknown", extension: "unknown" };
+	let needlesHold = "ok", extension = "ok";
+	try {
+		for (const [file, list] of Object.entries(needles)) {
+			const text = fs.readFileSync(join(root, file), "utf8");
+			if (!list.every((needle) => text.includes(needle))) needlesHold = "drift";
+		}
+	} catch { needlesHold = "drift"; }
+	try {
+		const loader = fs.readFileSync(join(root, "dist/core/extensions/loader.js"), "utf8");
+		if (!api.every((member) => loader.includes(`${member}(`))) extension = "drift";
+	} catch { extension = "drift"; }
+	return { version, tested, state, needles: needlesHold, extension };
+}
+
+/** The pi package a `pi` command belongs to, through its symlink. `null` for a wrapper that lives elsewhere: unknown, not a failure. */
+function piPackageRoot(piPath, fs) {
+	try {
+		let dir = dirname(fs.realpathSync(piPath));
+		for (let i = 0; i < 6; i += 1) {
+			const pkg = join(dir, "package.json");
+			if (fs.existsSync(pkg) && JSON.parse(fs.readFileSync(pkg, "utf8"))?.name === PI_PACKAGE) return dir;
+			dir = dirname(dir);
+		}
+	} catch { /* unreadable: unknown below */ }
+	return null;
+}
+
+/** Assemble one host's look. Throws nothing: every read that fails is a word on the record. */
+export async function buildLook({ env, host, pinned, now = Date.now, fs = nodeFs, get, hostPi, globalPiDir = env.PI_GLOBAL_PI_DIR }) {
+	const registry = env.PI_UPDATES_REGISTRY || DEFAULT_REGISTRY;
+	const attempt = async (fn) => { try { return { read: "ok", value: await fn() }; } catch { return { read: "unknown", value: null }; } };
+	const pi = await attempt(() => newestVersion(PI_PACKAGE, { get, registry }));
+	const newest = pi.read === "ok" && typeof pi.value === "string" ? pi.value : null;
+	let checks = null;
+	if (newest && pinned && compareVersions(newest, pinned) > 0) checks = (await attempt(() => bumpChecks(newest, { get }))).value ?? "unknown";
+	const manifest = globalPiDir ? readStageManifest({ globalPiDir, readFile: (p, e) => fs.readFileSync(p, e), fileExists: (p) => fs.existsSync(p) }) : null;
+	const packages = [];
+	for (const pkg of manifest?.packages ?? []) {
+		const got = await attempt(() => newestVersion(pkg.name, { get, registry }));
+		packages.push({ name: pkg.name, version: pkg.version, newest: got.read === "ok" ? got.value : null, read: got.read === "ok" && got.value ? "ok" : "unknown" });
+	}
+	const record = { v: 1, host, at: now(), everyHours: UPDATES_LOOK_EVERY_HOURS, pi: { pinned, newest, read: newest ? "ok" : "unknown", checks }, hostPi: await hostPi(), packages };
+	return parseLookRecord(record);
+}

package/src/updates-reconcile.mjs

@@ -0,0 +1,182 @@
+/**
+ * Each host applying what a person asked for (issue #796, `DES-PACKAGE-UPDATES-PREPARED-NOT-APPLIED`).
+ *
+ * A desired row per package, and each host moves to the newest generation. Never a copied request: those expire, and a queued Adopt followed by an Undo could
+ * replay stale. A host that was offline reads only the newest row when it returns, so an Adopt it never saw and the Undo of it become nothing at all.
+ *
+ * Determinate outcomes are a state on the host's row. A lock held by a peer or a registry that cannot be reached is no state: the host stays pending and tries again.
+ */
+import * as nodeFs from "node:fs";
+import { dirname, join } from "node:path";
+import { isSubscriptionAdapter } from "./updates-subscription-adapters.mjs";
+import { EXACT_VERSION_RE, PACKAGES_SUBDIR, parsePackagesFile, readStageManifest, stagedDirName } from "./packages.mjs";
+import { PackageStageError, SERVICE_NPM_TIMEOUT_MS, UNDO_DIR, pruneStagedTrees, serviceNpmEnv, stagePackageTree, stagedStem, treeDigest, withStageLock, writeStageManifest } from "./package-stage.mjs";
+import { compareVersions, readApplied, readDesired, writeApplied } from "./updates.mjs";
+
+export { isSubscriptionAdapter };
+
+const writable = (fs, path) => {
+	try {
+		fs.accessSync(path, nodeFs.constants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+
+/**
+ * The file's text with one package's entry set or removed, temp and rename. Other entries and their fields stay as they were, so an Adopt of one package
+ * and a later Undo of another do not disturb each other: restoring whole-file text would have undone everything since.
+ */
+function writePackagesEntry({ fs, path, name, entry }) {
+	const text = fs.existsSync(path) ? fs.readFileSync(path, "utf8") : null;
+	const doc = text === null ? { packages: [] } : JSON.parse(text);
+	const rows = Array.isArray(doc.packages) ? doc.packages : [];
+	const at = rows.findIndex((row) => row?.name === name);
+	if (entry === null && at >= 0) rows.splice(at, 1);
+	else if (entry !== null && at >= 0) rows[at] = entry;
+	else if (entry !== null) rows.push(entry);
+	doc.packages = rows;
+	const next = `${JSON.stringify(doc, null, 2)}\n`;
+	parsePackagesFile(next, path); // what is about to be written must be a file the stager would take
+	const temp = `${path}.${process.pid}.tmp`;
+	fs.writeFileSync(temp, next);
+	fs.renameSync(temp, path);
+}
+
+/** The file's current entry for a package, or `null`. Throws when the file does not parse: the caller reads that as unusable. */
+function readPackagesEntry({ fs, path, name }) {
+	if (!fs.existsSync(path)) return null;
+	const text = fs.readFileSync(path, "utf8");
+	parsePackagesFile(text, path);
+	const rows = JSON.parse(text).packages ?? [];
+	return rows.find((row) => row?.name === name) ?? null;
+}
+
+const undoPath = (packagesRoot, name) => join(packagesRoot, UNDO_DIR, `${stagedDirName(name)}.json`);
+
+function readUndo(fs, packagesRoot, name) {
+	try {
+		return JSON.parse(fs.readFileSync(undoPath(packagesRoot, name), "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+function replaceManifestEntry(manifest, name, entry) {
+	return { stagedAt: new Date().toISOString(), packages: manifest.packages.map((row) => (row.name === name ? entry : row)) };
+}
+
+const npmBinFor = (platform) => (platform === "win32" ? "npm.cmd" : "npm");
+
+/** Apply one desired row on this host. Returns the row to publish; throws `PackageStageError("infra")` to stay pending. */
+export async function applyDesired({ desired, env, cwd, fs = nodeFs, exec, now = Date.now, out = () => {}, platform = process.platform, globalPiDir = env.PI_GLOBAL_PI_DIR }) {
+	const row = (state, fields = {}) => ({ v: 1, generation: desired.generation, state, at: now(), version: null, reason: null, digest: null, ...fields });
+	const refuse = (reason, version = null) => row("cannot-adopt", { reason, version });
+	// A host that never took the Adopt being undone has nothing to take back, whichever else is true of it, and that includes having no overlay at all.
+	if (!globalPiDir || !fs.existsSync(globalPiDir)) return desired.op === "undo" ? row("no-change") : refuse("no-overlay");
+	const packagesRoot = join(globalPiDir, PACKAGES_SUBDIR);
+	const manifest = readStageManifest({ globalPiDir, readFile: (p, e) => fs.readFileSync(p, e), fileExists: (p) => fs.existsSync(p) });
+	const current = manifest?.packages.find((p) => p.name === desired.name) ?? null;
+	const undo = desired.op === "undo" ? readUndo(fs, packagesRoot, desired.name) : null;
+	if (desired.op === "undo" && undo?.generation !== desired.undoOf) return row("no-change", { version: current?.version ?? null });
+	if (!current) return refuse("not-staged-here");
+	if (!writable(fs, packagesRoot)) return refuse("overlay-read-only", current.version);
+	if (desired.op === "adopt" && isSubscriptionAdapter(desired.name)) return refuse("adapter", current.version);
+	// Never to an older version. A person may have moved past this row with `import-pi` since, and a host may read it again for any number of reasons (a new host, a lost applied key),
+	// with nobody looking: "nothing updates by itself" has to hold for a downgrade too. Going back is what Undo is for.
+	if (desired.op === "adopt" && compareVersions(current.version, desired.version) >= 0) return row("no-change", { version: current.version });
+	if (!EXACT_VERSION_RE.test(desired.version)) return refuse("stage-refused", current.version);
+	const packagesFile = env.PI_PACKAGES_FILE ?? join(cwd, "pi-packages.json");
+	try {
+		readPackagesEntry({ fs, path: packagesFile, name: desired.name });
+		// The file is replaced by temp and rename, so what has to be writable is its directory, whether or not the file itself is.
+		if (!writable(fs, dirname(packagesFile)) || (fs.existsSync(packagesFile) && !writable(fs, packagesFile))) throw new Error("not writable");
+	} catch {
+		return refuse("packages-file-unusable", current.version);
+	}
+
+	return await withStageLock({ fs, packagesRoot, now, holder: "updates-reconcile" }, async ({ stillHeld }) => {
+		const committing = () => { if (!stillHeld()) throw new PackageStageError("infra", "another stage took over this overlay's lock"); };
+		// Read again under the lock: a peer on a shared home may have applied this very row while we waited. It shares this manifest, and doing it twice
+		// would lose the record of what to undo.
+		const fresh = readStageManifest({ globalPiDir, readFile: (p, e) => fs.readFileSync(p, e), fileExists: (p) => fs.existsSync(p) });
+		const here = fresh?.packages.find((p) => p.name === desired.name) ?? null;
+		if (!here) return refuse("not-staged-here");
+		const stageOptions = { fs, exec, out, packagesRoot, npmBin: npmBinFor(platform), platform, timeoutMs: SERVICE_NPM_TIMEOUT_MS, env: serviceNpmEnv(env) };
+		const stageIt = async (entry) => {
+			try {
+				return { ...(await stagePackageTree({ ...stageOptions, entry })) };
+			} catch (error) {
+				if (error instanceof PackageStageError && error.kind === "not-found") return { refused: "version-not-found" };
+				if (error instanceof PackageStageError && error.kind === "policy") return { refused: "stage-refused" };
+				throw error instanceof PackageStageError ? error : new PackageStageError("infra", "the stage could not finish");
+			}
+		};
+
+		if (desired.op === "undo") {
+			const prior = undo.manifestEntry;
+			let dir = prior.dir;
+			// The old tree is kept for a week, and flipping back to it is what makes Undo instant. Past that it is staged again, at the exact version.
+			if (!fs.existsSync(join(packagesRoot, dir))) {
+				const staged = await stageIt({ name: prior.name, version: prior.version, dir: stagedStem(prior.dir) });
+				if (staged.refused) return refuse(staged.refused, here.version);
+				dir = staged.dir;
+			}
+			const manifest2 = replaceManifestEntry(fresh, desired.name, { ...prior, dir });
+			committing();
+			writePackagesEntry({ fs, path: packagesFile, name: desired.name, entry: undo.fileEntry });
+			writeStageManifest({ fs, packagesRoot, manifest: manifest2 });
+			fs.rmSync(undoPath(packagesRoot, desired.name), { force: true });
+			pruneStagedTrees({ fs, packagesRoot, manifest: manifest2, now });
+			return row("undone", { version: prior.version, digest: await treeDigest(join(packagesRoot, dir), { fs }) });
+		}
+
+		if (compareVersions(here.version, desired.version) >= 0) return row("no-change", { version: here.version });
+		const staged = await stageIt({ name: desired.name, version: desired.version, dir: stagedStem(here.dir) });
+		if (staged.refused) return refuse(staged.refused, here.version);
+		const removeUnnamed = () => { try { fs.rmSync(join(packagesRoot, staged.dir), { recursive: true, force: true }); } catch { /* the prune's, later */ } };
+		try {
+			const digest = await treeDigest(join(packagesRoot, staged.dir), { fs });
+			// Read under the lock, and kept if a previous attempt at this very generation already recorded it: that attempt may have written the pin before its manifest failed, and reading
+			// the file now would record the adopted pin as what came before it, so that Undo restored the wrong thing.
+			const earlier = readUndo(fs, packagesRoot, desired.name);
+			const priorEntry = earlier?.generation === desired.generation ? earlier.fileEntry : readPackagesEntry({ fs, path: packagesFile, name: desired.name });
+			const priorManifest = earlier?.generation === desired.generation ? earlier.manifestEntry : here;
+			committing();
+			// The undo record first, the pin second and the manifest last, so a crash leaves at worst a pin the next stage honours, and jobs still on the old set.
+			fs.mkdirSync(join(packagesRoot, UNDO_DIR), { recursive: true });
+			fs.writeFileSync(undoPath(packagesRoot, desired.name), `${JSON.stringify({ generation: desired.generation, manifestEntry: priorManifest, fileEntry: priorEntry })}\n`);
+			writePackagesEntry({ fs, path: packagesFile, name: desired.name, entry: { ...(priorEntry ?? { name: desired.name }), version: desired.version } });
+			const manifest2 = replaceManifestEntry(fresh, desired.name, { ...here, version: desired.version, dir: staged.dir });
+			writeStageManifest({ fs, packagesRoot, manifest: manifest2 });
+			pruneStagedTrees({ fs, packagesRoot, manifest: manifest2, now });
+			return row("adopted", { version: desired.version, digest });
+		} catch (error) {
+			// Nothing names this tree yet, and each retry would leave one more.
+			removeUnnamed();
+			throw error instanceof PackageStageError ? error : new PackageStageError("infra", "the stage could not commit");
+		}
+	});
+}
+
+/** One pass on this host: every row newer than what it applied, oldest first, one failure not stopping the rest. Returns a count of what happened, names only. */
+export async function reconcileUpdates({ redis, host, env, cwd, fs = nodeFs, exec, now = Date.now, log = () => {}, platform = process.platform }) {
+	const desired = await readDesired(redis);
+	const applied = desired === null ? null : await readApplied(redis, host);
+	if (!desired || !applied) return { unreachable: true };
+	const done = { applied: 0, pending: 0 };
+	for (const row of desired) {
+		if ((applied[row.name]?.generation ?? 0) >= row.generation) continue;
+		try {
+			const result = await applyDesired({ desired: row, env, cwd, fs, exec, now, platform });
+			await writeApplied(redis, host, row.name, result);
+			done.applied += 1;
+			log("updates_applied", { package: row.name, generation: row.generation, state: result.state, reason: result.reason });
+		} catch (error) {
+			done.pending += 1;
+			log("updates_pending", { package: row.name, generation: row.generation, kind: error instanceof PackageStageError ? error.kind : "infra" });
+		}
+	}
+	return done;
+}

package/src/updates-subscription-adapters.mjs

@@ -0,0 +1,8 @@
+/**
+ * Which packages carry a reviewed subscription adapter's identity (`docs/global-pi-overlay.md`), which re-staging would break. Its own module so that the console can ask without loading the stager.
+ */
+import { COMMUNITY_AUTH_ADAPTERS } from "./community-auth-metadata.mjs";
+
+export function isSubscriptionAdapter(name) {
+	return Object.values(COMMUNITY_AUTH_ADAPTERS).some((adapter) => adapter.package === name);
+}

package/src/updates.mjs

@@ -0,0 +1,252 @@
+/**
+ * The Updates page's facts and a person's desired versions, in Valkey (issue #796, `INT-UPDATES-KEYS`, `DES-PACKAGE-UPDATES-PREPARED-NOT-APPLIED`).
+ *
+ * THE SAME TEST AS DOCTOR'S RESULTS: delete every `updates:*` key while the fleet runs and every job behaves exactly as before, because a job reads
+ * only the stage manifest on disk. What is lost is the page's facts and any Adopt no host has applied yet.
+ *
+ * A look record is rebuilt on read, never passed through. Names and versions must match the same rules the stager takes, and each state is a closed
+ * word, so what a registry or a forge answered cannot reach a viewer as anything else.
+ */
+import { randomUUID } from "node:crypto";
+import { EXACT_VERSION_RE, NPM_NAME_RE } from "./packages.mjs";
+import { WORKER_NAME_RE } from "./worker-name.mjs";
+
+export const UPDATES_HOSTS = "updates:hosts";
+export const UPDATES_GENERATION = "updates:generation";
+export const UPDATES_DESIRED = "updates:desired";
+export const updatesLookKey = (host) => `updates:h:${host}`;
+export const updatesAppliedKey = (host) => `updates:applied:${host}`;
+export const updatesCanaryKey = (name, version) => `updates:canary:${name}@${version}`;
+
+export const UPDATES_LOOK_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export const UPDATES_CANARY_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** A host with no row at the newest generation is pending; this long after the request it reads as overdue, never as lost. */
+export const UPDATES_OVERDUE_MS = 24 * 60 * 60 * 1000;
+export const UPDATES_LOOK_EVERY_HOURS = 24;
+export const UPDATES_HOSTS_MAX = 64;
+export const UPDATES_PACKAGES_MAX = 64;
+export const UPDATES_EXCERPT_MAX = 2000;
+
+export const READ_STATES = Object.freeze(["ok", "unknown"]);
+export const CHECK_STATES = Object.freeze(["passing", "failing", "pending", "unknown"]);
+export const HOST_PI_STATES = Object.freeze(["same", "newer", "older", "absent", "unknown"]);
+export const PROBE_STATES = Object.freeze(["ok", "drift", "unknown"]);
+export const APPLIED_STATES = Object.freeze(["adopted", "undone", "no-change", "cannot-adopt"]);
+export const CANNOT_ADOPT_REASONS = Object.freeze(["no-overlay", "overlay-read-only", "packages-file-unusable", "adapter", "not-staged-here", "version-not-found", "stage-refused"]);
+export const DESIRED_OPS = Object.freeze(["adopt", "undo"]);
+
+const OP_TIMEOUT_MS = 3_000;
+const object = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const word = (value, words) => (words.includes(value) ? value : null);
+const name = (value) => (typeof value === "string" && value.length <= 214 && NPM_NAME_RE.test(value) ? value : null);
+const version = (value) => (typeof value === "string" && value.length <= 128 && EXACT_VERSION_RE.test(value) ? value : null);
+const instant = (value) => (Number.isSafeInteger(value) && value > 0 ? value : null);
+const digest = (value) => (typeof value === "string" && /^[a-f0-9]{64}$/.test(value) ? value : null);
+const person = (value) => (typeof value === "string" && /^[A-Za-z0-9._@-]{1,64}$/.test(value) ? value : null);
+
+function bounded(promise, timeoutMs = OP_TIMEOUT_MS) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error("valkey did not answer")), timeoutMs);
+		timer.unref?.();
+		Promise.resolve(promise).then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+	});
+}
+
+/** A version's order, as semver says: a pre-release sorts before its release, its dot-separated parts compared in turn, numbers as numbers and below words. Build metadata does not order. */
+export function compareVersions(a, b) {
+	const parts = (v) => {
+		const [core, pre = null] = String(v).split("+")[0].split(/-(.*)/s);
+		return { nums: core.split(".").map(Number), pre };
+	};
+	const x = parts(a), y = parts(b);
+	for (let i = 0; i < 3; i += 1) {
+		if (x.nums[i] !== y.nums[i]) return x.nums[i] < y.nums[i] ? -1 : 1;
+	}
+	if (x.pre === y.pre) return 0;
+	if (x.pre === null) return 1;
+	if (y.pre === null) return -1;
+	const xs = x.pre.split("."), ys = y.pre.split(".");
+	for (let i = 0; i < Math.max(xs.length, ys.length); i += 1) {
+		if (xs[i] === undefined) return -1;
+		if (ys[i] === undefined) return 1;
+		if (xs[i] === ys[i]) continue;
+		const xn = /^\d+$/.test(xs[i]), yn = /^\d+$/.test(ys[i]);
+		if (xn && yn) return Number(xs[i]) < Number(ys[i]) ? -1 : 1;
+		if (xn !== yn) return xn ? -1 : 1;
+		return xs[i] < ys[i] ? -1 : 1;
+	}
+	return 0;
+}
+
+/** One look record, rebuilt from anything: `null` unless its frame is whole, and an unknown word degrades to `unknown`, never to a good state. */
+export function parseLookRecord(text) {
+	let raw;
+	try { raw = typeof text === "string" ? JSON.parse(text) : text; } catch { return null; }
+	if (!object(raw) || raw.v !== 1 || !WORKER_NAME_RE.test(raw.host ?? "") || !instant(raw.at) || !Number.isSafeInteger(raw.everyHours) || raw.everyHours < 1 || raw.everyHours > 168) return null;
+	const pi = object(raw.pi) ? raw.pi : {};
+	const host = object(raw.hostPi) ? raw.hostPi : {};
+	const packages = [];
+	for (const row of Array.isArray(raw.packages) ? raw.packages.slice(0, UPDATES_PACKAGES_MAX) : []) {
+		const pkg = object(row) ? name(row.name) : null;
+		const at = object(row) ? version(row.version) : null;
+		if (!pkg || !at) continue;
+		packages.push({ name: pkg, version: at, newest: version(row.newest), read: word(row.read, READ_STATES) ?? "unknown" });
+	}
+	return {
+		v: 1, host: raw.host, at: raw.at, everyHours: raw.everyHours,
+		pi: { pinned: version(pi.pinned), newest: version(pi.newest), read: word(pi.read, READ_STATES) ?? "unknown", checks: pi.checks === null ? null : word(pi.checks, CHECK_STATES) ?? "unknown" },
+		hostPi: { version: version(host.version), tested: version(host.tested), state: word(host.state, HOST_PI_STATES) ?? "unknown", needles: word(host.needles, PROBE_STATES) ?? "unknown", extension: word(host.extension, PROBE_STATES) ?? "unknown" },
+		packages,
+	};
+}
+
+export const lookIsStale = (record, now) => now - record.at > 2 * record.everyHours * 60 * 60 * 1000;
+
+/** The value and its expiry in one command, for doctor's reason. The look's whole record replaces the last one. */
+export async function publishLook(redis, record) {
+	const parsed = parseLookRecord(record);
+	if (!parsed) throw new Error("not a look record");
+	await bounded(redis.set(updatesLookKey(parsed.host), JSON.stringify(parsed), "PX", UPDATES_LOOK_TTL_MS));
+	await bounded(redis.sadd(UPDATES_HOSTS, parsed.host));
+}
+
+/** `{ hosts: [{ record, stale }], more }` or `{ unreachable }`. Writes nothing: a viewer's page view prunes no index. */
+export async function readLooks(redis, { now = Date.now } = {}) {
+	try {
+		const members = (await bounded(redis.smembers(UPDATES_HOSTS))) ?? [];
+		const names = [...new Set(members)].filter((host) => typeof host === "string" && WORKER_NAME_RE.test(host)).sort();
+		const wanted = names.slice(0, UPDATES_HOSTS_MAX);
+		if (wanted.length === 0) return { hosts: [], more: 0 };
+		const values = await bounded(redis.mget(...wanted.map(updatesLookKey)));
+		const hosts = [];
+		for (const value of values) {
+			const record = typeof value === "string" ? parseLookRecord(value) : null;
+			if (record) hosts.push({ record, stale: lookIsStale(record, now()) });
+		}
+		return { hosts, more: names.length - wanted.length };
+	} catch {
+		return { unreachable: true };
+	}
+}
+
+/** One desired row, rebuilt. `undoOf` is the generation an Undo takes back. */
+export function parseDesired(text) {
+	let raw;
+	try { raw = typeof text === "string" ? JSON.parse(text) : text; } catch { return null; }
+	if (!object(raw) || raw.v !== 1 || !Number.isSafeInteger(raw.generation) || raw.generation < 1) return null;
+	const pkg = name(raw.name), at = version(raw.version), op = word(raw.op, DESIRED_OPS), by = person(raw.by), when = instant(raw.at);
+	if (!pkg || !at || !op || !by || !when) return null;
+	const undoOf = op === "undo" && Number.isSafeInteger(raw.undoOf) && raw.undoOf > 0 ? raw.undoOf : null;
+	if (op === "undo" && undoOf === null) return null;
+	const from = version(raw.from);
+	return { v: 1, generation: raw.generation, name: pkg, version: at, op, by, at: when, ...(undoOf === null ? {} : { undoOf }), ...(from === null ? {} : { from }), request: typeof raw.request === "string" && raw.request.length <= 64 ? raw.request : null };
+}
+
+/**
+ * The generation and its row in ONE script. INCR then HSET as two commands would let two concurrent requests land in the wrong order, leaving the older one as the row with the
+ * newer one's generation lost, and every host would then reconcile to what nobody last asked for. `expectGeneration` makes it a compare and set: what a person's preview was shown has to
+ * still be the row, or nothing is written and it answers 0 (a racing Undo would otherwise overwrite an Adopt it never saw).
+ */
+const SET_DESIRED = `if ARGV[3] ~= '' then
+  local current = redis.call('HGET', KEYS[2], ARGV[1])
+  local generation = 0
+  if current then generation = cjson.decode(current).generation end
+  if string.format('%d', generation) ~= ARGV[3] then return 0 end
+end
+local g = redis.call('INCR', KEYS[1])
+local row = cjson.decode(ARGV[2])
+row.generation = g
+redis.call('HSET', KEYS[2], ARGV[1], cjson.encode(row))
+return g`;
+
+/** Record what a person asked for, and return its generation, or 0 when `expectGeneration` no longer holds. */
+export async function setDesired(redis, { name: pkg, version: at, op, by, at: when, undoOf = null, from = null, expectGeneration = null }) {
+	const row = { v: 1, generation: 1, name: pkg, version: at, op, by, at: when, ...(undoOf === null ? {} : { undoOf }), ...(from === null ? {} : { from }), request: randomUUID() };
+	if (!parseDesired(row)) throw new Error("not a desired version");
+	return await bounded(redis.eval(SET_DESIRED, 2, UPDATES_GENERATION, UPDATES_DESIRED, pkg, JSON.stringify(row), expectGeneration === null ? "" : String(expectGeneration)));
+}
+
+/** Every desired row, or `null` when Valkey could not answer. An unreadable row is one nobody can act on, so it is left out. */
+export async function readDesired(redis) {
+	try {
+		const raw = (await bounded(redis.hgetall(UPDATES_DESIRED))) ?? {};
+		const rows = [];
+		for (const [key, value] of Object.entries(raw)) {
+			const row = parseDesired(value);
+			if (row && row.name === key) rows.push(row);
+		}
+		return rows.sort((a, b) => a.generation - b.generation);
+	} catch {
+		return null;
+	}
+}
+
+export function parseApplied(text) {
+	let raw;
+	try { raw = typeof text === "string" ? JSON.parse(text) : text; } catch { return null; }
+	if (!object(raw) || raw.v !== 1 || !Number.isSafeInteger(raw.generation) || raw.generation < 1) return null;
+	const state = word(raw.state, APPLIED_STATES), when = instant(raw.at);
+	if (!state || !when) return null;
+	return { v: 1, generation: raw.generation, state, version: version(raw.version), reason: state === "cannot-adopt" ? word(raw.reason, CANNOT_ADOPT_REASONS) : null, digest: digest(raw.digest), at: when };
+}
+
+export async function writeApplied(redis, host, pkg, row) {
+	const parsed = parseApplied(row);
+	if (!parsed || !WORKER_NAME_RE.test(host) || !name(pkg)) throw new Error("not an applied row");
+	// No expiry: a row's expiry would have this host read an old desired row as new, with nobody looking. A host holds one small row per package.
+	await bounded(redis.hset(updatesAppliedKey(host), pkg, JSON.stringify(parsed)));
+}
+
+/** `{ <package>: row }` for one host, or `null` when Valkey could not answer. */
+export async function readApplied(redis, host) {
+	try {
+		const raw = (await bounded(redis.hgetall(updatesAppliedKey(host)))) ?? {};
+		const rows = {};
+		for (const [key, value] of Object.entries(raw)) {
+			const row = parseApplied(value);
+			if (row && name(key)) rows[key] = row;
+		}
+		return rows;
+	} catch {
+		return null;
+	}
+}
+
+/** Whether this host has work: any desired row newer than what it applied. Read every couple of minutes by the worker, so it must stay two reads. */
+export async function hostHasPending(redis, host) {
+	const desired = await readDesired(redis);
+	const applied = desired === null ? null : await readApplied(redis, host);
+	if (!desired || !applied) return false;
+	return desired.some((row) => (applied[row.name]?.generation ?? 0) < row.generation);
+}
+
+/** Third-party text for a person to read: control characters gone, cut to its bound. Escaped where it is drawn, like everything else. */
+export function changelogExcerpt(text) {
+	if (typeof text !== "string") return null;
+	const clean = text.replace(/\r\n/g, "\n").replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, " ").trim();
+	return clean === "" ? null : clean.slice(0, UPDATES_EXCERPT_MAX);
+}
+
+export function parseCanaryFacts(text) {
+	let raw;
+	try { raw = typeof text === "string" ? JSON.parse(text) : text; } catch { return null; }
+	if (!object(raw) || raw.v !== 1 || !WORKER_NAME_RE.test(raw.host ?? "") || !instant(raw.at)) return null;
+	return { v: 1, host: raw.host, at: raw.at, digest: digest(raw.digest), excerpt: changelogExcerpt(raw.excerpt) };
+}
+
+/** What a canary's install found, published beside the host's facts and never on the run record: the excerpt is a third party's text. */
+export async function publishCanaryFacts(redis, { name: pkg, version: at, host, digest: tree, excerpt, at: when }) {
+	if (!name(pkg) || !version(at)) throw new Error("not a canary's package");
+	const facts = parseCanaryFacts({ v: 1, host, at: when, digest: tree, excerpt });
+	if (!facts) throw new Error("not a canary's facts");
+	await bounded(redis.set(updatesCanaryKey(pkg, at), JSON.stringify(facts), "PX", UPDATES_CANARY_TTL_MS));
+}
+
+export async function readCanaryFacts(redis, pkg, at) {
+	try {
+		const value = await bounded(redis.get(updatesCanaryKey(pkg, at)));
+		return typeof value === "string" ? parseCanaryFacts(value) : null;
+	} catch {
+		return null;
+	}
+}