@makerstufferupper/flypi 0.0.0-stage → 0.1.3

package/scripts/smoke-secrets.mjs

@@ -0,0 +1,153 @@
+/**
+ * Phase 5.5's gate in one command (docs/secrets.md, docs/testing.md): the vault in the memory file, the CLI
+ * as a second process while a writer holds the database, redaction at the boundary where text is stored, the
+ * `!flypi secret print NAME` reference form, and a key rotation with the re-encrypt job that finishes it.
+ *
+ * It is a driver, not a test: the assertions live in tests/secrets/*. What it adds is that these are real
+ * processes and a real file — the two things a unit test can only imitate are a second process reading while
+ * the daemon writes, and the bytes on disk that a backup would carry.
+ *
+ * Run: npm run smoke:secrets
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { flypiPaths } from "../src/agent/paths.ts";
+import { openMemoryDb } from "../src/memory/db.ts";
+import { MemoryStore } from "../src/memory/store.ts";
+import { createEmbedder } from "../src/memory/embed.ts";
+import { memoryConfig } from "../src/memory/config.ts";
+import { secretReferences } from "../src/secrets/config.ts";
+import { openSecretVault } from "../src/secrets/vault.ts";
+import { schemaVersion } from "../src/shared/sqlite.ts";
+
+// The checkout this script lives in — where `tsx` and the app's imports resolve from, which is not the
+// temp root the smoke runs against (same reason scripts/flypi.mjs has it).
+const checkout = resolve(fileURLToPath(import.meta.url), "..", "..");
+
+const ok = (line) => console.log(`ok: ${line}`);
+const fail = (line) => {
+	console.error(`FAIL: ${line}`);
+	process.exit(1);
+};
+
+const root = mkdtempSync(join(tmpdir(), "flypi-smoke-secrets-"));
+const paths = flypiPaths(root);
+const TOKEN = "ghp_Smoke1111111111111111AAAAAAAA";
+
+// 1. The writer: the same database the memory store uses, opened the way the daemon opens it.
+const db = openMemoryDb(paths.memoryDbPath);
+const vault = openSecretVault(paths, { db, write: true });
+ok(`vault in the memory file — ${paths.memoryDbPath} at schema v${schemaVersion(db)}, one file for memories and secrets`);
+
+// 2. The CLI as another process, value on stdin so it never appears in the process list, while this process
+// still holds the write handle. This is the everyday case: the daemon is running and someone types a command.
+const cli = (args, input) => {
+	const run = spawnSync(process.execPath, ["--import", "tsx", join(checkout, "scripts", "secret.ts"), "--root", root, ...args], {
+		cwd: checkout,
+		encoding: "utf8",
+		...(input === undefined ? {} : { input }),
+	});
+	return { code: run.status ?? 1, out: run.stdout ?? "", err: run.stderr ?? "" };
+};
+const stored = cli(["put", "github_token", "--kind", "password", "--meta", "purpose=smoke"], TOKEN);
+if (stored.code !== 0) fail(`secret put failed: ${stored.err || stored.out}`);
+const printed = cli(["print", "github_token"]);
+// pi trims a `!command`'s stdout (resolve-config-value.js), so a trailing newline is what a config file wants.
+if (printed.out.trim() !== TOKEN) fail(`a second process did not read the value back: ${JSON.stringify(printed.out)}`);
+ok(`second process reads while the writer holds the file — print answered ${TOKEN.slice(0, 4)}…${TOKEN.slice(-4)} with the daemon's writer busy (exit ${printed.code})`);
+
+const listed = cli(["list"]);
+if (!listed.out.includes("ghp…AAAA") || listed.out.includes(TOKEN)) fail(`list leaked a value or lost its mask:\n${listed.out}`);
+const described = cli(["get", "github_token"]);
+if (described.code !== 0 || !described.out.includes("purpose=smoke") || described.out.includes(TOKEN)) fail(`get did not describe the row without the value:\n${described.out}`);
+ok("list and get answer with masks — no plaintext on either path");
+
+// 3. The file itself. A backup of this database must not carry the credential in the clear.
+for (const file of [paths.memoryDbPath, `${paths.memoryDbPath}-wal`]) {
+	if (existsSync(file) && readFileSync(file).includes(TOKEN)) fail(`${file} contains the plaintext`);
+}
+const row = db.prepare("SELECT name, mask, length(value_cipher) AS bytes, length(value_nonce) AS nonce, length(value_tag) AS tag, fingerprint, key_version FROM secrets WHERE name = 'github_token'").get();
+if (row.bytes === 0 || row.nonce !== 12 || row.tag !== 16 || !/^[0-9a-f]{64}$/.test(row.fingerprint) || row.key_version !== 1) {
+	fail(`the row is not sealed the way the design says: ${JSON.stringify(row)}`);
+}
+ok(`bytes on disk are ciphertext — ${row.bytes} B cipher, ${row.nonce} B nonce, ${row.tag} B tag, key v${row.key_version}, and the file does not contain the value`);
+
+// 4. The redaction boundary, at the place it matters: text being stored. A memory and a turn's tool calls go
+// through the same function the transcript hooks call (src/memory/store.ts).
+const embeddings = memoryConfig(paths).embeddings;
+embeddings.provider = "none";
+const store = new MemoryStore(db, await createEmbedder(embeddings));
+const remembered = await store.addMemory({
+	kind: "smoke",
+	body: `the github token is ${TOKEN} — do not paste it in a wiki`,
+	tags: ["smoke"],
+	origin_class: "agent",
+	session_kind: "interactive",
+	actor: "smoke",
+});
+const storedBody = store.memory(remembered.id).body;
+if (storedBody.includes(TOKEN)) fail("a memory body kept the secret in the clear");
+if (!storedBody.includes("[secret:github_token]")) fail(`a memory body did not name what it hid: ${storedBody}`);
+// A turn row belongs to a conversation the memory DB knows (`turns.conversation_id` is a foreign key), so the
+// row exists before the turn is recorded — the same order the server keeps them in (src/memory/store.ts).
+db.prepare("INSERT INTO conversations (id, cwd, pi_session_file, created_at) VALUES ('smoke-conv', ?, '/tmp/smoke.jsonl', ?)").run(paths.root, new Date().toISOString());
+store.recordTurn("smoke-conv", {
+	userText: `look up ${TOKEN}`,
+	assistantText: `found it: ${TOKEN}`,
+	toolCalls: [{ name: "bash", arguments: { command: `gh api -H "Authorization: Bearer ${TOKEN}"` } }],
+});
+const turn = db.prepare("SELECT user_text, assistant_text, tool_calls_json FROM turns WHERE conversation_id = 'smoke-conv'").get();
+for (const column of [turn.user_text, turn.assistant_text, turn.tool_calls_json]) {
+	if (String(column).includes(TOKEN)) fail(`a turn column kept the secret: ${column}`);
+}
+ok(`redaction at the store — memory #${remembered.id} and the turn's tool calls both say [secret:github_token]`);
+
+// 5. A command that only takes a path, and the reference form pi's config files use.
+const pathOut = cli(["path", "github_token"]);
+const secretFile = pathOut.out.trim();
+if (statSync(secretFile).mode & 0o077 || !readFileSync(secretFile, "utf8").includes(TOKEN)) fail(`path did not write a 0400 file with the value: ${pathOut.out}`);
+// The agent dir is there only once something has been written into it; a config file is what creates it.
+mkdirSync(dirname(paths.mcpPath), { recursive: true });
+writeFileSync(paths.mcpPath, JSON.stringify({ mcpServers: { github: { url: "https://api.github.com/mcp", headers: { Authorization: "!flypi secret print github_token" } } } }, null, 2));
+const found = secretReferences(paths);
+if (found.length !== 1 || found[0].name !== "github_token" || !found[0].path.includes("headers.Authorization")) fail(`the reference in mcp.json was not found: ${JSON.stringify(found)}`);
+// Run that reference exactly as pi would run it. `flypi secret print` is the command a config file would hold.
+const viaFlypi = execFileSync(process.execPath, [join(checkout, "scripts", "flypi.mjs"), "secret", "print", "github_token"], { cwd: checkout, encoding: "utf8", env: { ...process.env, FLYPI_ROOT: root } });
+if (viaFlypi.trim() !== TOKEN) fail(`\`!flypi secret print github_token\` printed ${JSON.stringify(viaFlypi)}`);
+ok(`a config reference resolves — mcp.json at ${found[0].path} → \`flypi secret print github_token\` → the value; a path-only tool gets a 0400 file`);
+
+// 6. Key rotation: the old key keeps working, the drift is reported, and the job that fixes it runs here
+// because the daemon would have queued it.
+const before = vault.row("github_token");
+const rotated = vault.rotateKey("smoke");
+const drift = vault.keyDrift();
+// Rotating a key must not silently strand a row: the drift is visible and the job to fix it is already queued
+// (src/daemon/index.ts queues it at startup too, in case the process died between the two).
+if (drift.stale !== 1 || drift.current !== rotated.version || !drift.reencryptQueued) fail(`key rotation did not report the drift it caused: ${JSON.stringify(drift)}`);
+const stillOpens = vault.value("github_token", { actor: "smoke", action: "used" });
+if (stillOpens !== TOKEN) fail("a row under the old key stopped opening — a missing key must be loud, not wrong");
+const resealed = vault.reencrypt();
+const after = vault.row("github_token");
+if (resealed.rows !== 1 || after.key_version !== rotated.version) fail(`re-encrypt did not move the row: ${JSON.stringify(resealed)}`);
+if (vault.value("github_token", { actor: "smoke", action: "used" }) !== TOKEN) fail("the row stopped opening after re-encrypting");
+if (vault.keyDrift().stale !== 0) fail("the drift is still reported after the job ran");
+const audit = db.prepare("SELECT action, count(*) AS n FROM secret_audit WHERE secret_id = ? GROUP BY action ORDER BY action").all(before.id);
+ok(`key rotation — v${before.key_version} → v${rotated.version}, the old key kept opening until the job re-sealed ${resealed.rows} row(s) under v${after.key_version}, audit ${audit.map((a) => `${a.action}×${a.n}`).join(" ")}`);
+
+// 7. Deletion is a tombstone, and a tombstone is restorable without anyone holding the value.
+cli(["delete", "github_token"]);
+if (vault.row("github_token").status !== "deleted") fail("delete did not leave a tombstone");
+if (cli(["list"]).out.includes(TOKEN)) fail("the tombstone list leaked a value");
+cli(["undelete", "github_token"]);
+if (vault.row("github_token").status !== "active") fail("undelete did not bring the row back");
+ok("delete is a tombstone, and `undelete` finds it again — the value never had to be typed twice");
+
+db.close();
+vault.close();
+rmSync(root, { recursive: true, force: true });
+console.log(`\nthe checkout: ${root} (removed)`);
+console.log("  the same checks against a real store: flypi secret list; sqlite3 .flypi/memory/flypi.db 'select name, mask, key_version from secrets'");
+process.exit(0);

package/scripts/smoke.mjs

@@ -0,0 +1,59 @@
+/**
+ * The one command that answers "does end-to-end agent execution still work?" — docs/testing.md.
+ *
+ * It is a driver, not a test: the assertions live in the test files. What this adds is the two
+ * things a suite cannot show you, the recorded fixture rendered by the same mapper the UI uses
+ * (`tests/fixtures/transcript-log`, "if they disagree, one of them is wrong") and a real
+ * end-to-end turn through the server printed as the transcript a user would see.
+ *
+ * Run: npm run smoke
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { WebSocket } from "ws";
+import { startFlypiServer } from "../src/server/index.ts";
+import { reduceEvents, renderTranscriptText } from "../src/shared/transcript.ts";
+import { harness, toolTurn } from "../tests/helpers/flypi-harness.ts";
+
+const fixtureDir = resolve(import.meta.dirname, "../tests/fixtures/transcript-log");
+const events = JSON.parse(readFileSync(resolve(fixtureDir, "events.json"), "utf8"));
+const golden = readFileSync(resolve(fixtureDir, "transcript.txt"), "utf8");
+
+const rendered = renderTranscriptText(reduceEvents(events));
+// Byte for byte, the same comparison tests/shared/transcript.test.ts makes.
+if (rendered !== golden) {
+	console.error("FAIL: the shared mapper no longer renders the recorded fixture like the tests do.");
+	console.error(`rendered ${rendered.trimEnd().split("\n").length} lines, golden ${golden.trimEnd().split("\n").length} lines`);
+	process.exit(1);
+}
+console.log(`ok: fixture — ${events.length} events rendered as ${rendered.trimEnd().split("\n").length} lines`);
+
+// An end-to-end turn: scripted stub model → session → registry → WS server → shared mapper.
+const h = await harness(toolTurn());
+const server = await startFlypiServer({ registry: h.registry });
+const socket = new WebSocket(`${server.url}/?token=${encodeURIComponent(server.token)}`);
+const send = (command) => socket.send(JSON.stringify(command));
+
+await new Promise((opened) => socket.once("open", opened));
+const settled = new Promise((done, failed) => {
+	socket.on("message", (raw) => {
+		const frame = JSON.parse(String(raw));
+		if (frame.type === "error") return failed(new Error(`server said: ${frame.message}`));
+		if (frame.type === "result" && frame.requestId === "1") {
+			send({ type: "prompt", conversationId: frame.conversationId, text: "list the files" });
+			return;
+		}
+		if (frame.type === "event" && frame.event.type === "agent_settled") done(frame.conversationId);
+	});
+});
+send({ type: "newSession", requestId: "1" });
+const conversationId = await settled;
+
+const eventsOfTurn = h.registry.get(conversationId).session.messages;
+const answer = JSON.stringify(eventsOfTurn);
+console.log(`ok: end-to-end — ${eventsOfTurn.length} messages, the model's answer reached the session: ${/listed the files/.test(answer)}`);
+console.log(renderTranscriptText(reduceEvents(eventsOfTurn.map((message) => ({ type: "message_end", message })))).split("\n").slice(0, 6).join("\n"));
+socket.close();
+await server.close();
+h.cleanup();
+process.exit(/listed the files/.test(answer) ? 0 : 1);

package/scripts/start.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Phase 7 startup (docs/architecture.md): one command to bring up the **dev** instance on a machine
+ * that has nothing but Node. `start.sh` (macOS/Linux) and `start.cmd` (Windows) exist only to check
+ * that Node is there — everything below is one Node script, so all three OSes behave identically.
+ *
+ *   ./start.sh | start.cmd            # or: npm run start
+ *   node scripts/start.mjs --skip-models --skip-verify --turn --root DIR
+ *
+ * In order, and never silently:
+ *   1. Node >= 22.19 (pi 1.0.4 engines; 24+ recommended for `node:sqlite`)
+ *   2. `npm install` when node_modules is missing or package-lock.json changed since the last install
+ *   3. `.flypi/agent/` config: settings.json + models.json templates when absent, and the
+ *      `flypi-memory` entry in mcp.json with a token generated once and kept (0600, gitignored)
+ *   4. download the memory models into `.flypi/models` (`npm run models:warm`)
+ *   5. verify: `npm run probe -- --no-turn` (config + isolation) always, and one real model turn on a
+ *      fresh config, where a working endpoint is the thing that has just been wired up
+ *   6. start both halves of the dev instance — the memory MCP server and Vite — and print the URL
+ *
+ * It runs *before* `npm install`, so it imports nothing from `src/` and needs no dependency: the agent
+ * config is plain JSON, read and written here directly. `memoryEndpoint()` in src/agent/config-files.ts
+ * stays the authority for a running app; this is only what makes that file exist the first time.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { connect } from "node:net";
+import { join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const MIN_NODE = "22.19.0";
+const MEMORY_PORT = 8790;
+const DEV_AGENT_PORT = Number(process.env.FLYPI_DEV_PORT ?? 56789);
+const DEV_UI_PORT = Number(process.env.FLYPI_UI_PORT ?? 5173);
+
+/** The starting config for a machine with nothing configured: a local OpenAI-compatible endpoint. */
+const SETTINGS_TEMPLATE = {
+	defaultProvider: "lmstudio",
+	defaultModel: "replace-with-your-model-id",
+	defaultThinkingLevel: "low",
+	defaultTools: ["read", "bash", "edit", "write"],
+};
+const MODELS_TEMPLATE = {
+	providers: {
+		lmstudio: {
+			baseUrl: "http://127.0.0.1:1234/v1",
+			api: "openai-completions",
+			// A placeholder: pi accepts any value here, which is how a local server stays usable
+			// without a credential (src/agent/onboarding.ts). Replace it for a real provider.
+			apiKey: "lmstudio-local",
+			compat: { supportsDeveloperRole: false, supportsReasoningEffort: false },
+			models: [
+				{
+					id: "replace-with-your-model-id",
+					input: ["text"],
+					contextWindow: 32768,
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				},
+			],
+		},
+	},
+};
+
+/** The Node check, apart from the process so it can be tested against a version string. */
+export function nodeProblem(version = process.versions.node) {
+	const want = MIN_NODE.split(".").map(Number);
+	const have = version.split(".").map(Number);
+	for (let i = 0; i < want.length; i++) {
+		if ((have[i] ?? 0) < want[i]) {
+			return `Node ${MIN_NODE} or newer is required (found ${version}) — install it from https://nodejs.org. 24+ is recommended: flypi uses the built-in node:sqlite.`;
+		}
+		if ((have[i] ?? 0) > want[i]) break;
+	}
+	return undefined;
+}
+
+function readJson(file, fallback) {
+	if (!existsSync(file)) return fallback;
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		throw new Error(`${file} is not valid JSON: ${error.message}`);
+	}
+}
+
+/** 0600 like every other file flypi writes here: mcp.json holds the memory token. */
+function writeJson(file, value) {
+	mkdirSync(join(file, ".."), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+	chmodSync(file, 0o600);
+}
+
+/**
+ * Make `.flypi/agent/` exist and hold something that starts. Existing files are never rewritten: a
+ * working `models.json` carries compat, cost and context windows this script has no idea about, and
+ * clobbering one is worse than a fresh clone.
+ *
+ * The memory token is generated once and then read back from the file, so re-running the script does
+ * not invalidate a store that already has memories. An entry already using `${FLYPI_MEMORY_TOKEN}` is
+ * left alone — the token then comes from the environment, which `startDev` supplies either way.
+ */
+export function ensureConfig(root, env = process.env) {
+	const dir = join(root, ".flypi", "agent");
+	mkdirSync(dir, { recursive: true });
+	const created = [];
+
+	for (const [name, template] of [
+		["settings.json", SETTINGS_TEMPLATE],
+		["models.json", MODELS_TEMPLATE],
+	]) {
+		const file = join(dir, name);
+		// Absent, or the empty pair the daemon writes for a root that has no config of its own: an empty
+		// object holds nothing to lose, and a checkout that ran `flypi start` once still gets the template.
+		if (!existsSync(file) || Object.keys(readJson(file, {})).length === 0) {
+			writeJson(file, template);
+			created.push(name);
+		}
+	}
+
+	const mcpPath = join(dir, "mcp.json");
+	const file = readJson(mcpPath, {});
+	const servers = file.mcpServers ?? {};
+	const entry = servers["flypi-memory"];
+	let port = MEMORY_PORT;
+	let token;
+	if (!entry) {
+		token = randomBytes(24).toString("hex");
+		servers["flypi-memory"] = {
+			url: `http://127.0.0.1:${MEMORY_PORT}/mcp`,
+			description: "flypi memory store: memory_search, memory_write, memory_read, memory_supersede, memory_forget",
+			headers: { Authorization: `Bearer ${token}` },
+			exposure: "direct",
+		};
+		writeJson(mcpPath, { ...file, mcpServers: servers });
+		created.push("mcp.json (flypi-memory entry, token generated)");
+	} else {
+		const bearer = /^Bearer\s+(.*)$/.exec(String(entry.headers?.Authorization ?? ""))?.[1];
+		token = bearer && bearer !== "${FLYPI_MEMORY_TOKEN}" ? bearer : env.FLYPI_MEMORY_TOKEN || randomBytes(24).toString("hex");
+		const url = entry.url ? new URL(entry.url) : undefined;
+		if (url?.port) port = Number(url.port);
+	}
+	return { token, port, created };
+}
+
+/** Why an install is needed, or undefined when the tree already matches the lockfile. */
+export function installReason(root) {
+	if (!existsSync(join(root, "node_modules"))) return "no node_modules";
+	const lock = join(root, "package-lock.json");
+	if (!existsSync(lock)) return undefined;
+	const hash = createHash("sha256").update(readFileSync(lock)).digest("hex");
+	const stamp = join(root, ".flypi", "install-stamp");
+	if (existsSync(stamp) && readFileSync(stamp, "utf8").trim() === hash) return undefined;
+	return "package-lock.json changed since the last install";
+}
+
+/** True when something is already listening — the dev instance dies on EADDRINUSE, so say so first. */
+export function portInUse(port, host = "127.0.0.1") {
+	return new Promise((done) => {
+		const socket = connect({ port, host });
+		socket.setTimeout(500);
+		socket.once("connect", () => {
+			socket.destroy();
+			done(true);
+		});
+		socket.once("timeout", () => {
+			socket.destroy();
+			done(false);
+		});
+		socket.once("error", () => done(false));
+	});
+}
+
+/** npm on Windows is a .cmd, which Node refuses to spawn without a shell. The args here are fixed. */
+const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
+const SHELL = process.platform === "win32";
+
+function runNpm(checkout, ...args) {
+	return spawnSync(NPM, ["run", ...args], { cwd: checkout, stdio: "inherit", shell: SHELL }).status ?? 1;
+}
+
+async function main() {
+	const argv = process.argv.slice(2);
+	const flagValue = (name) => {
+		const i = argv.indexOf(name);
+		return i === -1 ? undefined : argv[i + 1];
+	};
+	// The checkout this script lives in is where npm runs — that is where package.json, node_modules and
+	// tsx are. `--root` says which `.flypi/` the instance owns, the same split scripts/flypi.mjs uses.
+	const checkout = resolve(fileURLToPath(import.meta.url), "..", "..");
+	const root = resolve(flagValue("--root") ?? checkout);
+
+	const node = nodeProblem();
+	if (node) {
+		console.error(`flypi: ${node}`);
+		process.exit(1);
+	}
+	console.log(`flypi: node ${process.versions.node}, root ${root}`);
+
+	const why = installReason(checkout);
+	if (why) {
+		console.log(`flypi: npm install (${why})`);
+		if (spawnSync(NPM, ["install"], { cwd: checkout, stdio: "inherit", shell: SHELL }).status !== 0) {
+			console.error("flypi: npm install failed — nothing else can run until it succeeds");
+			process.exit(1);
+		}
+		const stamp = join(checkout, ".flypi", "install-stamp");
+		mkdirSync(join(stamp, ".."), { recursive: true });
+		writeFileSync(stamp, createHash("sha256").update(readFileSync(join(checkout, "package-lock.json"))).digest("hex"));
+	}
+
+	const config = ensureConfig(root);
+	for (const name of config.created) console.log(`flypi: wrote ${join(root, ".flypi", "agent", name)}`);
+	if (config.created.includes("models.json")) {
+		console.log("flypi: models.json is a template — set the provider, baseUrl and model id your server actually serves (the settings gear in the UI edits the same file)");
+	}
+
+	if (!argv.includes("--skip-models")) {
+		console.log("flypi: fetching the memory models into .flypi/models (first run downloads them, later runs are instant)");
+		if (runNpm(checkout, "models:warm", "--", "--root", root) !== 0) {
+			console.error("flypi: the embedding model did not load. Memory search would fall back to keywords; re-run with --skip-models to start anyway, or fix the network and run again.");
+			process.exit(1);
+		}
+	}
+
+	if (!argv.includes("--skip-verify")) {
+		console.log("flypi: verifying the config (probe --no-turn)");
+		if (runNpm(checkout, "probe", "--", "--no-turn", "--root", root) !== 0) {
+			console.error("flypi: the config does not start a session — fix what probe says above");
+			process.exit(1);
+		}
+		// A real turn only on a config that was just created: that is the thing worth proving, and on
+		// every later start it would spend tokens and a local server's time to prove nothing new.
+		if (config.created.length > 0 || argv.includes("--turn")) {
+			console.log("flypi: running one real turn through the configured model");
+			if (runNpm(checkout, "probe", "--", "--root", root) !== 0) {
+				console.error("flypi: the config is wired, but the model did not answer. Start the model server, or fix .flypi/agent/models.json — the UI and its settings gear will still come up.");
+			}
+		}
+	}
+
+	for (const [what, port] of [
+		["memory server", config.port],
+		["dev agent server", DEV_AGENT_PORT],
+		["dev UI (Vite)", DEV_UI_PORT],
+	]) {
+		if (await portInUse(port)) {
+			console.error(`flypi: something is already listening on ${port} (${what}). Stop it first — for flypi's own daemon: node scripts/flypi.mjs stop`);
+			process.exit(1);
+		}
+	}
+
+	startDev(checkout, root, config);
+}
+
+/**
+ * Both halves of dev in one command: the memory MCP server (a separate process by design — the store
+ * has one writer) and Vite, which starts the agent server in its own process. Ctrl-C stops all three;
+ * they share the terminal's process group, which is also how Windows delivers it.
+ * shortcut: no restart-on-crash, dev is a foreground thing; if a half needs to survive, that is the
+ * daemon (`node scripts/flypi.mjs start`), not this.
+ */
+function startDev(checkout, root, config) {
+	const env = { ...process.env, FLYPI_MEMORY_TOKEN: config.token };
+	const children = [
+		spawn(NPM, ["run", "memory", "--", "--root", root, "--port", String(config.port), "--token", config.token], { cwd: checkout, stdio: "inherit", shell: SHELL, env }),
+		// --strictPort so the URL printed below is the URL Vite is on: without it Vite silently takes the
+		// next free port and the line the user clicks would be a guess.
+		spawn(NPM, ["run", "dev", "--", "--port", String(DEV_UI_PORT), "--strictPort"], { cwd: checkout, stdio: "inherit", shell: SHELL, env }),
+	];
+	console.log(`flypi: UI http://localhost:${DEV_UI_PORT} — agent server on port ${DEV_AGENT_PORT}, memory MCP on ${config.port}`);
+	let stopping = false;
+	const stop = () => {
+		if (stopping) return;
+		stopping = true;
+		for (const child of children) child.kill("SIGTERM");
+	};
+	process.on("SIGINT", stop);
+	process.on("SIGTERM", stop);
+	for (const child of children) {
+		child.on("exit", (code) => {
+			// One half dying is a broken dev instance, so neither stays up: the UI without memory is a
+			// chat that silently forgets, and memory without the UI has nobody to talk to.
+			if (!stopping) {
+				console.error(`flypi: a half of the dev instance exited (code ${code}) — stopping the other`);
+				stop();
+			}
+		});
+	}
+}
+
+// Run when invoked directly, import as a module when a test wants the helpers (tests/scripts/start.test.ts).
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+	await main();
+}

package/scripts/turn-boundary.ts

@@ -0,0 +1,52 @@
+/**
+ * C1's instrument for real conversations (docs/prompt-cache.md Phase 4.7): what the turn boundary cost, in
+ * tokens, in the conversations flypi actually ran.
+ *
+ *   npm run probe:boundary            # every .flypi/sessions/*.jsonl
+ *   npm run probe:boundary -- path    # one session file, or another sessions dir
+ *
+ * It reads the provider's own numbers out of pi's session log — the same accounting `turns.usage_json` holds
+ * (Phase 4.6 A1), summed per turn there — and splits the model calls at the only place the prompt cache is
+ * allowed to break: the first call of a turn. Nothing here asks a model anything, so it re-runs on any
+ * machine that has the session files.
+ *
+ * `probe:turn` is the other half: it runs one two-turn conversation on a live route, and `--no-memory` runs
+ * it with nothing transient injected, which is how you tell the break apart from the route forgetting its
+ * cache anyway.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { flypiPaths } from "../src/agent/paths.ts";
+import { modelCalls, spread, summarise, type ModelCall } from "../src/shared/turn-boundary.ts";
+
+const sessionsDir = flypiPaths(process.cwd()).sessionsDir;
+const target = resolve(process.argv[2] ?? sessionsDir);
+if (!existsSync(target)) {
+	console.error(`no session files at ${target} — flypi keeps them in ${sessionsDir}`);
+	process.exit(1);
+}
+const files = statSync(target).isDirectory()
+	? readdirSync(target).filter((name) => name.endsWith(".jsonl")).sort().map((name) => `${target}/${name}`)
+	: [target];
+
+for (const file of files) {
+	const calls = modelCalls(readFileSync(file, "utf8"));
+	const summary = summarise(calls);
+	if (summary.boundaries === 0) continue; // one-turn conversations have no boundary to price
+	console.log(`${file.split("/").pop()}  ${calls[0]?.model ?? "?"}  model calls=${calls.length}`);
+	for (const call of calls.filter((c: ModelCall) => c.firstCallOfTurn && c.carry > 0)) {
+		console.log(
+			`  boundary  prompt=${call.prompt} reused=${call.reused} repaid=${call.repaid} could_reuse=${call.carry}`,
+		);
+	}
+}
+
+const all = summarise(files.flatMap((file) => modelCalls(readFileSync(file, "utf8"))));
+console.log(
+	[
+		`turn boundaries after the first turn: ${all.boundaries}`,
+		`  re-paid (min/median/max tokens):        ${spread(all.paid)}  total=${all.paid.reduce((a, b) => a + b, 0)}`,
+		`  the prefix that was there to reuse:     ${spread(all.carry)}`,
+		`  inside a turn, the same conversations:  n=${all.withinTurn.length} re-paid ${spread(all.withinTurn)}`,
+	].join("\n"),
+);

package/scripts/update.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * `flypi update` (docs/architecture.md Phase 7): put the newest published flypi on this machine.
+ *
+ *   flypi update            # check, download, stop the daemon, install it, start the daemon again
+ *   flypi update --check    # the answer only — touches nothing but the stamp
+ *   flypi update --dry-run  # every step, none of them run
+ *
+ * The same package the daemon downloads on its own and installs while it is idle (`src/daemon/update.ts`);
+ * this is the version of that you can ask for at a keyboard. The daemon is stopped before the install because
+ * it replaces the files it is running from, and started again through this same CLI, which is what keeps the
+ * port and interface it was reached by (`flypi restart`'s rule). If the install fails, the daemon is started
+ * again on the version it had: a failed update leaves a running flypi, not a dead one.
+ */
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { checkForUpdate, clearUpdateCheck, downloadUpdate, installArgs, isGlobalInstall, isNewer, keepDownload, packageDir, packageInfo, readUpdateCheck, updateAvailable, writeUpdateCheck } from "../src/daemon/update.ts";
+
+const argv = process.argv.slice(2);
+const rootAt = argv.indexOf("--root");
+const root = resolve(rootAt === -1 ? process.env.FLYPI_ROOT ?? process.cwd() : (argv[rootAt + 1] ?? ""));
+const checkOnly = argv.includes("--check");
+const dryRun = argv.includes("--dry-run");
+const pkg = packageInfo();
+
+/** `remote: true` marks the steps that leave this machine, so the dry-run output says which is which. */
+function run(command: string, args: string[], { remote = false } = {}): number {
+	if (dryRun) {
+		console.log(`flypi update: would run${remote ? " [remote]" : ""}: ${command} ${args.join(" ")}`);
+		return 0;
+	}
+	return spawnSync(command, args, { stdio: "inherit" }).status ?? 1;
+}
+/** The daemon CLI, for the stop and the start — so the port/interface carry-over lives in one place. */
+const cli = (...args: string[]) => run(process.execPath, [resolve(import.meta.dirname, "flypi.mjs"), "--root", root, ...args]);
+
+if (pkg.checkout) {
+	// The registry only knows what `npm publish` put there, and a checkout has the source in front of it.
+	console.log(`flypi: ${pkg.version} is a checkout at ${packageDir()} — update it with git:`);
+	console.log("flypi:   git pull --ff-only && npm install && npm run build, then `flypi restart`");
+	process.exit(0);
+}
+
+const stamp = await checkForUpdate({ current: pkg.version, name: pkg.name });
+// A package the daemon already downloaded stays staged; `--check` leaves the stamp as it is.
+stamp.download = keepDownload(stamp, readUpdateCheck(root));
+if (!dryRun) writeUpdateCheck(root, stamp);
+if (stamp.error) {
+	console.log(`flypi: no update check: ${stamp.error}`);
+	process.exit(0);
+}
+const step = updateAvailable(stamp, pkg.version);
+if (!step) {
+	console.log(`flypi: ${pkg.version} is the newest published version of ${pkg.name}`);
+	process.exit(0);
+}
+// One step, never a jump: flypi's databases migrate when the version that needs the migration starts, so
+// 0.1.0 → 0.3.0 would skip what 0.2.0 would have done to the schema (src/daemon/update.ts).
+const further = stamp.latest && isNewer(step, stamp.latest) ? ` — one step at a time; ${stamp.latest} is the newest published` : "";
+console.log(`flypi: ${pkg.version} → ${step}${further}`);
+if (checkOnly) {
+	console.log(stamp.download ? `flypi: ${step} is downloaded; it installs the next time the daemon is idle` : "flypi: `flypi update` installs it");
+	process.exit(0);
+}
+if (!stamp.dist?.tarball) {
+	console.error(`flypi: the registry named no package for ${step} to download`);
+	process.exit(1);
+}
+if (!isGlobalInstall()) console.log("flypi: note — this code is not the npm global package, so `npm install -g` may not replace it");
+
+const downloaded = await downloadUpdate({ root, version: step, dist: stamp.dist });
+if (dryRun) {
+	console.log(`flypi update: would download ${stamp.dist.tarball}, verify it against the registry's checksum, then:`);
+	cli("stop");
+	run("npm", installArgs("<the downloaded package>"), { remote: true });
+	cli("start");
+	process.exit(0);
+}
+if (!downloaded.file) {
+	console.error(`flypi: ${step} could not be downloaded: ${downloaded.error}`);
+	process.exit(1);
+}
+stamp.download = { version: step, file: downloaded.file, at: new Date().toISOString() };
+writeUpdateCheck(root, stamp);
+
+cli("stop");
+const installed = run("npm", installArgs(downloaded.file), { remote: true });
+if (installed === 0) clearUpdateCheck(root);
+cli("start");
+if (installed !== 0) console.error("flypi: the install failed — the daemon is running the version it had");
+else console.log(`flypi: ${pkg.name}@${step} installed${further}`);
+process.exit(installed);