@makerstufferupper/flypi 0.1.3 → 0.1.5

package/scripts/release-check.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * The release rehearsal (docs/release-checks.md). It runs the checks that have to pass before a version goes
+ * to the registry, and with `--published` the ones that prove what landed there is what was built.
+ *
+ *   node scripts/release-check.mjs                 # gates → pack → npm-install → image
+ *   node scripts/release-check.mjs --published     # registry + pushed image + run the published image
+ *   node scripts/release-check.mjs --skip-gates    # the docker half only
+ *   node scripts/release-check.mjs --keep          # leave the containers and volumes for a look
+ *
+ * It never publishes, pushes an image, or touches a container it did not create: everything it makes is named
+ * `flypi-check-*` on ports 8792/8793, so the serving `flypi` container on 8791 and its `flypi-data` volume are
+ * out of reach. Exit code is the number of failed checks.
+ */
+import { spawnSync } from "node:child_process";
+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const argv = process.argv.slice(2);
+const has = (flag) => argv.includes(flag);
+const valueOf = (flag) => {
+	const at = argv.indexOf(flag);
+	return at === -1 ? undefined : argv[at + 1];
+};
+const version = valueOf("--version") ?? JSON.parse(readFileSync("package.json", "utf8")).version;
+
+if (has("--help") || has("-h")) {
+	console.log(`flypi release rehearsal — docs/release-checks.md
+
+  npm run release:check                        gates → pack → npm-install → image
+  npm run release:check -- --published         the registry and the pushed image, after the publish
+  npm run release:check -- --skip-gates        the docker half only
+  npm run release:check -- --keep              leave the containers and volumes for a look
+  npm run release:check -- --version <v>       check a version other than package.json's
+  npm run release:check -- --help              this list (-h is the same)
+
+It never publishes or pushes, and only touches containers named flypi-check-*.`);
+	process.exit(0);
+}
+const IMAGE = "makerstufferupper/flypi";
+const TARBALL_URL = `https://registry.npmjs.org/@makerstufferupper/flypi/-/flypi-${version}.tgz`;
+
+let failures = 0;
+const ok = (name, detail) => console.log(`  ok    ${name}${detail ? ` — ${detail}` : ""}`);
+const bad = (name, detail) => {
+	failures++;
+	console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ""}`);
+};
+/** One check: run something, say whether it worked, keep going either way. */
+function check(name, command, args, options = {}) {
+	const result = spawnSync(command, args, { encoding: "utf8", ...options });
+	if (result.status === 0) {
+		ok(name, options.show && result.stdout ? result.stdout.trim().split("\n").at(-1) : undefined);
+		return result;
+	}
+	bad(name, `${command} ${args.join(" ")} exited ${result.status}${result.stderr ? `: ${result.stderr.trim().split("\n")[0]}` : ""}`);
+	return result;
+}
+
+const packDir = mkdtempSync(join(tmpdir(), "flypi-release-"));
+const created = { containers: [], volumes: [], images: [] };
+
+function docker(args, options = {}) {
+	return spawnSync("docker", args, { encoding: "utf8", ...options });
+}
+/** A container of our own, on a port and a volume nothing else is using. */
+function freshContainer(name, image, port, volume, command) {
+	docker(["rm", "-f", name]);
+	docker(["volume", "rm", volume]);
+	created.containers.push(name);
+	created.volumes.push(volume);
+	const run = docker(["run", "-d", "--name", name, "-p", `127.0.0.1:${port}:${port}`, "-v", `${volume}:/data`, "-e", "FLYPI_ROOT=/data", image, ...command]);
+	return run.status === 0 ? name : (bad(`docker run ${image}`, run.stderr.trim().split("\n")[0]), null);
+}
+/** Poll /healthz — the first start of a fresh state root is not instant. */
+async function health(port, seconds = 180) {
+	const deadline = Date.now() + seconds * 1000;
+	while (Date.now() < deadline) {
+		try {
+			const response = await fetch(`http://127.0.0.1:${port}/healthz`);
+			if (response.ok) return await response.json();
+		} catch {}
+		await new Promise((resolve) => setTimeout(resolve, 2000));
+	}
+	return null;
+}
+/** The three things every serving flypi owes: its own version, the pi it loaded, and a page. */
+async function assertServing(name, port, expectVersion) {
+	const body = await health(port);
+	if (!body) return bad(`${name}: /healthz never answered`, `port ${port}`);
+	body.version === expectVersion
+		? ok(`${name}: /healthz reports flypi ${body.version}`)
+		: bad(`${name}: /healthz version`, `expected ${expectVersion}, got ${body.version}`);
+	body.pi?.version
+		? ok(`${name}: it loaded pi ${body.pi.version}`, body.pi.pinned ? "pinned" : "not pinned")
+		: bad(`${name}: /healthz names no pi`, "Phase 8.1 — the loaded version must be reported");
+	const page = spawnSync("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", `http://127.0.0.1:${port}/`], { encoding: "utf8" });
+	page.stdout === "200" ? ok(`${name}: GET / is 200`) : bad(`${name}: GET /`, `got ${page.stdout || "no answer"}`);
+	return body;
+}
+/**
+ * The agent has a bash tool in here, so the tools a turn reaches for have to be present *and* working: git over
+ * https, git-lfs, curl, wget. Slim has none of them, and a git-lfs binary without its filters registered still
+ * checks in an LFS file's contents rather than a pointer — so this tracks one and reads the blob back out.
+ */
+function hasTools(name) {
+	const probe = docker([
+		"exec",
+		name,
+		"sh",
+		"-c",
+		"git --version >/dev/null && curl --version >/dev/null && wget --version >/dev/null" +
+			" && cd /tmp && rm -rf lfs-check && git init -q lfs-check && cd lfs-check && git lfs track '*.bin' >/dev/null" +
+			" && echo hello > a.bin && git -c user.email=flypi@example.com -c user.name=flypi add a.bin && git cat-file -p :a.bin",
+	]);
+	/git-lfs\.github\.com\/spec\/v1/.test(probe.stdout ?? "")
+		? ok(`${name}: it has git + git-lfs, curl and wget`)
+		: bad(`${name}: git + git-lfs, curl and wget`, `exit ${probe.status}: ${(probe.stderr || probe.stdout || "").trim().split("\n")[0]}`);
+}
+function cleanup() {
+	if (has("--keep")) return console.log(`\nkept: ${created.containers.join(", ")} · volumes ${created.volumes.join(", ")} · ${packDir}`);
+	for (const name of created.containers) docker(["rm", "-f", name]);
+	for (const volume of created.volumes) docker(["volume", "rm", volume]);
+	for (const image of created.images) docker(["rmi", image]);
+	rmSync(packDir, { recursive: true, force: true });
+}
+
+// ── stages ────────────────────────────────────────────────────────────────────────────────────────────────
+
+function gates() {
+	console.log(`gates — the suite this version would be published with`);
+	check("tsc --noEmit", "npm", ["run", "typecheck"]);
+	check("npm test", "npm", ["test"]);
+	check("npm run smoke", "npm", ["run", "smoke"]);
+	check("npm run probe:pi", "npm", ["run", "probe:pi"]);
+}
+
+function pack() {
+	console.log(`\npack — the artifact, before anything installs it`);
+	check("npm run build (dist/ui)", "npm", ["run", "build"]);
+	check(`npm pack`, "npm", ["pack", "--pack-destination", packDir]);
+	const tgz = `makerstufferupper-flypi-${version}.tgz`;
+	const packed = spawnSync("tar", ["xzOf", join(packDir, tgz), "package/package.json"], { encoding: "utf8" });
+	if (packed.status !== 0) return bad(`read ${tgz}`, "npm pack produced nothing readable");
+	const pkg = JSON.parse(packed.stdout);
+	pkg.version === version ? ok(`tarball version ${pkg.version}`) : bad("tarball version", `package.json says ${pkg.version}`);
+	const self = Object.keys(pkg.dependencies).filter((d) => d.includes("makerstufferupper"));
+	self.length ? bad("no self-dependency", `${self.join(", ")} — flypi must not depend on flypi`) : ok("no self-dependency in dependencies");
+	const listed = spawnSync("tar", ["tzf", join(packDir, tgz)], { encoding: "utf8" }).stdout.split("\n");
+	for (const file of ["dist/ui/index.html", "bin/flypi.mjs", "src/daemon/pi.ts"]) {
+		listed.includes(`package/${file}`) ? ok(`ships ${file}`) : bad(`ships ${file}`, "missing from the tarball — check package.json `files`");
+	}
+	const stray = listed.filter((f) => /package\/(\.scratch|\.flypi|node_modules|coverage)\//.test(f));
+	stray.length ? bad("no stray files", stray.slice(0, 3).join(", ")) : ok("nothing stray (.scratch, .flypi, node_modules, coverage)");
+	return tgz;
+}
+
+async function npmInstall(tgz) {
+	console.log(`\nnpm-install — the tarball in a clean container, the way \`npm install -g\` does it`);
+	const name = "flypi-check-npm";
+	const container = freshContainer(name, "node:24-slim", 8792, "flypi-check-npm-data", ["sleep", "7200"]);
+	if (!container) return;
+	if (docker(["cp", join(packDir, tgz), `${name}:/tmp/flypi.tgz`]).status !== 0) return bad("docker cp the tarball");
+	check("npm i -g /tmp/flypi.tgz", "docker", ["exec", name, "npm", "i", "-g", "--no-audit", "--no-fund", "/tmp/flypi.tgz"]);
+	const installed = docker(["exec", name, "node", "-e", `console.log(require("/usr/local/lib/node_modules/@makerstufferupper/flypi/package.json").version)`]);
+	installed.stdout?.trim() === version ? ok(`installed package reports ${version}`) : bad("installed package version", installed.stdout?.trim() || installed.stderr?.trim());
+	docker(["exec", "-d", name, "flypi", "start", "--foreground", "--port", "8792", "--host", "0.0.0.0", "--embeddings", "none", "--judge", "none"]);
+	await assertServing(name, 8792, version);
+}
+
+async function image(tgz) {
+	console.log(`\nimage — the published image's runtime shape, built from the same tarball`);
+	copyFileSync("docker/Dockerfile.local", join(packDir, "Dockerfile"));
+	const tag = `flypi-check:${version}`;
+	const built = docker(["build", "-q", "--build-arg", `FLYPI_TGZ=${tgz}`, "-t", tag, packDir]);
+	if (built.status !== 0) return bad("docker build", built.stderr.trim().split("\n").slice(-3).join(" "));
+	created.images.push(tag);
+	ok(`docker build ${tag}`);
+	const name = "flypi-check-image";
+	// Keyword-only memory: the image's own CMD would fetch ~900 MB of models into a volume that is deleted after.
+	const container = freshContainer(name, tag, 8793, "flypi-check-image-data", ["flypi", "start", "--foreground", "--port", "8793", "--host", "0.0.0.0", "--embeddings", "none", "--judge", "none"]);
+	if (!container) return;
+	await assertServing(name, 8793, version);
+	// The container must refuse to move pi in one sentence, not a stack trace (docs/pi-upgrades.md 8.3).
+	const refused = docker(["exec", name, "flypi", "pi", "use", "0.0.0"]);
+	/std|not writable|not the npm global/.test(`${refused.stdout}${refused.stderr}`) && refused.status !== 0
+		? ok("flypi pi use refuses in a container, in one sentence")
+		: bad("flypi pi use in a container", `exit ${refused.status}: ${(refused.stderr || refused.stdout).trim().split("\n")[0]}`);
+	const state = docker(["exec", name, "sh", "-c", "ls /data/.flypi/pi 2>&1"]);
+	/state/.test(state.stdout) ? bad("a refused switch leaves no pin behind", state.stdout.trim()) : ok("a refused switch left nothing behind");
+	hasTools(name);
+}
+
+async function published() {
+	console.log(`\npublished — that ${version} is really in the registry, and the image installs it`);
+	// The metadata and the tarball propagate at different speeds: `npm view` can answer minutes before the
+	// tarball URL stops 404-ing, which is what kills a pinned image build. Poll the URL, not the tag.
+	let code = "000";
+	for (let i = 0; i < 30 && code !== "200"; i++) {
+		code = spawnSync("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", TARBALL_URL], { encoding: "utf8" }).stdout;
+		if (code !== "200") await new Promise((resolve) => setTimeout(resolve, 10000));
+	}
+	code === "200" ? ok("the registry serves the tarball") : bad("the registry serves the tarball", `${code} after 5 min — ${TARBALL_URL}`);
+	const latest = spawnSync("npm", ["view", "@makerstufferupper/flypi", "version"], { encoding: "utf8" });
+	latest.stdout?.trim() === version ? ok(`npm's latest is ${version}`) : bad("npm's latest", `the registry answers ${latest.stdout?.trim() || "nothing"}`);
+
+	const inspect = docker(["buildx", "imagetools", "inspect", `${IMAGE}:${version}`]);
+	const platforms = ["linux/amd64", "linux/arm64"].filter((p) => inspect.stdout?.includes(p));
+	platforms.length === 2 ? ok("the pushed image carries both platforms") : bad("the pushed image's platforms", platforms.join(", ") || "the manifest was not readable");
+
+	const name = "flypi-check-published";
+	const container = freshContainer(name, `${IMAGE}:${version}`, 8793, "flypi-check-published-data", ["flypi", "start", "--foreground", "--port", "8793", "--host", "0.0.0.0", "--embeddings", "none", "--judge", "none"]);
+	if (!container) return;
+	await assertServing(name, 8793, version);
+	// A stale push is exactly what this stage exists to catch, and the tools come from the Dockerfile — so the
+	// image Docker Hub serves, not just the one built here, has to carry them.
+	hasTools(name);
+}
+
+// ── run ───────────────────────────────────────────────────────────────────────────────────────────────────
+
+try {
+	if (has("--published")) {
+		await published();
+	} else {
+		if (!has("--skip-gates")) gates();
+		const tgz = pack();
+		if (tgz) {
+			await npmInstall(tgz);
+			await image(tgz);
+		}
+	}
+} finally {
+	cleanup();
+}
+
+console.log(failures ? `\n${failures} check(s) failed` : `\nall checks passed for ${version}`);
+process.exit(failures ? 1 : 0);

package/scripts/serve.ts

@@ -19,6 +19,7 @@ import { SessionRegistry } from "../src/server/session-registry.ts";
 import { openRunStore } from "../src/server/run-store.ts";
 import { secretsApi } from "../src/server/secrets-api.ts";
 import { openSecretVault, type SecretStore } from "../src/secrets/vault.ts";
+import { loadedPi } from "../src/daemon/pi.ts";
 import { startFlypiServer } from "../src/server/index.ts";
 
 const argv = process.argv.slice(2);
@@ -63,6 +64,7 @@ const server = await startFlypiServer({
 	port: flagValue("--port") ? Number(flagValue("--port")) : undefined,
 	token: flagValue("--token") ?? process.env.FLYPI_TOKEN,
 	serverVersion: "dev",
+	pi: () => loadedPi(paths.root),
 	// An interrupted turn is a backend fact, so it is answered from the backend's store here too.
 	interruptedRun: (sessionFile) => runs.interruptedFor(sessionFile),
 	// Prod: the same server serves the built UI (docs/architecture.md: "Dev vs prod").

package/src/agent/packages.ts

@@ -24,6 +24,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { isNewer, published } from "../daemon/update.ts";
 import { FlypiConfigError } from "./runtime.ts";
 import type { FlypiPaths } from "./paths.ts";
 
@@ -31,6 +32,8 @@ import type { FlypiPaths } from "./paths.ts";
 export const PACKAGE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 /** The answer, next to flypi's own update stamp, so the panel reports it without reaching the network. */
 export const PACKAGE_CHECK_FILE = join(".flypi", "package-check.json");
+/** shortcut: the picker offers the 30 newest releases; going further back means editing the source by hand. */
+export const PUBLISHED_LIST_MAX = 30;
 
 /** One `packages` entry, as the panel shows it. */
 export interface PackageRow {
@@ -42,8 +45,16 @@ export interface PackageRow {
 	installed: boolean;
 	/** Where the code is: `.flypi/agent/npm/node_modules/<name>`, a checkout, or the local path. */
 	path: string;
+	/** The version its own `package.json` says it is — what a rollback has to name (docs/pi-upgrades.md). */
+	version?: string;
 	/** A newer release is published (npm) or the remote moved (git). Only from the daemon's stamp. */
 	update?: boolean;
+	/** The npm package an `npm:` source names, version stripped — what a pin is written onto. Absent for a git URL or a path. */
+	name?: string;
+	/** The published releases the daemon's stamp knows, oldest first — what "install this version" offers. */
+	versions?: string[];
+	/** The newest of those that is newer than what is installed. Absent when nothing newer is published. */
+	available?: string;
 }
 
 export interface PackageSnapshot {
@@ -65,15 +76,53 @@ export interface PackageCheck {
 	checkedAt: string;
 	/** The `packages` entries, exactly as settings.json holds them. */
 	updates: string[];
+	/** Published releases per npm source, oldest first — the rollback list the panel offers (docs/pi-upgrades.md). */
+	versions?: Record<string, string[]>;
 	error?: string;
 }
 
+/**
+ * The npm package an `npm:` source names, with any version or range it pins stripped: `npm:foo@^1.2` and
+ * `npm:foo` are both `foo`, and `npm:@scope/foo@1.0.0` is `@scope/foo`. Undefined for a git URL or a path,
+ * which have no registry to ask. This is also what tells a reader the source is pinned — a source that names
+ * a version is not `npm:<name>` any more.
+ */
+export function npmName(source: string): string | undefined {
+	if (!source.startsWith("npm:")) return undefined;
+	const name = source.slice("npm:".length).trim().replace(/@[^/@]*$/, "");
+	return name || undefined;
+}
+
 /** pi's package manager, on flypi's own agent dir, plus the settings file it writes through. */
 function packages(paths: FlypiPaths): { manager: DefaultPackageManager; settings: SettingsManager } {
 	const settings = SettingsManager.create(paths.root, paths.agentDir);
 	return { manager: new DefaultPackageManager({ cwd: paths.root, agentDir: paths.agentDir, settingsManager: settings }), settings };
 }
 
+/** The version an installed extension's own `package.json` claims. Null when it cannot be read. */
+function installedVersion(path: string): string | undefined {
+	try {
+		return (JSON.parse(readFileSync(join(path, "package.json"), "utf8")) as { version?: string }).version;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * `updates` in `.flypi/agent/settings.json`: may the daemon install an extension update by itself, on the
+ * same idle stretch it installs flypi with? Default true — the behaviour that predates the key. It is the
+ * path an incompatible change arrives by, so it is now something a user can turn off; pi itself has no
+ * equivalent and never updates unattended (docs/pi-upgrades.md).
+ */
+export function autoExtensions(paths: FlypiPaths): boolean {
+	try {
+		const settings = JSON.parse(readFileSync(paths.settingsPath, "utf8")) as { updates?: { autoExtensions?: unknown } };
+		return settings.updates?.autoExtensions !== false;
+	} catch {
+		return true;
+	}
+}
+
 /** What pi could not read or write, named by file — a settings.json it cannot parse is never silently "empty". */
 function settingsErrors(settings: SettingsManager): string[] {
 	return settings.drainErrors().map((failure) => `${failure.path ?? failure.scope}: ${failure.error.message}`);
@@ -84,13 +133,23 @@ export function readPackages(paths: FlypiPaths): PackageSnapshot {
 	const { manager, settings } = packages(paths);
 	const check = readPackageCheck(paths.root);
 	return {
-		packages: manager.listConfiguredPackages().map((entry) => ({
-			source: entry.source,
-			scope: entry.scope,
-			installed: entry.installedPath !== undefined,
-			path: entry.installedPath ?? "",
-			...(check?.updates.includes(entry.source) ? { update: true } : {}),
-		})),
+		packages: manager.listConfiguredPackages().map((entry) => {
+			const name = npmName(entry.source);
+			const version = entry.installedPath ? installedVersion(entry.installedPath) : undefined;
+			const versions = check?.versions?.[entry.source];
+			const available = versions?.filter((v) => !version || isNewer(version, v)).at(-1);
+			return {
+				source: entry.source,
+				scope: entry.scope,
+				installed: entry.installedPath !== undefined,
+				path: entry.installedPath ?? "",
+				...(version ? { version } : {}),
+				...(check?.updates.includes(entry.source) ? { update: true } : {}),
+				...(name ? { name } : {}),
+				...(versions?.length ? { versions } : {}),
+				...(available ? { available } : {}),
+			};
+		}),
 		...(check ? { checkedAt: check.checkedAt } : {}),
 		errors: settingsErrors(settings),
 	};
@@ -117,13 +176,47 @@ export async function applyPackageEdits(paths: FlypiPaths, edits: PackageEdits):
 }
 
 /**
- * Ask the registries and remotes which configured sources have something newer. An unreachable registry is
- * the answer, not a crash — the daemon asks this on a machine that may be offline.
+ * The published releases of each npm source, for the panel's "install this version" — the way back for an
+ * extension is pi's own pin form, and a pin has to name a version to name (docs/pi-upgrades.md). One
+ * registry document per npm source per day, on the same rhythm as the update check below.
+ *
+ * A source with nothing to offer is simply absent from the answer: a package the registry has never heard of
+ * (404), an offline box, and a git URL or a path all leave the row with no list rather than failing the check.
+ */
+export async function publishedVersions(paths: FlypiPaths, fetchImpl?: typeof fetch): Promise<Record<string, string[]>> {
+	const out: Record<string, string[]> = {};
+	for (const entry of packages(paths).manager.listConfiguredPackages()) {
+		const name = npmName(entry.source);
+		if (!name) continue;
+		try {
+			// The scoped form is `@scope%2Fname`; an unscoped name needs no escaping at all.
+			const response = await (fetchImpl ?? fetch)(`https://registry.npmjs.org/${name.replace("/", "%2F")}`, {
+				signal: AbortSignal.timeout(5_000),
+				headers: { accept: "application/json" },
+			});
+			if (!response.ok) continue;
+			const doc = (await response.json()) as { versions?: Record<string, unknown> };
+			// Released only, oldest first — the same rule flypi's own version ladder reads.
+			const list = published(doc.versions ?? {}).slice(-PUBLISHED_LIST_MAX);
+			if (list.length > 0) out[entry.source] = list;
+		} catch {
+			// Nothing to say: the row offers no version until a later check reaches the registry.
+		}
+	}
+	return out;
+}
+
+/**
+ * Ask the registries and remotes which configured sources have something newer, and what each npm source has
+ * ever published. An unreachable registry is the answer, not a crash — the daemon asks this on a machine that
+ * may be offline.
  */
-export async function checkPackageUpdates(paths: FlypiPaths): Promise<PackageCheck> {
+export async function checkPackageUpdates(paths: FlypiPaths, fetchImpl?: typeof fetch): Promise<PackageCheck> {
 	const { manager } = packages(paths);
 	try {
-		return { checkedAt: new Date().toISOString(), updates: (await manager.checkForAvailableUpdates()).map((entry) => entry.source) };
+		const updates = (await manager.checkForAvailableUpdates()).map((entry) => entry.source);
+		const versions = await publishedVersions(paths, fetchImpl);
+		return { checkedAt: new Date().toISOString(), updates, ...(Object.keys(versions).length > 0 ? { versions } : {}) };
 	} catch (error) {
 		return { checkedAt: new Date().toISOString(), updates: [], error: (error as Error).message };
 	}

package/src/agent/pi-compat.ts

@@ -0,0 +1,204 @@
+/**
+ * The surface of pi that flypi depends on, and a check that a candidate tree still offers it
+ * (docs/pi-upgrades.md Phase 8.2, risk 14).
+ *
+ * This is a **pre-filter, not a gate**. It catches the dominant breakage class — a renamed or dropped export,
+ * a moved internal file, a raised Node floor — in about a second and without restarting anything. It cannot
+ * see the behavioural half of pi-api.md: pi 1.4.0 kept every export and changed the *shape* of the
+ * `before_agent_start` event, which no `typeof` check can find. Only `npm test` and `npm run smoke` catch
+ * that class, and they are the gate.
+ *
+ * The list is **generated from the source, never maintained by hand**: `tests/scripts/pi-compat.test.ts`
+ * greps every `from "@earendil-works/…"` in `src/ scripts/ tests/ ui/` and fails when the two disagree. A
+ * hand-kept list that drifts reports a clean pass, which is worse than no list.
+ *
+ * Three specifiers, not one (docs/pi-upgrades.md C3): `pi-coding-agent` is the bulk, `pi-mcp` is imported by
+ * the memory smoke script and three tests without being a declared dependency of flypi, and
+ * `pi-ai/providers/faux` is the stub every model-touching test runs on. A probe that checked only
+ * `pi-coding-agent` would report a clean pass while the whole suite was broken.
+ */
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** One specifier flypi imports from, and what it takes from it. */
+export interface PiImport {
+	/** The bare specifier, exactly as the source writes it. */
+	specifier: string;
+	/** Names with a runtime presence. flypi calls every one of them, so each must stay a function. */
+	values: string[];
+	/** Type-only names: no runtime check is possible, so the entry's `.d.ts` is checked instead. */
+	types: string[];
+}
+
+export interface PiDeepImport {
+	/** The package whose internals flypi reaches into by path. */
+	specifier: string;
+	/** The file inside it, as `src/agent/pi-mcp.ts` joins it onto `getPackageDir()`. */
+	path: string;
+}
+
+/** What flypi imports from pi. Kept honest by `tests/scripts/pi-compat.test.ts`, not by anyone's memory. */
+export const PI_COMPAT: { imports: PiImport[]; deep: PiDeepImport[] } = {
+	imports: [
+		{
+			specifier: "@earendil-works/pi-coding-agent",
+			values: [
+				"createAgentSession",
+				"DefaultResourceLoader",
+				"DefaultPackageManager",
+				"SettingsManager",
+				"SessionManager",
+				"ModelRuntime",
+				"getPackageDir",
+				"createMcpExtension",
+				"createToolSearchExtension",
+			],
+			types: [
+				"AgentSessionEvent",
+				"CreateAgentSessionOptions",
+				"CustomMessageEntry",
+				"ExtensionAPI",
+				"ExtensionContext",
+				"ExtensionFactory",
+				"ExtensionUIContext",
+				"ExtensionUIDialogOptions",
+				"LoadedMcpConfig",
+				"McpExtensionOptions",
+				"McpServerConfig",
+				"McpServerEntry",
+				"SessionEntry",
+			],
+		},
+		{ specifier: "@earendil-works/pi-mcp", values: ["McpClient", "StreamableHttpTransport"], types: [] },
+		{
+			specifier: "@earendil-works/pi-ai/providers/faux",
+			values: ["fauxAssistantMessage", "fauxProvider", "fauxText", "fauxThinking", "fauxToolCall"],
+			types: ["FauxProviderHandle", "FauxResponseStep"],
+		},
+	],
+	// Reached by path because the entry does not export them and its `exports` map hides the types
+	// (src/agent/pi-mcp.ts). A moved internal file breaks flypi while every export still passes.
+	deep: [
+		{ specifier: "@earendil-works/pi-coding-agent", path: "dist/extensions/mcp/runtime.js" },
+		{ specifier: "@earendil-works/pi-coding-agent", path: "dist/core/auth-storage.js" },
+		{ specifier: "@earendil-works/pi-coding-agent", path: "dist/core/resolve-config-value.js" },
+	],
+};
+
+/** `engines.node: ">=22.19.0"` against the Node that would run it. Numeric parts, left to right. */
+function nodeSatisfied(range: string, version: string): boolean {
+	const min = /(\d+)\.(\d+)\.(\d+)/.exec(range);
+	if (!min) return true;
+	const parts = version.split(".").map(Number);
+	for (let i = 1; i <= 3; i++) {
+		const diff = Math.sign((parts[i - 1] ?? 0) - Number(min[i]));
+		if (diff) return diff > 0;
+	}
+	return true;
+}
+
+/** Walk up from a resolved file to the package that owns it — `dist/index.js` is not the package root. */
+function packageRoot(fromFile: string, name: string): string | null {
+	let dir = dirname(fromFile);
+	while (dir !== dirname(dir)) {
+		try {
+			if ((JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { name?: string }).name === name) return dir;
+		} catch {
+			/* keep walking */
+		}
+		dir = dirname(dir);
+	}
+	return null;
+}
+
+/**
+ * Resolve specifiers **from inside the candidate tree**. `import.meta.resolve(spec, parentURL)` cannot do
+ * it — Node 24 ignores the parent argument and resolves from the calling module, which would have the probe
+ * check flypi's own pi and report a clean pass for a candidate that is not even there. A module written at
+ * the candidate's root resolves from its own location, which is the tree being probed.
+ */
+async function resolverFor(root: string): Promise<(specifier: string) => string | null> {
+	const helper = join(root, ".flypi-probe-resolver.mjs");
+	writeFileSync(helper, "export const resolveFrom = (specifier) => import.meta.resolve(specifier);\n");
+	let resolveFrom: (specifier: string) => string;
+	try {
+		({ resolveFrom } = await import(pathToFileURL(helper).href));
+	} finally {
+		rmSync(helper, { force: true });
+	}
+	return (specifier) => {
+		try {
+			const url = resolveFrom(specifier);
+			return fileURLToPath(url).startsWith(join(root, "node_modules") + "/") ? url : null;
+		} catch {
+			return null;
+		}
+	};
+}
+
+/**
+ * What a candidate tree is missing — one sentence per problem, empty when it looks usable. A complete tree
+ * resolves its own third-party dependencies, so the probe asks the candidate rather than flypi.
+ */
+export async function checkPiCompat(candidateRoot: string): Promise<string[]> {
+	const failures: string[] = [];
+	let root: string;
+	try {
+		root = realpathSync(candidateRoot);
+	} catch {
+		return [`${candidateRoot} is not a directory — nothing to probe`];
+	}
+	if (!existsSync(join(root, "node_modules", "@earendil-works"))) return [`${candidateRoot} has no @earendil-works in its node_modules — that is not a candidate pi tree`];
+	const resolveFrom = await resolverFor(root);
+
+	for (const entry of PI_COMPAT.imports) {
+		const url = resolveFrom(entry.specifier);
+		if (!url) {
+			failures.push(`${entry.specifier}: does not resolve from inside ${candidateRoot}`);
+			continue;
+		}
+		let mod: Record<string, unknown>;
+		try {
+			// The query busts the ESM module cache: asked twice in one process, the probe has to look at the
+			// tree again rather than at what the first look left loaded.
+			mod = (await import(`${url}?pi-probe=1`)) as Record<string, unknown>;
+		} catch (error) {
+			failures.push(`${entry.specifier}: importing it threw — ${(error as Error).message}`);
+			continue;
+		}
+		for (const name of entry.values) {
+			if (typeof mod[name] !== "function") failures.push(`${entry.specifier}: ${name} is ${typeof mod[name]}, and flypi calls it as a function`);
+		}
+		if (entry.types.length === 0) continue;
+		// The entry's own declaration file: `dist/index.d.ts` for the package entry,
+		// `dist/providers/faux.d.ts` for the subpath. Every type flypi imports is re-exported there by name.
+		const declaration = fileURLToPath(url.replace(/\.js$/, ".d.ts"));
+		if (!existsSync(declaration)) {
+			failures.push(`${entry.specifier}: no ${declaration.slice(declaration.lastIndexOf("/") + 1)} beside the entry, so its type exports cannot be checked`);
+			continue;
+		}
+		const text = readFileSync(declaration, "utf8");
+		for (const name of entry.types) {
+			if (!new RegExp(`\\b${name}\\b`).test(text)) failures.push(`${entry.specifier}: the type ${name} is no longer re-exported from the entry`);
+		}
+	}
+
+	for (const deep of PI_COMPAT.deep) {
+		const url = resolveFrom(deep.specifier);
+		const owner = url ? packageRoot(fileURLToPath(url), deep.specifier) : null;
+		const file = owner ? join(owner, deep.path) : "";
+		if (!url || !owner || !existsSync(file)) failures.push(`${deep.specifier}: ${deep.path} is not there, and flypi imports it by path`);
+	}
+
+	// The Node floor: a candidate that needs a newer Node than the daemon runs on fails at import, which is
+	// the failure that leaves no web UI to click rollback on (docs/risks.md risk 13).
+	const entry = resolveFrom("@earendil-works/pi-coding-agent");
+	if (entry) {
+		const packageJson = join(packageRoot(fileURLToPath(entry), "@earendil-works/pi-coding-agent") ?? "", "package.json");
+		const engines = existsSync(packageJson) ? (JSON.parse(readFileSync(packageJson, "utf8")) as { engines?: { node?: string } }).engines?.node : undefined;
+		if (engines && !nodeSatisfied(engines, process.versions.node)) failures.push(`this pi needs Node ${engines}; this process is ${process.versions.node}`);
+	}
+
+	return failures;
+}