@makerstufferupper/flypi 0.0.0-stage → 0.1.2

package/scripts/secret.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * The vault from a shell (docs/secrets.md Phase 5.5): `flypi secret list | get | print | put | rotate |
+ * delete | undelete | path | import-ssh | rotate-key`.
+ *
+ *   echo 'sk-…' | flypi secret put openai_key --kind password
+ *   flypi secret print openai_key          # the value, for `!flypi secret print NAME` in a config file
+ *
+ * The value comes from stdin, not argv, so it does not appear in the process list next to a username. Read
+ * commands open the database read-only, which is why they answer while the daemon is running.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { runSecretCli } from "../src/secrets/cli.ts";
+
+const argv = process.argv.slice(2);
+const rootAt = argv.indexOf("--root");
+const root = rootAt === -1 ? process.env.FLYPI_ROOT ?? process.cwd() : (argv[rootAt + 1] ?? "");
+if (rootAt !== -1) argv.splice(rootAt, 2);
+
+// A piped value, read here so `runSecretCli` stays synchronous and testable (src/secrets/cli.ts). A terminal
+// would block on stdin, so only a pipe or a redirect counts.
+const stdin = process.stdin.isTTY ? undefined : readFileSync(0, "utf8");
+process.exit(runSecretCli(argv, { root: resolve(root), ...(stdin === undefined ? {} : { stdin }) }));

package/scripts/serve-daemon.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * The always-on daemon (docs/architecture.md Phase 4.5): the agent server, the built UI, the memory MCP
+ * surface and the job queue in one process. Foreground here; `flypi start` is what puts it in the
+ * background and writes `.flypi/daemon.log`.
+ *
+ *   npm run daemon                              # ports and token from .flypi/agent/mcp.json
+ *   npm run daemon -- --port 8787               # override the agent server
+ *   npm run daemon -- --host 0.0.0.0            # bind every interface (a container: a published port
+ *                                               # cannot reach the container's own loopback)
+ *   npm run daemon -- --embeddings none         # FTS-only memory, no model download
+ *
+ * Unlike `npm run serve`, this is the process that keeps conversations alive with no client attached,
+ * records which turn was running when it died, and runs `memory.reembed` while idle. It holds both
+ * databases — the memory store's and the backend's run record — because it is the one process that is both
+ * halves at once; `npm run serve` holds only the second.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { flypiPaths } from "../src/agent/paths.ts";
+import { builtUi, startFlypiDaemon } from "../src/daemon/index.ts";
+import { memoryConfig } from "../src/memory/config.ts";
+import { openMemoryDb } from "../src/memory/db.ts";
+import { createEmbedder } from "../src/memory/embed.ts";
+import { modelProgress } from "../src/memory/progress.ts";
+import { createJudge } from "../src/memory/judge.ts";
+import { MemoryStore } from "../src/memory/store.ts";
+import { openRunStore } from "../src/server/run-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";
+if (flagValue("--judge")) config.judge.provider = flagValue("--judge") === "none" ? "none" : "transformers";
+
+// The download is ~1 GB on a machine that has never run flypi, and the daemon is not listening until it
+// finishes — so both loaders report what they are fetching, into the log `flypi start` echoes back.
+const embedder = await createEmbedder(config.embeddings, modelProgress(config.embeddings.model));
+if (embedder.error) console.log(`flypi: ${embedder.error} — memory search will be keyword-only`);
+// A second resident model (~400 MB next to the embedder, docs/decisions.md). Not loading it is supported:
+// the store judges what tokens can judge and says so. With no embedder there is no candidate set.
+const judge = embedder.identity ? await createJudge(config.judge, modelProgress(config.judge.model)) : { classify: undefined };
+if (judge.error) console.log(`flypi: ${judge.error}`);
+
+const db = openMemoryDb(paths.memoryDbPath);
+const store = new MemoryStore(db, embedder, { classify: judge.classify });
+// The backend's own database: which conversation had a turn in flight. Separate file, separate writer.
+const runs = openRunStore(paths);
+
+const token = flagValue("--token") ?? process.env.FLYPI_TOKEN;
+// The package the code ships in — not `paths.root`, which is the state directory (`~/.flypi`'s parent for
+// an installed app, the checkout in a dev tree).
+const pkgDir = resolve(fileURLToPath(import.meta.url), "..", "..");
+// The built UI ships next to the code, not next to the state: `--root` says which `.flypi/` the daemon owns,
+// and for the installed app that is the home directory, which has no dist/ui in it.
+const uiDir = builtUi(pkgDir);
+// The version the health page and `flypi status` report. Read from the package rather than from npm's
+// environment: the CLI spawns this directly, so npm_package_version is only set when it came through a script.
+const version = (JSON.parse(readFileSync(resolve(pkgDir, "package.json"), "utf8")).version ?? "dev") as string;
+const daemon = await startFlypiDaemon({
+	paths,
+	db,
+	store,
+	runs,
+	...(flagValue("--port") ? { port: Number(flagValue("--port")) } : {}),
+	// Set by `flypi start` when the port came from an earlier start rather than from this command line: a port
+	// nobody named today is a preference, so the daemon binds another one instead of dying on `EADDRINUSE`.
+	...(argv.includes("--port-may-move") ? { portMayMove: true } : {}),
+	...(flagValue("--host") ? { host: flagValue("--host") } : {}),
+	...(token ? { token } : {}),
+	...(uiDir ? { uiDir } : {}),
+	version,
+});
+console.log(`flypi: daemon pid ${process.pid}`);
+console.log(`flypi: agent server ${daemon.url}`);
+console.log(`flypi: memory MCP   http://127.0.0.1:${daemon.memoryPort}/mcp`);
+console.log(`flypi: embeddings   ${embedder.identity ? embedder.identity.model : "none (FTS-only)"}`);
+console.log(`flypi: judge        ${judge.classify ? config.judge.model : "none (token rule only)"}`);
+if (!uiDir) console.log("flypi: dist/ui is not built — running headless (`npm run build` for the UI)");
+console.log("flypi: `flypi stop`, or Ctrl-C, to stop`");
+
+// The plan's rule: an interrupted turn is not re-run, because the tools may already have written to the
+// world. So shutdown only has to stop the loop, close the sockets and leave the record.
+let stopping = false;
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+	process.on(signal, () => {
+		if (stopping) return;
+		stopping = true;
+		void daemon.close().then(() => {
+			db.close();
+			runs.close();
+			process.exit(0);
+		});
+	});
+}

package/scripts/serve-memory.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Start the memory store as an MCP server over HTTP (docs/memory.md Phase 3).
+ *
+ *   npm run memory                                  # ephemeral port, generated token
+ *   npm run memory -- --port 8790 --token …         # fixed
+ *   npm run memory -- --embeddings none             # FTS-only, no model download
+ *   npm run memory -- --judge none                  # no contradiction model (token rule only)
+ *
+ * Point an MCP client at it with:
+ *   { "name": "flypi-memory", "url": "http://127.0.0.1:<port>/mcp", "headers": { "Authorization": "Bearer <token>" } }
+ *
+ * Two mounts, one store: `/mcp` is an ordinary caller, `/mcp/background` is an unattended writer — same token,
+ * same database, and the store refuses it `memory_supersede`/`memory_forget`/`memory_capture`
+ * (src/memory/mcp.ts, docs/memory.md Phase 4.8). flypi points a review fork's entry at the second one.
+ */
+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 { createJudge } from "../src/memory/judge.ts";
+import { startMemoryServer } from "../src/memory/mcp.ts";
+import { MemoryStore } from "../src/memory/store.ts";
+import { openSecretVault } from "../src/secrets/vault.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";
+if (flagValue("--judge")) config.judge.provider = flagValue("--judge") === "none" ? "none" : "transformers";
+
+const embedder = await createEmbedder(config.embeddings);
+if (embedder.error) console.log(`flypi memory: ${embedder.error} — search will be keyword-only`);
+// A second resident model (~400 MB of RSS next to the embedder, docs/decisions.md). Refusing to load it
+// is a supported state, not a failure: the store keeps judging what tokens can judge and says so.
+// With no embedder there is no candidate set, so a judge would be 400 MB for a call that cannot happen.
+const judge = embedder.identity ? await createJudge(config.judge) : { classify: undefined };
+if (judge.error) console.log(`flypi memory: ${judge.error}`);
+
+const db = openMemoryDb(flagValue("--db") ?? paths.memoryDbPath);
+const store = new MemoryStore(db, embedder, { classify: judge.classify });
+// The vault lives in this same file, so this process is the one that can write it — and opening it here is
+// what makes `redactSecrets` real when a memory body is stored (docs/secrets.md Phase 5.5). A memory server
+// with no vault open would accept `sk-…` into a memory row and never know.
+// This process owns the write handle, so the vault may record uses and changes against it.
+openSecretVault(paths, { db, write: true });
+const identity = store.indexIdentity();
+if (identity.stale > 0 && identity.expected) {
+	console.log(`flypi memory: ${identity.stale} stored vectors are not from ${identity.expected?.model} — queued memory.reembed`);
+}
+
+const server = await startMemoryServer({
+	store,
+	port: flagValue("--port") ? Number(flagValue("--port")) : undefined,
+	token: flagValue("--token") ?? process.env.FLYPI_MEMORY_TOKEN,
+	principal: "mcp",
+});
+
+console.log(`flypi memory: listening ${server.url}`);
+console.log(`flypi memory: token     ${server.token}`);
+console.log(`flypi memory: embeddings ${embedder.identity ? embedder.identity.model : "none (FTS-only)"}`);
+console.log(`flypi memory: judge      ${judge.classify ? config.judge.model : embedder.identity ? "none (token rule only)" : "none (no candidates without embeddings)"}`);
+console.log("flypi memory: Ctrl-C to stop");
+
+const stop = () => {
+	void server.close().then(() => {
+		db.close();
+		process.exit(0);
+	});
+};
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);

package/scripts/serve.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Start the flypi agent server (docs/protocol.md).
+ *
+ *   npm run serve                     # ephemeral port, generated token
+ *   npm run serve -- --port 8787      # fixed port
+ *   FLYPI_TOKEN=… npm run serve -- --token …
+ */
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { flypiPaths } from "../src/agent/paths.ts";
+import { memoryEndpoint } from "../src/agent/config-files.ts";
+import { memoryConfig } from "../src/memory/config.ts";
+import { openMemoryDbReadOnly } from "../src/memory/db.ts";
+import { configuredIdentity } from "../src/memory/embed.ts";
+import { MemoryStore } from "../src/memory/store.ts";
+import { memoryApi } from "../src/server/memory-api.ts";
+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 { startFlypiServer } from "../src/server/index.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()));
+// The backend's own database, and this process is its only writer (docs/risks.md risk 3): it is the process
+// that runs pi sessions, so it is the process that knows whether a turn was in flight. The memory store is
+// not opened here at all — this half has no business with it, and the agent reaches memory over MCP.
+const runs = openRunStore(paths);
+// One backend at a time owns this file, like any other flypi database: `flypi start` or `npm run serve`, not
+// both. Whatever is left `running` belongs to a process that is gone, so say so before serving anyone a chat.
+runs.reconcileInterrupted();
+// The vault is in the memory database, which this process does not own. With the file present it is opened
+// read-only, so a chat run here still redacts `[secret:x]` instead of repeating a credential into the
+// transcript; with no file, or one this build has not migrated, the sessions simply have no secret tools and
+// the Secrets tab says so (docs/secrets.md Phase 5.5). `flypi start` is the process that can write it.
+let vault: SecretStore | undefined;
+// The memory browser (docs/memory.md Phase 6) reads the same file. Read-only, like the vault: the Memory tab
+// lists rows, turns and wiki pages from here, and a write is refused with the sentence that names the process
+// that may write. The embedder is the configured model's *identity* and nothing more, so the index state the
+// panel reports is true without this process loading ~100 MB of model it will never ask a vector of.
+let memory: ReturnType<typeof memoryApi> | undefined;
+try {
+	if (existsSync(paths.memoryDbPath)) {
+		const memoryDb = openMemoryDbReadOnly(paths.memoryDbPath);
+		memory = memoryApi(new MemoryStore(memoryDb, await configuredIdentity(memoryConfig(paths).embeddings)), memoryDb, { readOnly: true });
+	}
+} catch (error) {
+	console.log(`flypi: no memory store: ${(error as Error).message}`);
+}
+const registry = new SessionRegistry({
+	root: paths.root,
+	onRunStatus: (conversationId, status, info) => runs.setRunStatus(conversationId, status, info),
+	vault,
+});
+const server = await startFlypiServer({
+	registry,
+	port: flagValue("--port") ? Number(flagValue("--port")) : undefined,
+	token: flagValue("--token") ?? process.env.FLYPI_TOKEN,
+	serverVersion: "dev",
+	// 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").
+	uiDir: resolve(process.cwd(), "dist/ui"),
+	secrets: vault ? secretsApi(vault, paths) : undefined,
+	memory,
+});
+
+console.log(`flypi: listening ${server.url}`);
+console.log(`flypi: token    ${server.token}`);
+console.log(`flypi: connect  ${server.url}/?token=${server.token}`);
+// Same check the daemon makes: an entry pointing at a token this process does not have is refused by the
+// store, and the sessions here would simply have no memory tools (docs/risks.md risk 8).
+const memoryNote = memoryEndpoint(paths).note;
+if (memoryNote) console.log(`flypi: ${memoryNote}`);
+console.log("flypi: Ctrl-C to stop");
+
+const stop = () => {
+	registry.dispose();
+	runs.close();
+	void server.close().then(() => process.exit(0));
+};
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);

package/scripts/smoke-memory.mjs

@@ -0,0 +1,239 @@
+/**
+ * Phase 3's gate in one command (docs/memory.md, docs/testing.md): the SQLite file, both halves of
+ * search, the status rules, and the MCP-over-HTTP surface — against the real `.flypi/memory/flypi.db`
+ * the plan says must stay queryable with `sqlite3`.
+ *
+ * It is a driver, not a test: the assertions live in tests/memory/*. What it adds is that the same
+ * file opens, migrates, and answers a client that speaks MCP.
+ *
+ * Run: npm run smoke:memory            (add -- --no-embeddings to skip the model download)
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deflateSync } from "node:zlib";
+import { McpClient, StreamableHttpTransport } from "@earendil-works/pi-mcp";
+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 { startMemoryServer } from "../src/memory/mcp.ts";
+import { MemoryStore } from "../src/memory/store.ts";
+import { consolidate, planSweep } from "../src/memory/consolidate.ts";
+import { readWiki, renderWiki } from "../src/memory/wiki.ts";
+
+const paths = flypiPaths(process.cwd());
+const flagValue = (name) => {
+	const i = process.argv.indexOf(name);
+	return i === -1 ? undefined : process.argv[i + 1];
+};
+const dbFile = flagValue("--db") ?? paths.memoryDbPath;
+const config = memoryConfig(paths);
+if (process.argv.includes("--no-embeddings")) config.embeddings.provider = "none";
+
+const embedder = await createEmbedder(config.embeddings);
+const db = openMemoryDb(dbFile);
+const store = new MemoryStore(db, embedder);
+
+const ok = (line) => console.log(`ok: ${line}`);
+const fail = (line) => {
+	console.error(`FAIL: ${line}`);
+	process.exit(1);
+};
+
+const marker = `smoke-${Date.now()}`;
+const write = (body, extra = {}) =>
+	store.addMemory({ kind: "smoke", body, tags: ["smoke"], origin_class: "agent", session_kind: "interactive", actor: "smoke", ...extra });
+
+// 1. Write, then find it by its own words.
+const { id } = await write(`${marker}: the build command is npm run build`);
+const byKeyword = await store.search({ query: marker });
+if (!byKeyword.results.some((row) => row.id === id)) fail(`#${id} was not found by its own marker`);
+ok(
+	`store + keyword search — #${id} in ${byKeyword.results.length} hit(s)` +
+		(byKeyword.partial ? `, keyword-only (${embedder.error ?? "embeddings off"})` : `, embeddings ${embedder.identity?.model}`),
+);
+
+// 2. The one automatic transition: active → superseded, both rows kept. The two rows must be different
+// facts — the dedup gate is meant to catch the same fact worded differently (see NEAR_DUPLICATE).
+const { id: replacement } = await write(`${marker}: the deploy target is 10.0.0.7`);
+store.markSuperseded(id, replacement, "smoke");
+const retired = store.memory(id);
+if (retired.status !== "superseded" || retired.superseded_by !== replacement) fail("supersede did not leave both rows linked");
+if (store.memory(replacement).status !== "active") fail("the replacement is not active");
+if ((await store.search({ query: marker })).results.some((row) => row.id === id)) fail("a superseded row is still searchable");
+ok(`status rules — #${id} superseded by #${replacement}, both rows still in the table`);
+
+// 3. Nothing deletes a row except an explicit forget; a repeat write is not a second row.
+const { id: throwaway } = await write(`${marker}: this one is only here to be forgotten`);
+const repeated = await write(`${marker}: this one is only here to be forgotten`);
+if (repeated.duplicateOf !== throwaway) fail(`a repeat of #${throwaway} wrote #${repeated.id} instead of pointing back`);
+if (store.memory(id).use_count === 0) fail("the search in step 1 did not count as a use");
+ok(`dedup + counters — a repeat points at #${throwaway}, retrieval counted ${store.memory(id).use_count} use(s)`);
+
+const rowsBefore = db.prepare("SELECT count(*) AS n FROM memories").get().n;
+store.forget(throwaway, "smoke");
+if (store.memory(throwaway).status !== "deleted") fail("forget did not reach status=deleted");
+if (db.prepare("SELECT count(*) AS n FROM memories").get().n !== rowsBefore) fail("a memory row disappeared; Phase 3 never hard-deletes");
+ok(`audit + delete rules — ${db.prepare("SELECT count(*) AS n FROM memory_audit WHERE memory_id = ?").get(throwaway).n} audit rows for #${throwaway}, still ${rowsBefore} memory rows`);
+
+// 4. The index is one vector space, or it says so.
+const index = store.indexIdentity();
+if (index.stale > 0 && !index.reembedQueued) fail("a stale index did not queue memory.reembed");
+ok(`index identity — ${index.rows} vectors, ${index.stale} from another model, reembed queued: ${index.reembedQueued}`);
+
+// 5. The same store over HTTP, through the MCP client pi uses.
+const server = await startMemoryServer({ store, token: "smoke-token", principal: "mcp:smoke" });
+const client = new McpClient({ name: "flypi-smoke", version: "0.0.0" });
+await client.connect(new StreamableHttpTransport({ url: server.url, headers: { authorization: "Bearer smoke-token" } }));
+const tools = await client.listTools();
+// The surface the agent can reach, named rather than counted: a tool appearing or vanishing is a
+// decision, and a bare number cannot say which one moved (this sat at 7 while `memory_cite` shipped).
+// These are the ten the server registers today — see docs/memory.md Phase 4 on the read tools the
+// plan describes and this server does not have.
+const SURFACE = ["memory_capture", "memory_cite", "memory_forget", "memory_index_status", "memory_media", "memory_read", "memory_search", "memory_supersede", "memory_turn", "memory_write"];
+const names = tools.map((tool) => tool.name).sort();
+if (names.join(",") !== [...SURFACE].sort().join(",")) fail(`memory tools changed: expected ${SURFACE.join(", ")}, got ${names.join(", ")}`);
+const overTheWire = JSON.parse((await client.callTool("memory_search", { query: marker })).content[0].text);
+if (!overTheWire.results.some((row) => row.id === id || row.id === replacement)) fail("the MCP search did not see the row the store wrote");
+// A turn of a real conversation reaches the store the same way: the memory server is the only writer, and
+// the hit-rate metrics are what tell flypi whether recall paid for itself. Asked about this run's own
+// conversation by id — the store may hold turns from earlier sessions, and `memoryHitRate()` counts them all.
+await client.callTool("memory_turn", { conversation_id: "smoke-conv", user_text: "what do we use?", retrieved: [id], cited: [id] });
+const turnRow = db.prepare("SELECT retrieved_json AS retrieved, cited_json AS cited FROM turns WHERE conversation_id = 'smoke-conv'").get();
+if (!turnRow || turnRow.retrieved === null || turnRow.cited === null) fail("the turn log did not record what was shown and cited");
+const measured = store.memoryHitRate();
+if (typeof measured.rate !== "number" || measured.turns < 1) fail(`the hit-rate metric did not compute: ${JSON.stringify(measured)}`);
+ok(`MCP over HTTP — ${tools.length} tools at ${server.url}, search reached #${overTheWire.results.map((row) => row.id).join(", #")}, turn ${turnRow.retrieved} retrieved / ${turnRow.cited} cited, store hit rate ${measured.rate} over ${measured.turns} turn(s)`);
+
+// 6. A picture and a recording: a path in, a vector in the same space, the bytes back out. This is the
+// mechanism with the real model — whether the *meaning* of a photo is retrieved well is what the recall
+// corpus measures (docs/memory.md Phase 4), so nothing semantic is asserted here.
+const dir = mkdtempSync(join(tmpdir(), "flypi-smoke-media-"));
+const pictureFile = join(dir, "shape.png");
+const toneFile = join(dir, "tone.wav");
+const pictureBytes = png(64, 64, (x, y) => ((x - 32) ** 2 + (y - 32) ** 2 < 400 ? [0, 0, 0] : [255, 255, 255]));
+const toneBytes = wav(0.6, 220);
+writeFileSync(pictureFile, pictureBytes);
+writeFileSync(toneFile, toneBytes);
+
+const picture = JSON.parse((await client.callTool("memory_write", { body: `${marker}: a black circle on white`, kind: "smoke", media_path: pictureFile })).content[0].text);
+const recording = JSON.parse((await client.callTool("memory_write", { body: `${marker}: a short tone`, kind: "smoke", media_path: toneFile })).content[0].text);
+if (!picture.id || !recording.id) fail(`a media write was refused: ${picture.error ?? recording.error}`);
+for (const [written, kind] of [[picture, "image"], [recording, "audio"]]) {
+	const row = store.memory(written.id);
+	if (row.modality !== kind) fail(`#${written.id} is ${row.modality}, not ${kind}`);
+	// With a model, both must be in the index; without one, both must say why they are not.
+	if (embedder.identity ? row.embed?.dims !== 768 : written.indexed !== false || !written.note) {
+		fail(`#${written.id} ${embedder.identity ? `has no ${kind} vector in the current index` : `did not report why it is keyword-only`}`);
+	}
+}
+if (embedder.identity && store.indexIdentity().stale !== 0) fail("the media vectors did not land in the current index");
+
+const asked = JSON.parse((await client.callTool("memory_search", { query: `${marker} tone` })).content[0].text);
+if (!asked.results.some((row) => row.id === recording.id && row.modality === "audio")) fail("the search did not report the recording's modality");
+const back = JSON.parse((await client.callTool("memory_media", { id: picture.id })).content[0].text);
+if (back.mime !== "image/png" || !Buffer.from(back.base64, "base64").equals(pictureBytes)) fail("the image bytes did not come back unchanged");
+ok(`media — #${picture.id} (image) and #${recording.id} (audio) stored and found, bytes round-tripped${embedder.identity ? ", both embedded at 768d" : ", keyword-only as configured"}`);
+
+const unsupported = await client.callTool("memory_write", { body: `${marker}: a song`, kind: "smoke", media_path: join(dir, "song.mp3") });
+if (!unsupported.isError) fail("an mp3 was accepted; only wav audio is supported");
+ok("an unsupported container is refused with what to do about it");
+
+// 8. Phase 6: the sweep and the wiki. The daemon runs the sweep when the store is quiet; here it is forced,
+// because the gate is that the same file answers a whole-store pass and that the wiki comes out of it readable
+// with its `#id` spine. The merge is only run against a scratch database — a sweep over the real store would
+// merge someone's real rows to watch a script work.
+const twin = await write(`${marker}: the deploy host is the small box`);
+const twinCopy = await write(`${marker}: the deploy host is the small box at home`);
+const scratch = dbFile !== paths.memoryDbPath;
+const rowsBeforeSweep = db.prepare("SELECT count(*) AS n FROM memories").get().n;
+// Against the real store this is the plan only — `planSweep` is pure, which is the whole reason the sweep can
+// be interrupted without half-applying, and the same property means a smoke can look without merging anyone's
+// rows. Against a scratch file the pass actually writes.
+const sweep = scratch
+	? consolidate(store)
+	: planSweep(store.activeMemories(), store.activeVectors(), store.citationEvidence());
+if (db.prepare("SELECT count(*) AS n FROM memories").get().n !== rowsBeforeSweep) fail("a sweep made a memory row disappear");
+const rendered = renderWiki(store, db);
+const page = readWiki(db).find((entry) => entry.slug === "smoke");
+if (!page || !page.body.includes(`#${twin.id}`)) fail("the wiki did not render this run's rows with their #id citations");
+ok(
+	`sweep + wiki — ${scratch ? `merged ${sweep.merges.length} cluster(s),` : `planned ${sweep.merges.length} cluster(s) (plan only; pass --db to write),`} ` +
+		`${rowsBeforeSweep} rows before and after, ${rendered.pages} page(s) with ${page.sections.length} section(s), spine cites #${twin.id}`,
+);
+if (scratch && (sweep.merges.length === 0 || store.memory(twinCopy.id).status !== "superseded")) {
+	fail(`the sweep did not collapse #${twinCopy.id} into #${twin.id}`);
+}
+
+await client.close();
+await server.close();
+rmSync(dir, { recursive: true, force: true });
+
+console.log(`\nthe file: ${dbFile}`);
+// The smoke's own rows stay in the table with status='deleted' — Phase 3 never hard-deletes, and
+// forgetting them is what stops a later run's near-identical sentence from deduping against this one.
+for (const row of [id, replacement, throwaway, picture.id, recording.id]) store.forget(row, "smoke:cleanup");
+// A turn row is a measurement, not a memory, so the never-hard-delete rule does not apply to it: leaving
+// this smoke's turn in a real store would quietly move its hit-rate numbers.
+db.prepare("DELETE FROM turns WHERE conversation_id = 'smoke-conv'").run();
+ok(`cleanup — #${id}, #${replacement}, #${throwaway} are status=deleted; ${db.prepare("SELECT count(*) AS n FROM memories WHERE status='active'").get().n} active rows left`);
+console.log(`  sqlite3 '${dbFile}' 'select count(*) from memories'`);
+db.close();
+process.exit(0);
+
+/** A PNG the image encoder can actually see: solid shapes, no photo, so nothing semantic is implied. */
+function png(width, height, pixel) {
+	const stride = width * 3 + 1;
+	const raw = Buffer.alloc(stride * height);
+	for (let y = 0; y < height; y += 1) {
+		for (let x = 0; x < width; x += 1) pixel(x, y).forEach((value, channel) => (raw[y * stride + 1 + x * 3 + channel] = value));
+	}
+	const ihdr = Buffer.alloc(13);
+	ihdr.writeUInt32BE(width, 0);
+	ihdr.writeUInt32BE(height, 4);
+	ihdr[8] = 8; // bit depth
+	ihdr[9] = 2; // truecolour
+	return Buffer.concat([
+		Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+		chunk("IHDR", ihdr),
+		chunk("IDAT", deflateSync(raw)),
+		chunk("IEND", Buffer.alloc(0)),
+	]);
+}
+
+function chunk(type, body) {
+	const head = Buffer.alloc(8);
+	head.writeUInt32BE(body.length, 0);
+	head.write(type, 4);
+	const crc = Buffer.alloc(4);
+	let check = ~0;
+	for (const byte of Buffer.concat([Buffer.from(type), body])) { // the CRC covers the type and the body, not the length
+		check ^= byte;
+		for (let bit = 0; bit < 8; bit += 1) check = (check >>> 1) ^ (0xedb88320 & -(check & 1));
+	}
+	crc.writeUInt32BE(~check >>> 0, 0);
+	return Buffer.concat([head, body, crc]);
+}
+
+/** `seconds` of a `hertz` tone, 16 kHz mono — what a recorder would produce. */
+function wav(seconds, hertz) {
+	const frames = Math.round(seconds * 16_000);
+	const data = Buffer.alloc(frames * 2);
+	for (let i = 0; i < frames; i += 1) data.writeInt16LE(Math.round(8000 * Math.sin((2 * Math.PI * hertz * i) / 16_000)), i * 2);
+	const header = Buffer.alloc(44);
+	header.write("RIFF", 0);
+	header.writeUInt32LE(36 + data.length, 4);
+	header.write("WAVE", 8);
+	header.write("fmt ", 12);
+	header.writeUInt32LE(16, 16);
+	header.writeUInt16LE(1, 20);
+	header.writeUInt16LE(1, 22);
+	header.writeUInt32LE(16_000, 24);
+	header.writeUInt32LE(32_000, 28);
+	header.writeUInt16LE(2, 32);
+	header.writeUInt16LE(16, 34);
+	header.write("data", 36);
+	header.writeUInt32LE(data.length, 40);
+	return Buffer.concat([header, data]);
+}