@makerstufferupper/flypi 0.0.0-stage → 0.1.2

package/scripts/flypi.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * `flypi start | stop | restart | status | logs` — the daemon CLI (docs/architecture.md Phase 4.5).
+ *
+ * No dependency and no service manager needed, and no port arbitration either: the daemon picks its own
+ * port, then says so in `.flypi/daemon.json` (0600 — it carries the token). The CLI's job is to start it
+ * detached, wait until `/healthz` answers, and report the URL you would otherwise have to dig out of a log.
+ *
+ *   node scripts/flypi.mjs start [--foreground]   # or: npm run flypi -- start
+ *   node scripts/flypi.mjs status | stop | restart | logs [-n 50] [-f]
+ *   node scripts/flypi.mjs update [--check]        # the newest published flypi (docs/architecture.md Phase 7)
+ *
+ * `--root DIR` (or FLYPI_ROOT) picks which `.flypi/` the CLI owns; in a checkout it defaults to the cwd,
+ * and the installed `bin/flypi.mjs` sets FLYPI_ROOT to the home directory before importing this.
+ */
+import { mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const argv = process.argv.slice(2);
+// `--root DIR` is accepted anywhere in the line and taken out before the subcommand is read: children are
+// handed `--root` explicitly, so a subcommand like `secret` must not see it twice.
+const rootAt = argv.indexOf("--root");
+const rootFlag = rootAt === -1 ? undefined : argv.splice(rootAt, 2)[1];
+const root = resolve(rootFlag ?? process.env.FLYPI_ROOT ?? process.cwd());
+// The checkout the script lives in, which is where `tsx` and the app's imports resolve from. `--root` is
+// how the daemon is told which `.flypi/` to own: they are not the same directory when the CLI is run with
+// FLYPI_ROOT from somewhere else.
+const checkout = resolve(fileURLToPath(import.meta.url), "..", "..");
+const serveDaemon = resolve(fileURLToPath(import.meta.url), "..", "serve-daemon.ts");
+const secretCli = resolve(fileURLToPath(import.meta.url), "..", "secret.ts");
+const updateCli = resolve(fileURLToPath(import.meta.url), "..", "update.ts");
+const infoPath = resolve(root, ".flypi", "daemon.json");
+const logPath = resolve(root, ".flypi", "daemon.log");
+/**
+ * The port and interface the last start was *named* with, kept next to the pid file and left there when the
+ * daemon stops. A clean stop removes the pid file, so without this a bare `flypi start` after `flypi stop`
+ * picks a new ephemeral port and invalidates the URL every bookmark and every published Docker port uses.
+ * No token in it, so no `0600`.
+ */
+const flagsPath = resolve(root, ".flypi", "daemon-flags.json");
+
+/**
+ * A pid file is only evidence if the process is still there; `kill(pid, 0)` asks without stopping it. That
+ * answer is not enough on its own: it succeeds on a zombie, and a container whose PID 1 does not reap
+ * (`docker run` without `--init`) leaves a killed daemon's entry in the process table for the life of the
+ * container — so `status` called it "running" and `start` called it "already running", forever, over a pid
+ * file the daemon never got to remove. Where `/proc` is readable the state says whether it is a process or a
+ * corpse; elsewhere (macOS, Windows) `kill(pid, 0)` is the only evidence there is, and launchd/Windows reap
+ * what they orphan, so a lingering zombie is not the case there.
+ */
+const alive = (pid) => {
+	try {
+		process.kill(pid, 0);
+	} catch {
+		return false;
+	}
+	try {
+		// `<pid> (comm) <state> …`, and `comm` can hold spaces and parentheses — hence the last `)`, not the first.
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		return stat.slice(stat.lastIndexOf(")") + 2)[0] !== "Z";
+	} catch {
+		return true;
+	}
+};
+
+/**
+ * Flags `flypi start` hands to the daemon. `--port`/`--host` because a detached daemon is otherwise
+ * unreachable by number or by interface: it picks an ephemeral port, and a published Docker port cannot
+ * reach the container's own loopback. `--embeddings none`/`--judge none` because they are the difference
+ * between a first run that downloads ~1 GB of ONNX models and one that comes up keyword-only in seconds.
+ *
+ * `carried` is the daemon that was just stopped, the stale pid file a crashed one left, or the flags file a
+ * previous start wrote. A bare `flypi restart` or a bare `flypi start` means "that daemon again", so the port
+ * and interface it was reached by carry over — forgetting them moves a container's daemon off its published
+ * port with nothing to explain the dead URL.
+ * The memory flags do not carry over: the settings file is the persistent place for those, and the flags
+ * are the one-off override of it.
+ */
+const flagValue = (name) => {
+	const i = argv.indexOf(name);
+	return i === -1 ? undefined : argv[i + 1];
+};
+const daemonFlags = (carried) => {
+	// A port named on this command line is a demand: a container's published port is useless on another
+	// number, so the daemon has to fail loudly rather than move. A port carried over from an earlier start
+	// is a preference, so `--port-may-move` lets it bind another one instead of dying on `EADDRINUSE`.
+	const named = flagValue("--port");
+	const port = named ?? carried?.port;
+	const host = flagValue("--host") ?? carried?.host;
+	return [
+		...(port === undefined ? [] : ["--port", String(port), ...(named === undefined ? ["--port-may-move"] : [])]),
+		...(host === undefined ? [] : ["--host", String(host)]),
+		...["--embeddings", "--judge"].flatMap((name) => (flagValue(name) ? [name, flagValue(name)] : [])),
+	];
+};
+
+const readJson = (file) => {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+};
+
+const readInfo = () => readJson(infoPath);
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+async function health(port) {
+	try {
+		const response = await fetch(`http://127.0.0.1:${port}/healthz`);
+		return response.ok ? await response.json() : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Echo what the daemon has written since it was spawned. A first run fetches ~1 GB of memory models before
+ * it is listening, and a silent wait is indistinguishable from a hang; `logFrom` is the log's size at spawn,
+ * so an earlier run's lines are not replayed.
+ */
+const echoLog = (from) => {
+	try {
+		const text = readFileSync(logPath, "utf8");
+		if (text.length > from) process.stdout.write(text.slice(from));
+		return text.length;
+	} catch {
+		return from;
+	}
+};
+
+// Generous, because the thing it waits on is a download: the models are ~1 GB on a machine that has never
+// run flypi. A child that exits is reported immediately, so this only ever costs time on a real hang.
+const STARTUP_TIMEOUT_MS = 15 * 60_000;
+async function waitForStartup(stalePid, died, logFrom, timeoutMs = STARTUP_TIMEOUT_MS) {
+	const until = Date.now() + timeoutMs;
+	let shown = logFrom;
+	while (Date.now() < until) {
+		shown = echoLog(shown);
+		const info = readInfo();
+		if (info && info.pid !== stalePid && alive(info.pid)) {
+			// The health page is the proof it is serving, not just spawned. Loading the memory models can
+			// take a moment, so this is a poll rather than one attempt.
+			const status = await health(info.port);
+			if (status) return { info, status };
+		}
+		// A child that has already exited is not going to answer: report the log now, do not make the user
+		// wait out the model-loading timeout to find out the process never started.
+		if (died() !== null) return null;
+		await sleep(200);
+	}
+	return null;
+}
+
+function report(info, status) {
+	console.log(`flypi: running (pid ${info.pid}) — root ${root}`);
+	console.log(`flypi: agent   http://${info.host}:${info.port}  (token ${info.token})`);
+	console.log(`flypi: memory  http://127.0.0.1:${info.memoryPort}/mcp`);
+	if (status) console.log(`flypi: started ${status.startedAt}, version ${status.version}, ${status.jobs} job(s) queued`);
+	// The daemon's own daily answer (src/daemon/update.ts) — `status` does not reach the network itself.
+	if (status?.updateAvailable) console.log(`flypi: ${status.updateAvailable} is available — \`flypi update\` installs it`);
+	if (status?.updateReady) console.log(`flypi: ${status.updateReady} is downloaded — it installs once the daemon has been idle`);
+}
+
+async function start({ foreground = false, previous } = {}) {
+	const existing = readInfo();
+	if (existing && alive(existing.pid)) {
+		report(existing, await health(existing.port));
+		console.log("flypi: already running — `flypi restart` to restart it");
+		return 0;
+	}
+	// A file left by a dead process would otherwise be mistaken for the daemon we are about to start.
+	if (existing) rmSync(infoPath, { force: true });
+	// Most recent word wins: the daemon being restarted, the stale pid file a crash left, then the flags a
+	// previous start named and nothing has removed since.
+	const carried = previous ?? existing ?? readJson(flagsPath);
+	const flags = daemonFlags(carried);
+	// The `.flypi/` directory is created here, not assumed: on a machine that has never run flypi, `--root`
+	// has no `.flypi/` in it yet, and neither the log nor the flags file would open.
+	mkdirSync(dirname(logPath), { recursive: true });
+	// Only a start that names them writes the file — an ephemeral port the daemon picked is not worth making
+	// sticky — and it merges, so naming just `--port` does not drop an `--host` that is still in force.
+	const namedFlags = { ...(flagValue("--port") ? { port: Number(flagValue("--port")) } : {}), ...(flagValue("--host") ? { host: flagValue("--host") } : {}) };
+	if (Object.keys(namedFlags).length > 0) writeFileSync(flagsPath, `${JSON.stringify({ ...readJson(flagsPath), ...namedFlags })}\n`);
+	if (foreground) {
+		const child = spawn(process.execPath, ["--import", "tsx", serveDaemon, "--root", root, ...flags], { cwd: checkout, stdio: "inherit" });
+		return new Promise((done) => child.on("exit", (code) => done(code ?? 0)));
+	}
+	// The log's directory is created above, not assumed.
+	const log = openSync(logPath, "a");
+	const logFrom = statSync(logPath).size;
+	const child = spawn(process.execPath, ["--import", "tsx", serveDaemon, "--root", root, ...flags], { cwd: checkout, detached: true, stdio: ["ignore", log, log] });
+	child.unref();
+	let exitCode = null;
+	child.once("exit", (code) => {
+		exitCode = code ?? 0;
+	});
+	console.log(`flypi: starting (pid ${child.pid}) — log: ${logPath}`);
+	const started = await waitForStartup(existing?.pid, () => exitCode, logFrom);
+	if (!started) {
+		const why = exitCode === null ? `no /healthz within ${Math.round(STARTUP_TIMEOUT_MS / 60_000)} minutes` : `it exited (code ${exitCode}) before it was listening`;
+		console.error(`flypi: ${why}. Last log lines:\n${tail(logPath, 20)}`);
+		return 1;
+	}
+	report(started.info, started.status);
+	return 0;
+}
+
+const tail = (file, lines) => {
+	try {
+		return readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-lines).join("\n");
+	} catch {
+		return "(no log yet)";
+	}
+};
+
+async function stop() {
+	const info = readInfo();
+	if (!info || !alive(info.pid)) {
+		console.log("flypi: not running");
+		return 0;
+	}
+	// SIGTERM, and the daemon's own shutdown: stop the loop, close the sockets, remove its pid file. A
+	// turn that was running is left as `interrupted` for the next start to report — never re-run.
+	process.kill(info.pid, "SIGTERM");
+	// The proof it stopped is the record it removes on the way out, not the process table: `kill(pid, 0)`
+	// succeeds on a zombie, and a container whose PID 1 does not reap (`docker run` without `--init`) leaves a
+	// cleanly-shut-down daemon sitting there — so the old check called a clean stop a failure.
+	const stopped = () => !alive(info.pid) || readInfo() === null;
+	for (let waited = 0; waited < 10_000 && !stopped(); waited += 100) await sleep(100);
+	console.log(stopped() ? "flypi: stopped" : `flypi: pid ${info.pid} did not stop — kill it if you must`);
+	return 0;
+}
+
+async function status() {
+	const info = readInfo();
+	if (!info) {
+		console.log(`flypi: no ${infoPath} — never started, or it stopped and cleaned up after itself`);
+		return 1;
+	}
+	if (!alive(info.pid)) {
+		console.log(`flypi: not running (pid ${info.pid} is gone; it died or was killed) — the file is left so you can see where`);
+		return 1;
+	}
+	report(info, await health(info.port));
+	return 0;
+}
+
+function logs({ lines = 40, follow = false } = {}) {
+	console.log(tail(logPath, lines));
+	if (!follow) return 0;
+	const child = spawn("tail", ["-f", logPath], { stdio: "inherit" });
+	return new Promise((done) => child.on("exit", (code) => done(code ?? 0)));
+}
+
+/**
+ * `flypi secret …` (docs/secrets.md Phase 5.5). Run as a child for the same reason `start --foreground`
+ * is: the app is TypeScript, and this script is plain node so the daemon CLI works without a build.
+ * stdio is inherited so a value can be piped in and never appear in the argument list.
+ */
+async function secret(args) {
+	const child = spawn(process.execPath, ["--import", "tsx", secretCli, "--root", root, ...args], { cwd: checkout, stdio: "inherit" });
+	return new Promise((done) => child.on("exit", (code) => done(code ?? 0)));
+}
+
+/**
+ * `flypi update` (docs/architecture.md Phase 7): the newest published flypi, installed. Run as a child for
+ * the same reason `secret` is — the app is TypeScript and this script is plain node. The child stops and
+ * starts the daemon through this CLI, so the port/interface carry-over stays in one place.
+ */
+async function update(args) {
+	const child = spawn(process.execPath, ["--import", "tsx", updateCli, "--root", root, ...args], { cwd: checkout, stdio: "inherit" });
+	return new Promise((done) => child.on("exit", (code) => done(code ?? 0)));
+}
+
+const command = argv[0] ?? "status";
+const flagNumber = (name) => {
+	const i = argv.indexOf(name);
+	return i === -1 ? undefined : Number(argv[i + 1]);
+};
+const result = await {
+	start: () => start({ foreground: argv.includes("--foreground") }),
+	stop,
+	restart: async () => {
+		// Read the pid file before stopping: the daemon removes it on the way out, and the port and interface
+		// it was reached by are what a bare `flypi restart` has to reuse.
+		const previous = readInfo();
+		await stop();
+		return start({ foreground: argv.includes("--foreground"), previous });
+	},
+	status,
+	logs: () => logs({ ...(flagNumber("-n") ? { lines: flagNumber("-n") } : {}), follow: argv.includes("-f") || argv.includes("--follow") }),
+	secret: () => secret(argv.slice(1)),
+	update: () => update(argv.slice(1)),
+}[command]?.();
+if (result === undefined) {
+	console.log("usage: flypi [--root DIR] start [--foreground] [--port N] [--host H] [--embeddings none] [--judge none] | stop | restart | status | logs [-n N] [-f] | update [--check] | secret …");
+	process.exit(2);
+}
+process.exit(result);

package/scripts/probe-turn-boundary.ts

@@ -0,0 +1,97 @@
+/**
+ * C1's instrument (docs/prompt-cache.md): one real conversation, two turns, on a real route. A turn boundary
+ * is where the prompt cache is allowed to break (Phase 4.7), and `npm run probe` runs one turn, so it never
+ * measures that. This prints what the provider reported per model call and per turn — the same accounting
+ * `src/memory/recall.ts` writes into the `turns` row — plus the size of the block each turn injected and the
+ * session prompt it carries.
+ *
+ *   npm run probe:turn -- local/llama_a
+ *
+ * Needs the memory MCP service up and FLYPI_MEMORY_TOKEN set, or recall degrades to the short "unreachable"
+ * note and nothing is persisted — which since C2 means the boundary is clean for the wrong reason, so a run
+ * without the token measures nothing about the block.
+ *
+ * What a healthy run looks like since C2 (docs/prompt-cache.md): the block's message appears once, after the
+ * turn that retrieved it, with the same hash in every later request, and the first call of turn 2 re-pays only the
+ * new user message (18–19 tokens on the routes configured here) where C1 measured thousands.
+ *
+ * `FLYPI_CACHE_PROBE=1` adds the request half of the picture: one line per model request, and one per message
+ * inside it, hashed (src/shared/cache-probe.ts). Two runs of the same command then answer the question the
+ * usage numbers cannot on their own — the 0-vs-1462 at a boundary is either the request bytes changing
+ * (diff shows where) or the route dropping a prefix it was given (diff is empty).
+ *
+ * `--no-memory` runs the same two turns with no memory server configured, which is C1's control: nothing
+ * transient is injected, so the prefix is byte-identical across the boundary and whatever the route still
+ * re-pays is its own forgetting, not the block's. `probe:boundary` prices the block case from the
+ * conversations that really ran.
+ */
+import { createHash } from "node:crypto";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { flypiPaths } from "../src/agent/paths.ts";
+import { createFlypiSession } from "../src/agent/runtime.ts";
+import { cacheProbeEnabled, cacheProbeLines } from "../src/shared/cache-probe.ts";
+import { addUsage, emptyUsage, usageOf } from "../src/shared/transcript.ts";
+
+const PROMPTS = ["List the files in the current directory.", "How many of those are markdown files?"];
+const args = process.argv.slice(2);
+const control = args.includes("--no-memory");
+const modelRef = args.find((arg) => !arg.startsWith("--"));
+const probing = cacheProbeEnabled();
+let blockChars = 0;
+let requests = 0;
+
+const paths = flypiPaths(process.cwd());
+if (control) console.log("memory: off — no recalled block, no memory instruction in the prompt (C1's control)");
+const modelRuntime = await ModelRuntime.create({ authPath: paths.authPath, modelsPath: paths.modelsPath });
+const model = modelRef ? modelRuntime.getModel(modelRef.slice(0, modelRef.indexOf("/")), modelRef.slice(modelRef.indexOf("/") + 1)) : undefined;
+if (modelRef && !model) throw new Error(`no such model: ${modelRef}`);
+const { session } = await createFlypiSession({
+	root: paths.root,
+	tools: ["read", "bash"],
+	// The control takes the memory server out of *this session's* config rather than out of the file: the
+	// same "no memory server configured" the app gets when mcp.json is absent, and nothing on disk changes,
+	// so a SIGKILL or a second overlapping run cannot leave the real config disabled. `blockChars=0` in the
+	// output below is the proof the control really ran.
+	...(control ? { mcpConfig: { servers: [], errors: [] } } : {}),
+	...(model ? { model } : {}),
+	onMemoryBlock: (block) => {
+		blockChars = block.length;
+	},
+});
+
+// pi's own seam for looking at a request without changing it: `onPayload` is called with the body the
+// provider is about to get, and returning undefined keeps it. This is the only view of the bytes a prefix
+// cache actually keys on — pi's internal context still carries timestamps and other fields the adapter drops.
+if (probing) {
+	session.agent.onPayload = (payload) => {
+		requests += 1;
+		console.log([`request ${requests}`, ...cacheProbeLines(payload)].join("\n"));
+	};
+	console.log(`FLYPI_CACHE_PROBE=1: hashing every request; diff two runs to see what the route could not reuse`);
+}
+
+let turn = 0;
+for (const prompt of PROMPTS) {
+	turn += 1;
+	const before = session.messages.length;
+	blockChars = 0;
+	const sys = session.systemPrompt ?? "";
+	console.log(`turn ${turn} systemPrompt chars=${sys.length} sha=${createHash("sha256").update(sys).digest("hex").slice(0, 12)}`);
+	await session.prompt(prompt);
+	let total = emptyUsage();
+	let calls = 0;
+	for (const message of session.messages.slice(before)) {
+		const usage = usageOf((message as { usage?: unknown })?.usage);
+		if (!usage) continue;
+		calls += 1;
+		total = addUsage(total, usage);
+		console.log(
+			`turn ${turn} call ${calls}  prompt=${usage.input + usage.cacheRead + usage.cacheWrite} in=${usage.input} out=${usage.output} cacheRead=${usage.cacheRead} cacheWrite=${usage.cacheWrite}`,
+		);
+	}
+	console.log(`turn ${turn} TOTAL    in=${total.input} out=${total.output} cacheRead=${total.cacheRead} cacheWrite=${total.cacheWrite} blockChars=${blockChars}`);
+}
+session.dispose();
+// shortcut: the MCP client keeps a socket open after the last turn, so the process would outlive its
+// output; exiting from the write callback is the smallest way to make this usable in a pipeline.
+process.stdout.write("done\n", () => process.exit(0));

package/scripts/probe.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Phase 0 gate: prove the pi runtime is isolated to .flypi/ and can complete a turn.
+ *
+ *   npm run probe                 # config check + one real turn ("list files in cwd")
+ *   npm run probe -- --no-turn    # config check only (offline / CI)
+ *   npm run probe -- --root DIR   # check a different checkout
+ *   npm run probe -- --model provider/id   # run that route instead of the settings default
+ *
+ * Exits 1 with a one-line message on any problem — never a stack trace.
+ * The session wiring itself lives in src/agent/runtime.ts, which the server shares.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { assertFlypiOwned, flypiPaths } from "../src/agent/paths.ts";
+import { createFlypiSession, FlypiConfigError, type FlypiModel } from "../src/agent/runtime.ts";
+import { addUsage, emptyUsage, usageOf } from "../src/shared/transcript.ts";
+
+function fail(message: string): never {
+	console.error(`flypi probe: ${message}`);
+	process.exit(1);
+}
+
+const argv = process.argv.slice(2);
+const flagValue = (name: string): string | undefined => {
+	const i = argv.indexOf(name);
+	return i === -1 ? undefined : argv[i + 1];
+};
+const root = resolve(flagValue("--root") ?? process.cwd());
+const noTurn = argv.includes("--no-turn");
+const modelRef = flagValue("--model");
+const paths = flypiPaths(root);
+
+try {
+	assertFlypiOwned(paths);
+} catch (error) {
+	fail((error as Error).message);
+}
+
+console.log(`config dir   ${paths.agentDir}`);
+console.log(`sessions     ${paths.sessionsDir}`);
+
+const modelRuntime = await ModelRuntime.create({ authPath: paths.authPath, modelsPath: paths.modelsPath });
+let model: FlypiModel | undefined;
+if (modelRef) {
+	const slash = modelRef.indexOf("/");
+	if (slash < 1) fail(`--model wants "provider/id", got "${modelRef}"`);
+	model = modelRuntime.getModel(modelRef.slice(0, slash), modelRef.slice(slash + 1));
+	if (!model) fail(`model "${modelRef}" is not defined in ${paths.modelsPath}`);
+}
+
+let session;
+try {
+	({ session } = await createFlypiSession({ root, tools: ["read", "bash"], modelRuntime, model }));
+} catch (error) {
+	if (!(error instanceof FlypiConfigError)) throw error;
+	fail(error.message);
+}
+
+const tools = session.getActiveToolNames();
+const mcp = (
+	JSON.parse(readFileSync(paths.mcpPath, "utf8")) as { mcpServers?: Record<string, unknown> }
+).mcpServers ?? {};
+
+console.log(`model        ${session.model?.provider}/${session.model?.id}`);
+console.log(`thinking     ${session.thinkingLevel}`);
+console.log(`tools        ${tools.join(", ")}`);
+console.log(`session file ${session.sessionFile ?? "(none)"}`);
+console.log(`mcp servers  ${Object.keys(mcp).join(", ") || "(none configured)"} — connecting them is Phase 5`);
+
+if (!tools.includes("read") || !tools.includes("bash")) {
+	fail(`expected the read and bash tools to be active, got: ${tools.join(", ") || "(none)"}`);
+}
+
+if (!noTurn) {
+	const used = new Set<string>();
+	const unsubscribe = session.subscribe((event) => {
+		if (event.type === "tool_execution_start") used.add(event.toolName);
+	});
+	try {
+		await session.prompt("List the files in the current directory.");
+	} catch (error) {
+		fail(`the turn failed: ${(error as Error).message}`);
+	} finally {
+		unsubscribe();
+	}
+	const answer = session.getLastAssistantText();
+	console.log(`turn tools   ${[...used].join(", ") || "(none)"}`);
+	console.log(`turn answer  ${answer ?? "(none)"}`);
+	if (!answer) fail("the model returned no text");
+	if (used.size === 0) fail("the turn completed without calling any tool");
+	if (!session.sessionFile?.startsWith(paths.sessionsDir)) {
+		fail(`session file ${session.sessionFile} is not inside ${paths.sessionsDir}`);
+	}
+
+	// Phase 4.6 A0 (docs/prompt-cache.md): whether the provider's cache numbers reach the session at all.
+	// Printed, never asserted — a route that reports no cached tokens is the finding, not a probe failure.
+	let total = emptyUsage();
+	let calls = 0;
+	for (const message of session.messages) {
+		const usage = usageOf((message as { usage?: unknown }).usage);
+		if (!usage) continue;
+		calls++;
+		total = addUsage(total, usage);
+		console.log(
+			`call ${calls}      in=${usage.input} out=${usage.output} cacheRead=${usage.cacheRead} cacheWrite=${usage.cacheWrite}`,
+		);
+	}
+	console.log(`turn usage   in=${total.input} out=${total.output} cacheRead=${total.cacheRead} cacheWrite=${total.cacheWrite}`);
+	console.log(
+		`cache numbers ${
+			total.cacheRead || total.cacheWrite ? "arrive" : "none — this route reported no cached tokens to the session"
+		}`,
+	);
+}
+
+session.dispose();
+console.log("flypi probe: ok");

package/scripts/record-transcript.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Record `tests/fixtures/transcript-log` — the event sequence one real multi-tool turn produces
+ * (read → edit → read → bash → answer, with the real pi tools running against a throwaway
+ * checkout), plus the text render of it. The same fixture drives the `renderMessage()` golden,
+ * the UI component tests and `scripts/smoke.mjs`, which is why it is recorded once and committed.
+ *
+ *   npm run record
+ *
+ * Determinism: timestamps, the stub model's per-call nonce, and absolute paths under the temp
+ * root are stripped (tests/helpers/flypi-harness.ts `normalize`). What is left is what a client
+ * would actually render. The `node --test` output in the bash card carries durations, so
+ * re-recording can shift those numbers — that is the one thing that legitimately changes.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { harness, normalize } from "../tests/helpers/flypi-harness.ts";
+import { reduceEvents, renderTranscriptText } from "../src/shared/transcript.ts";
+import { FIX_THE_FAILING_TEST, fixTheFailingTest, writeFailingTestRepo } from "../tests/helpers/recorded-turn.ts";
+
+const FIXTURE_DIR = join(import.meta.dirname, "..", "tests", "fixtures", "transcript-log");
+
+const h = await harness(() => fixTheFailingTest(), { tools: ["read", "edit", "bash"] });
+const root = h.root;
+writeFailingTestRepo(root);
+try {
+	const conversation = await h.registry.create();
+	const events: unknown[] = [];
+	h.registry.attach(conversation.id, (_seq, event) => events.push(event));
+	await h.registry.prompt(conversation.id, FIX_THE_FAILING_TEST);
+	for (let attempt = 0; attempt < 500 && h.registry.get(conversation.id).session.isStreaming; attempt++) {
+		await new Promise((resolve) => setTimeout(resolve, 20));
+	}
+	// The session file must exist on disk before it is reported; a turn flushes it.
+	const sessionPath = h.registry.get(conversation.id).session.sessionFile;
+
+	const normalized = normalize(events, root) as Record<string, unknown>[];
+	mkdirSync(FIXTURE_DIR, { recursive: true });
+	writeFileSync(join(FIXTURE_DIR, "events.json"), `${JSON.stringify(normalized, null, 1)}\n`);
+	writeFileSync(
+		join(FIXTURE_DIR, "transcript.txt"),
+		renderTranscriptText(reduceEvents(normalized as never)),
+	);
+	writeFileSync(
+		join(FIXTURE_DIR, "README.md"),
+		`# transcript-log — a recorded multi-tool turn
+
+\`events.json\` is the pi session event stream from one real turn: a scripted stub model
+(tests/helpers/stub-model.ts) driving the real pi \`read\`, \`edit\` and \`bash\` tools against a
+throwaway checkout whose failing test is a numeric sort. Regenerate with \`npm run record\`.
+Timestamps, the stub nonce and temp-root paths are stripped; the bash card's test-runner
+durations are the one thing that can differ between recordings.
+
+Why it is committed: the same events drive the \`renderMessage()\` golden (\`transcript.txt\`),
+the UI component tests and \`scripts/smoke.mjs\`. If those disagree, one of them is wrong.
+Recorded against pi ${process.env.FLYPI_PI_VERSION ?? "1.0.4"}; session file \`${sessionPath ? "<root>/…jsonl" : "(none)"}\`.
+`,
+	);
+	console.log(`recorded ${normalized.length} events → tests/fixtures/transcript-log`);
+	console.log(readFileSync(join(FIXTURE_DIR, "transcript.txt"), "utf8"));
+} finally {
+	h.cleanup();
+}

package/scripts/reembed-memory.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Re-embed the memories the current index cannot represent. Run this after changing the embedding model
+ * (docs/decisions.md): the old vectors are not comparable to the new ones, so until they are rewritten
+ * those memories are reachable by keywords only.
+ *
+ *   npm run reembed:memory
+ *   npm run reembed:memory -- --db /path/to/flypi.db
+ */
+import { resolve } from "node:path";
+import { flypiPaths } from "../src/agent/paths.ts";
+import { memoryConfig } from "../src/memory/config.ts";
+import { openMemoryDb } from "../src/memory/db.ts";
+import { createEmbedder } from "../src/memory/embed.ts";
+import { MemoryStore } from "../src/memory/store.ts";
+
+const argv = process.argv.slice(2);
+const flagValue = (name: string): string | undefined => {
+	const i = argv.indexOf(name);
+	return i === -1 ? undefined : argv[i + 1];
+};
+
+const paths = flypiPaths(resolve(flagValue("--root") ?? process.cwd()));
+const config = memoryConfig(paths);
+if (flagValue("--embeddings")) config.embeddings.provider = flagValue("--embeddings") === "none" ? "none" : "transformers";
+
+const embedder = await createEmbedder(config.embeddings);
+if (embedder.error) console.log(`flypi reembed: ${embedder.error}`);
+
+const db = openMemoryDb(flagValue("--db") ?? paths.memoryDbPath);
+const store = new MemoryStore(db, embedder);
+const before = store.indexIdentity();
+console.log(`flypi reembed: ${before.rows} stored vectors, ${before.stale} not from ${before.expected?.model ?? "anything we can produce"}`);
+
+const { embedded, skipped } = await store.reembed("cli");
+console.log(`flypi reembed: rewrote ${embedded.length} ${embedded.length === 1 ? "memory" : "memories"}${embedded.length ? `: ${embedded.join(", ")}` : ""}`);
+for (const row of skipped) console.log(`flypi reembed: #${row.id} stays keyword-only: ${row.why}`);
+
+const after = store.indexIdentity();
+console.log(`flypi reembed: index now holds ${after.rows} vectors, ${after.stale} from another model`);
+db.close();

package/scripts/release.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * `npm run release [patch|minor|major] [--dry-run]` — the version bump *is* the release.
+ *
+ * package.json is the single version: the daemon reports it on `/healthz`, `flypi status` prints it, and the
+ * update check compares against it. So the increment is `npm version`, which bumps it, commits, and tags
+ * `v<version>` — and refuses to run on a dirty tree, which is the gate that makes a tag mean something.
+ * Then push the tag and publish; npm runs `prepublishOnly` (typecheck, tests, the UI build) on the way to
+ * the registry, so anything that gets published has passed the gates.
+ *
+ * `--dry-run` prints every step and runs none of them.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+const argv = process.argv.slice(2);
+const dryRun = argv.includes("--dry-run");
+const kind = argv.find((a) => ["patch", "minor", "major", "preminor", "premajor"].includes(a)) ?? "patch";
+
+/** `remote: true` marks the two steps that leave this machine, so the dry-run output says which is which. */
+function run(command, args, { remote = false } = {}) {
+	if (dryRun) {
+		console.log(`flypi release: would run${remote ? " [remote]" : ""}: ${command} ${args.join(" ")}`);
+		return 0;
+	}
+	const result = spawnSync(command, args, { stdio: "inherit" });
+	if (result.status !== 0) process.exit(result.status ?? 1);
+	return result.status;
+}
+
+run("npm", ["version", kind, "-m", "release %s"]);
+const version = JSON.parse(readFileSync("package.json", "utf8")).version;
+run("git", ["push", "--follow-tags"], { remote: true });
+run("npm", ["publish", "--access", "public"], { remote: true });
+console.log(dryRun ? `flypi release: dry run only - a ${kind} bump from ${version}; nothing committed, pushed or published` : `flypi release: ${version} published`);