@makerstufferupper/flypi 0.0.0-stage → 0.1.2

package/src/daemon/index.ts

@@ -0,0 +1,442 @@
+/**
+ * The always-on daemon (docs/architecture.md Phase 4.5): one process that holds the memory store, serves
+ * the agent server and the memory MCP surface, keeps conversations alive with no client attached, and runs
+ * the job queue. This is what makes dreaming possible later — and it is the process that knows, after a
+ * crash, which turn was in flight.
+ *
+ * Two databases, one per component (docs/decisions.md): `store` is the memory component's, and `runs` is the
+ * backend's. The daemon is the seam where they meet — it writes chat state to one and facts to the other, and
+ * nothing joins across the two files. Each keeps its own single writer (risk 3): the memory store is opened by
+ * the caller because opening it means loading the embedding and judgment models (~1.4 GB of RSS, docs/memory.md),
+ * and so is the run store, which is a file either entrypoint can open in a millisecond. Everything that makes
+ * it a *daemon* — the reconciliation, `/healthz`, `daemon.json`, the queue — lives here, and is tested here.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import type { FlypiPaths } from "../agent/paths.ts";
+import { applyConfigEdits, ensureAgentConfig, ensureMemoryEntry, memoryEndpoint } from "../agent/config-files.ts";
+import { applyPackageEdits, checkPackageUpdates, dueForPackageCheck, readPackageCheck, writePackageCheck } from "../agent/packages.ts";
+import { CONSOLIDATE_JOB, consolidate, sweepDue } from "../memory/consolidate.ts";
+import { startMemoryServer, type MemoryServerHandle } from "../memory/mcp.ts";
+import type { MemoryStore } from "../memory/store.ts";
+import { WIKI_JOB, renderWiki } from "../memory/wiki.ts";
+import { openSecretVault } from "../secrets/vault.ts";
+import { REENCRYPT_JOB } from "../secrets/vault.ts";
+import { memoryApi } from "../server/memory-api.ts";
+import { secretsApi } from "../server/secrets-api.ts";
+import { startFlypiServer, type FlypiServerHandle, type FlypiServerOptions } from "../server/index.ts";
+import { SessionRegistry, type CreateSession } from "../server/session-registry.ts";
+import type { RunStore } from "../server/run-store.ts";
+import { JobQueue, startJobLoop, type JobHandler } from "./jobs.ts";
+import { IDLE_BEFORE_INSTALL_MS, checkForUpdate, clearUpdateCheck, downloadUpdate, dueForCheck, installArgs, isGlobalInstall, isNewer, keepDownload, packageDir, packageInfo, readUpdateCheck, stagedUpdate, updateAvailable, writeUpdateCheck } from "./update.ts";
+
+/** What `.flypi/daemon.json` holds: enough for `flypi status` to find a running daemon again. */
+export interface DaemonInfo {
+	pid: number;
+	host: string;
+	port: number;
+	/** The token the UI needs. The file is 0600 for that reason. */
+	token: string;
+	/** Where the memory MCP surface answered, and the token its `mcp.json` entry must carry. */
+	memoryPort: number;
+	startedAt: string;
+	version: string;
+}
+
+export const DAEMON_FILE = join(".flypi", "daemon.json");
+
+export interface DaemonOptions {
+	paths: FlypiPaths;
+	db: DatabaseSync;
+	store: MemoryStore;
+	/** The backend's own store: which conversation had a turn in flight (docs/architecture.md Phase 4.5). */
+	runs: RunStore;
+	/** Only to swap in the stub model in tests; production uses the registry's own factory. */
+	createSession?: CreateSession;
+	/** How often the queue is asked what is due. Production leaves the loop's own interval alone. */
+	jobIntervalMs?: number;
+	token?: string;
+	port?: number;
+	/** When that `port` was carried over from an earlier start rather than named now, one someone else has
+	 * taken is recoverable: bind another and say so. Absent means `port` is a demand — a container's published
+	 * port is useless on another number, and moving it quietly is the dead URL this path exists to avoid. */
+	portMayMove?: boolean;
+	/** Interface to bind. Omitted means the server's loopback default; a container needs `0.0.0.0`, since a
+	 * published Docker port never reaches the container's own loopback. The token is the auth either way. */
+	host?: string;
+	uiDir?: string;
+	version?: string;
+	/** Where a daemon says what it did. Defaults to the console, which is where `flypi start` collects it. */
+	log?: (line: string) => void;
+}
+
+export interface DaemonHandle {
+	port: number;
+	memoryPort: number;
+	token: string;
+	url: string;
+	jobs: JobQueue;
+	close(): Promise<void>;
+}
+
+/** Read a running daemon's pid file, or null when it is missing, unreadable or holds something unusable. */
+export function readDaemonInfo(root: string): DaemonInfo | null {
+	try {
+		const info = JSON.parse(readFileSync(join(root, DAEMON_FILE), "utf8")) as DaemonInfo;
+		if (typeof info.pid !== "number" || typeof info.port !== "number" || typeof info.token !== "string") return null;
+		return info;
+	} catch {
+		return null;
+	}
+}
+
+export async function startFlypiDaemon(options: DaemonOptions): Promise<DaemonHandle> {
+	const log = options.log ?? ((line: string) => console.log(line));
+	// Named once: it goes in the health page, the pid file and the server's own version banner, and a
+	// daemon that reported three different versions would be a bug nobody could see.
+	const version = options.version ?? "dev";
+	const paths = options.paths;
+	const queue = new JobQueue(options.db);
+
+	// A claim still held at startup belongs to a process that is gone; leaving it locked would keep that
+	// kind of job out of the queue forever (`queueJob` will not re-queue an open one).
+	const reclaimed = queue.releaseStaleClaims();
+	if (reclaimed > 0) log(`flypi: released ${reclaimed} job claim(s) left by a dead process`);
+
+	// The other half of crash recovery: a turn left `running` finished nowhere. Say which ones. That is the
+	// backend's record, not the memory store's — see src/server/run-store.ts.
+	const interrupted = options.runs.reconcileInterrupted();
+	if (interrupted.length > 0) log(`flypi: ${interrupted.length} turn(s) were interrupted by the previous shutdown: ${interrupted.join(", ")}`);
+
+	// A stale index is queued as a job by reading it, which is the point: the daemon fixes it when idle.
+	const identity = options.store.indexIdentity();
+	if (identity.stale > 0) log(`flypi: ${identity.stale} stored vectors are not from ${identity.expected?.model ?? "the configured model"} — memory.reembed is queued`);
+
+	// A fresh install has no agent dir at all, and a missing config file reads as a broken install
+	// (`could not read …: ENOENT`) rather than as what it is: no model configured yet. Writing the empty pair
+	// turns that into the answer the settings panel can act on — an empty list with an add button — and a new
+	// conversation then names the half that is still missing.
+	const blank = ensureAgentConfig(paths);
+	if (blank.length > 0) log(`flypi: wrote ${blank.join(" and ")} — no model is configured yet (the Settings tab adds one)`);
+
+	const endpoint = memoryEndpoint(paths);
+	// The vault is in the memory database, so the daemon — the process that already owns that file — is the
+	// process that can write it: `flypi secret put` from another process only reads the same tables, and the
+	// sessions started here redact against what is in them (docs/secrets.md Phase 5.5). `write: true` on the
+	// handle it already holds is what lets a `saveSecrets` from the web UI land here rather than being refused
+	// as a read-only process; without it the Secrets tab can list and redact and never store.
+	const vault = openSecretVault(paths, { db: options.db, write: true });
+	const drift = vault.keyDrift();
+	if (drift.stale > 0 && !drift.reencryptQueued) {
+		options.store.queueJob(REENCRYPT_JOB, { payload: { reason: `${drift.stale} secret(s) sealed under an older key` } });
+		log(`flypi: ${drift.stale} secret(s) are still sealed under an older key — secrets.reencrypt is queued`);
+	}
+	// The port and token the agent's own `mcp.json` names, so the daemon cannot be listening on one port
+	// while `recall()` connects to another. Absent in the file means the server picks its own.
+	const memoryOptions = { store: options.store, token: endpoint.token, principal: "daemon" };
+	let memory: MemoryServerHandle;
+	// Naming the port in that file makes a later run bind that port again, and an ephemeral port can be
+	// someone else's by then. That one failure is recoverable — and an entry pointing at a port nothing
+	// answers on is exactly the silent breakage this path exists to prevent, so the file is corrected too.
+	let moved = false;
+	try {
+		memory = await startMemoryServer({ ...memoryOptions, port: endpoint.port });
+	} catch (error) {
+		if (endpoint.port === undefined || (error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;
+		log(`flypi: ${paths.mcpPath} names port ${endpoint.port}, which something else already holds — binding another port`);
+		memory = await startMemoryServer(memoryOptions);
+		moved = true;
+	}
+	// The port and token above live only in this process until they are in the file the agent reads, so a
+	// fresh install — which has no agent dir at all — gets one here, after the bind, saying where the server
+	// actually is. An existing entry is left alone: the file is the source of truth, not this process.
+	let adopted = false;
+	try {
+		adopted = ensureMemoryEntry(paths, memory.port, memory.token);
+		// Only the url, and only when the port it named was taken: the token, the exposure and everything
+		// else in the entry are the operator's, and rewriting one of those is how a `${VAR}` reference
+		// becomes a plaintext secret.
+		if (moved) applyConfigEdits(paths, { mcpServers: [{ name: "flypi-memory", url: `http://127.0.0.1:${memory.port}/mcp` }] });
+	} catch (error) {
+		// A file that will not parse belongs to the operator to fix; the daemon still serves everything else.
+		log(`flypi: cannot write the flypi-memory entry: ${(error as Error).message}`);
+	}
+	if (adopted) log(`flypi: wrote the flypi-memory entry in ${paths.mcpPath} — the agent will see the memory tools`);
+	// Anything else the file gets wrong is not ours to fix, and the note says which half is missing.
+	if (endpoint.note && !adopted) log(`flypi: ${endpoint.note}`);
+
+	const registry = new SessionRegistry({
+		root: paths.root,
+		createSession: options.createSession,
+		onRunStatus: (conversationId, status, info) => options.runs.setRunStatus(conversationId, status, info),
+		vault,
+	});
+
+	const startedAt = new Date().toISOString();
+	const serverOptions: FlypiServerOptions = {
+		registry,
+		...(options.host ? { host: options.host } : {}),
+		token: options.token,
+		uiDir: options.uiDir,
+		serverVersion: version,
+		health: () => {
+			// The stamp, not a fresh check: `/healthz` is polled by launchd/systemd and must not reach the
+			// network, and it is how `flypi status` and the page report an update without a round trip.
+			const stamp = readUpdateCheck(paths.root);
+			const newer = updateAvailable(stamp, version);
+			const ready = stagedUpdate(stamp, version);
+			return {
+				pid: process.pid,
+				startedAt: startedAt,
+				version,
+				memoryPort: memory.port,
+				jobs: queue.queued(),
+				...(newer ? { updateAvailable: newer } : {}),
+				...(ready ? { updateReady: ready } : {}),
+			};
+		},
+		scheduler: () => queue.snapshot(),
+		secrets: secretsApi(vault, paths),
+		// The Memory tab (docs/memory.md Phase 6). This process owns the memory database, so it is the one
+		// that can write what the browser edits — the same reason the vault is opened here with `write: true`.
+		memory: memoryApi(options.store, options.db),
+		interruptedRun: (sessionFile) => options.runs.interruptedFor(sessionFile),
+		// The page's "install now": the same path the idle rule takes, without the wait.
+		installUpdate: () => installStaged(),
+	};
+	let server: FlypiServerHandle;
+	// The same rule as the memory port above, and the reason the pid file is written after the bind rather
+	// than from the requested flags: what the file names has to be the port that is actually answering.
+	try {
+		server = await startFlypiServer({ ...serverOptions, port: options.port });
+	} catch (error) {
+		if (!options.portMayMove || options.port === undefined || (error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error;
+		log(`flypi: port ${options.port} — the one an earlier start used — is already taken; binding another, and \`flypi status\` says where`);
+		server = await startFlypiServer(serverOptions);
+	}
+
+	const infoPath = join(paths.root, DAEMON_FILE);
+	const info: DaemonInfo = {
+		pid: process.pid,
+		host: server.host,
+		port: server.port,
+		token: server.token,
+		memoryPort: memory.port,
+		startedAt,
+		version,
+	};
+	// 0600: the file carries the token that guards the agent server.
+	writeFileSync(infoPath, `${JSON.stringify(info, null, 2)}\n`, { mode: 0o600 });
+
+	// Is a newer flypi published, and is its package downloaded? After the bind, so a daemon that is not
+	// listening yet is not waiting on a network it may not have, and fire-and-forget, because a registry that
+	// cannot be reached is never a startup failure. A checkout is not an installed package: it updates with
+	// git, and the registry has never heard of it. Downloading is not installing — see `updatePass`.
+	const pkg = packageInfo();
+	// One check at a time: the job loop's first pass runs immediately, while the start-of-daemon check is
+	// still waiting on the registry.
+	let checking = false;
+	const checkUpdates = async () => {
+		if (checking) return;
+		checking = true;
+		try {
+			const previous = readUpdateCheck(paths.root);
+			const stamp = await checkForUpdate({ current: version, name: pkg.name });
+			// A package already on disk stays unless the step it was fetched for has changed.
+			stamp.download = keepDownload(stamp, previous);
+			if (stamp.next && stamp.dist && !stamp.download) {
+				const downloaded = await downloadUpdate({ root: paths.root, version: stamp.next, dist: stamp.dist });
+				if (downloaded.file) stamp.download = { version: stamp.next, file: downloaded.file, at: new Date().toISOString() };
+				else log(`flypi: ${stamp.next} is available but could not be downloaded: ${downloaded.error}`);
+			}
+			writeUpdateCheck(paths.root, stamp);
+			const step = updateAvailable(stamp, version);
+			if (step) {
+				// One step, and the reader is told when more than one is waiting: the ladder is walked a release
+				// at a time so each version's own schema upgrade runs against the schema it expects.
+				const further = stamp.latest && isNewer(step, stamp.latest) ? `; one step at a time — ${stamp.latest} is the newest published` : "";
+				log(`flypi: ${step} is available — this is ${version}; ${stamp.download ? "downloaded, and it installs the next time the daemon is idle (`flypi update` does it now)" : "not downloaded — `flypi update` installs it"}${further}`);
+			} else if (stamp.error) log(`flypi: no update check: ${stamp.error}`);
+		} finally {
+			checking = false;
+		}
+	};
+
+	// Install the downloaded package and restart through the CLI — the same path `flypi restart` takes, so the
+	// port and interface carry over and the shutdown is the normal one (pid file removed, sockets closed, a
+	// turn that was running left interrupted). The CLI stops this process, so the daemon does not exit here.
+	let installRefused = false;
+	const installPackage = (to: string, file: string): string | null => {
+		if (installRefused) return "this process is not the npm global package — install it yourself";
+		if (!isGlobalInstall()) {
+			// Say it once: the running code is not what `npm install -g` would replace, so installing would
+			// land somewhere else and the restart would come back on this version.
+			installRefused = true;
+			return "this process is not the npm global package — install it yourself";
+		}
+		log(`flypi: installing ${to} from ${file} — it restarts itself to run it`);
+		const npm = spawn("npm", installArgs(file), { stdio: "ignore" });
+		// Both listeners, or a missing `npm` on a launchd/systemd PATH is an unhandled `error` event — which
+		// would take the daemon down on the spot, the one thing an update attempt must never do.
+		npm.on("error", (error) => log(`flypi: the install could not start: ${error.message} — staying on ${version}`));
+		npm.on("exit", (code) => {
+			if (code !== 0) {
+				log(`flypi: the install failed (npm exited ${code}) — staying on ${version}, and it will try again after the next idle stretch`);
+				return;
+			}
+			const cli = spawn(process.execPath, [resolve(packageDir(), "scripts", "flypi.mjs"), "--root", paths.root, "restart"], { detached: true, stdio: "ignore" });
+			cli.on("error", (error) => log(`flypi: ${to} is installed, but the restart could not start: ${error.message}`));
+			cli.unref();
+			// Forget the answer: the version that comes back builds its own ladder from where it now stands,
+			// so the next step is one step, not the rest of an older answer.
+			clearUpdateCheck(paths.root);
+		});
+		return null;
+	};
+
+	// What the page's "install now" asks for: the staged package, or the newest published one if the daily
+	// check has not fetched it yet. Same guards, no idle wait — someone is attached, which is exactly the state
+	// the idle rule will not restart in, so this restart is asked for rather than stumbled into.
+	const installStaged = async (): Promise<string | null> => {
+		let stamp = readUpdateCheck(paths.root);
+		if (stamp?.next && stamp.dist && !stagedUpdate(stamp, version)) {
+			// "Now" can arrive before the daily check has fetched the package: fetch the step, not the top of
+			// the ladder.
+			const downloaded = await downloadUpdate({ root: paths.root, version: stamp.next, dist: stamp.dist });
+			if (downloaded.file) {
+				stamp = { ...stamp, download: { version: stamp.next, file: downloaded.file, at: new Date().toISOString() } };
+				writeUpdateCheck(paths.root, stamp);
+			}
+		}
+		const staged = stagedUpdate(stamp, version);
+		if (!staged) return "there is nothing downloaded to install — and the registry named no package to fetch";
+		if (!stamp?.download?.file) return "the downloaded update is not on disk any more";
+		return installPackage(staged, stamp.download.file);
+	};
+
+	// One pass of the update rule, from the job loop: re-check when the answer is stale, and install when the
+	// package is on disk and the daemon has been idle for a stretch — the sweep's idle (no page attached, no
+	// turn in flight) held for IDLE_BEFORE_INSTALL_MS, so a brief lull is never a restart.
+	let idleSince = 0;
+	// The same idle stretch installs extension packages (src/agent/packages.ts). They need no restart — the code
+	// is loaded per conversation — so the one difference is what happens afterwards: the conversations that are
+	// open are reloaded instead of the process.
+	let updatingPackages = false;
+	const updatePackages = async (sources: string[]) => {
+		if (updatingPackages) return;
+		updatingPackages = true;
+		try {
+			await applyPackageEdits(paths, { update: sources });
+			// The stamp is emptied for what was applied; the next day's check answers again from scratch. A source
+			// pi refuses to move (a pinned version, a registry that is down) stays recorded and is tried again.
+			writePackageCheck(paths.root, { checkedAt: new Date().toISOString(), updates: [] });
+			await registry.reloadExtensions();
+			log(`flypi: updated ${sources.length} extension package(s): ${sources.join(", ")}`);
+		} catch (error) {
+			log(`flypi: the extension update failed: ${(error as Error).message} — it will try again after the next idle stretch`);
+		} finally { updatingPackages = false; }
+	};
+	const checkPackages = async () => {
+		const check = await checkPackageUpdates(paths);
+		writePackageCheck(paths.root, check);
+		if (check.error) log(`flypi: no extension update check: ${check.error}`);
+		else if (check.updates.length) log(`flypi: ${check.updates.length} extension package(s) have updates — ${check.updates.join(", ")}; they install the next time the daemon is idle`);
+	};
+	const updatePass = (idle: boolean) => {
+		const stamp = readUpdateCheck(paths.root);
+		const pkgStamp = readPackageCheck(paths.root);
+		// A checkout is not an installed package, but the extensions it loads are: only flypi's own ladder is
+		// skipped there.
+		if (!pkg.checkout && dueForCheck(stamp)) void checkUpdates();
+		if (dueForPackageCheck(pkgStamp)) void checkPackages();
+		const staged = pkg.checkout ? null : stagedUpdate(stamp, version);
+		const pending = pkgStamp?.updates ?? [];
+		if ((!staged && pending.length === 0) || !idle) {
+			idleSince = 0;
+			return;
+		}
+		if (!idleSince) idleSince = Date.now();
+		if (Date.now() - idleSince < IDLE_BEFORE_INSTALL_MS) return;
+		// Packages first: they need no restart, and the flypi install below may take this process away.
+		if (pending.length) void updatePackages(pending);
+		if (staged && stamp?.download?.file) installPackage(staged, stamp.download.file);
+		// Start the clock again either way: a failed install retries after another idle stretch, not every pass.
+		idleSince = 0;
+	};
+	if (!pkg.checkout) void checkUpdates();
+	if (dueForPackageCheck(readPackageCheck(paths.root))) void checkPackages();
+
+	const handlers: Record<string, JobHandler> = {
+		// The kinds this build can run. `secrets.reencrypt` landed in Phase 5.5; `memory.consolidate` and
+		// `wiki.render` are Phase 6 — one line each in this map, and the queue needs nothing else.
+		"memory.reembed": async () => {
+			const result = await options.store.reembed();
+			// A new vector space is a different set of near pairs, so the merge pass runs again over it
+			// (docs/memory.md Phase 6: "re-run the merge pass after every `memory.reembed`"). Queued, not run
+			// inline: a sweep belongs to the same idle moment the re-embed did.
+			options.store.queueJob(CONSOLIDATE_JOB, { payload: { reason: "the vectors changed: near pairs are a different set now" } });
+			return `re-embedded ${result.embedded.length}, skipped ${result.skipped.length}${result.skipped.length ? `: ${result.skipped.map((row) => `#${row.id} ${row.why}`).join("; ")}` : ""}`;
+		},
+		"memory.consolidate": () => {
+			const sweep = consolidate(options.store);
+			// The wiki is a projection of what the sweep left behind, so it is re-rendered after a sweep and
+			// not on every write (docs/memory.md Phase 6).
+			options.store.queueJob(WIKI_JOB);
+			// The operator-facing line (`job_runs.detail` is what a person reads when a sweep ran), so a pass
+			// that found nothing to do says that instead of "merged 0 cluster(s) into nothing".
+			return `${sweep.merges.length ? `merged ${sweep.merges.length} cluster(s) into ${sweep.merges.map((merge) => `#${merge.survivor}`).join(", ")}` : "nothing to merge"}; promoted ${sweep.promotions.length}; rows ${sweep.rowsBefore} → ${sweep.rowsAfter}`;
+		},
+		"wiki.render": () => {
+			const wiki = renderWiki(options.store, options.db);
+			return `rendered ${wiki.pages} page(s), ${wiki.sections} section(s)`;
+		},
+		"secrets.reencrypt": async () => {
+			const result = vault.reencrypt();
+			return `re-sealed ${result.rows} secret(s) under v${result.keyVersion}`;
+		},
+	};
+	// A job is bookkeeping: it runs while nothing else is happening, and a pass that throws is a
+	// `failed` row in `job_runs`, not a restarted daemon.
+	const stopJobs = startJobLoop(queue, handlers, {
+		intervalMs: options.jobIntervalMs,
+		// The sweep's trigger, on flypi's conditions rather than a 3am cron (docs/memory.md Phase 6): the
+		// daemon is idle — no page attached and no turn in flight — and either enough rows have arrived since
+		// the last pass or the last one is a day old. A desktop app is off at 3am some nights, so a cron
+		// would simply not run.
+		beforePass: () => {
+			// The update rule and the sweep's trigger ask the same question — is the daemon idle? — so one
+			// answer per pass. The update installs only after a stretch of that idle (src/daemon/update.ts).
+			const idle = server.clients() === 0 && options.runs.runningTurns() === 0;
+			updatePass(idle);
+			const state = options.store.sweepState();
+			if (!sweepDue({ ...state, at: new Date().toISOString(), idle })) return;
+			options.store.queueJob(CONSOLIDATE_JOB, { payload: { reason: `${state.newRows} row(s) since the last sweep${state.lastSweepAt ? `, last ${state.lastSweepAt}` : ", never swept"}` } });
+		},
+		onPass: (ran) => ran.forEach((attempt) => log(`flypi: job ${attempt.kind} ${attempt.status}${attempt.detail ? `: ${attempt.detail}` : ""}`)),
+	});
+
+	return {
+		port: server.port,
+		memoryPort: memory.port,
+		token: server.token,
+		url: server.url,
+		jobs: queue,
+		close: async () => {
+			stopJobs();
+			// The vault shares this database handle, so its redaction wiring goes with it.
+			vault.close();
+			registry.dispose();
+			await server.close();
+			await memory.close();
+			rmSync(infoPath, { force: true });
+		},
+	};
+}
+
+/** Is the built UI there? `npm run build` first; a daemon without it is headless, which is allowed. */
+export function builtUi(root: string): string | undefined {
+	const dir = join(root, "dist", "ui");
+	return existsSync(dir) ? dir : undefined;
+}

package/src/daemon/jobs.ts

@@ -0,0 +1,202 @@
+/**
+ * The daemon's job queue (docs/architecture.md Phase 4.5).
+ *
+ * One `setTimeout` loop, no queue dependency, and no cron parser: `jobs.next_run_at` is enough. What
+ * makes it safe is the claim — a single `UPDATE … WHERE id = ? AND locked_at IS NULL` whose `changes`
+ * says who won — so two schedulers on one row cannot both run it, and a crash mid-run cannot lose a
+ * fact that was already written (the facts live in `memories`; a job only reorganises them).
+ *
+ * Every attempt is recorded in `job_runs`: what ran, when, whether it worked, and what it changed. The
+ * record is written when the attempt ends and carries the kind itself, because a job row closes when its
+ * work is done (`reembed()` deletes it once the index is clean) and the history of what it did is not
+ * part of that cleanup.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import { redactSecrets } from "../secrets/redact.ts";
+import type { JobRow, JobRunRow, SchedulerSnapshot } from "../server/protocol.ts";
+
+export interface Job {
+	id: number;
+	kind: string;
+	payload: unknown;
+}
+
+/** A job returns what it changed, for `job_runs.detail`. Throwing is a `failed` row, not a crash. */
+export type JobHandler = (job: Job) => string | void | Promise<string | void>;
+
+/** What one pass did, so a test (or the debug panel) can see it without reading the database. */
+export interface JobAttempt {
+	id: number;
+	kind: string;
+	status: "ok" | "failed";
+	detail?: string;
+}
+
+/** How long a job that ran waits before it is due again. Jobs are periodic maintenance, not a queue. */
+const RESCHEDULE_MS = 60 * 60 * 1000;
+
+const now = () => new Date().toISOString();
+
+/** How many jobs one pass takes. A pass is bounded so a huge backlog cannot starve a live turn. */
+const DUE_BATCH = 50;
+
+export class JobQueue {
+	constructor(
+		private readonly db: DatabaseSync,
+		private readonly clock: () => string = now,
+	) {}
+
+	/**
+	 * The jobs that are due and unclaimed, oldest first, as of this call. A pass works through this list
+	 * rather than asking again after each job: a failed job stays due, and asking again would put the pass
+	 * in a loop that never ends.
+	 */
+	dueNow(): Job[] {
+		const rows = this.db
+			.prepare("SELECT id, kind, payload FROM jobs WHERE locked_at IS NULL AND next_run_at <= ? ORDER BY id LIMIT ?")
+			.all(this.clock(), DUE_BATCH) as { id: number; kind: string; payload: string }[];
+		return rows.map((row) => ({ id: row.id, kind: row.kind, payload: JSON.parse(row.payload) as unknown }));
+	}
+
+	/**
+	 * The claim, exactly as the plan writes it. `changes` is the whole concurrency story: one caller gets
+	 * 1, everyone else gets 0 and moves on. Nothing is read-then-written, so there is no window to race in.
+	 */
+	claim(id: number, workerId: string): boolean {
+		return this.db.prepare("UPDATE jobs SET locked_by = ?, locked_at = ? WHERE id = ? AND locked_at IS NULL").run(workerId, this.clock(), id).changes === 1;
+	}
+
+	/** The queue's clock, so an attempt is stamped with the same clock that decided it was due. */
+	at(): string {
+		return this.clock();
+	}
+
+	/** Record one attempt — see the file header for why this happens after the run, not before. */
+	record(job: Job, startedAt: string, status: "ok" | "failed", detail?: string): void {
+		// A job that finished its work closes its own queue row (`reembed()` does), so the id may be gone by
+		// the time the attempt is recorded: link it when it is still there, and let the record stand alone
+		// when it is not. The kind is copied, so the history never loses what ran.
+		this.db
+			.prepare("INSERT INTO job_runs (job_id, kind, started_at, finished_at, status, detail) VALUES ((SELECT id FROM jobs WHERE id = ?), ?, ?, ?, ?, ?)")
+			.run(job.id, job.kind, startedAt, this.clock(), status, detail ?? null);
+	}
+
+	/**
+	 * Release the claim. A job that failed keeps its `next_run_at` (the plan's rule: a failed sweep is
+	 * retried on the next tick, not rescheduled into next week); a job that ran waits out `RESCHEDULE_MS`.
+	 */
+	release(id: number, { failed }: { failed: boolean }): void {
+		const at = this.clock();
+		this.db
+			.prepare("UPDATE jobs SET locked_by = NULL, locked_at = NULL, next_run_at = ? WHERE id = ?")
+			.run(failed ? at : new Date(Date.parse(at) + RESCHEDULE_MS).toISOString(), id);
+	}
+
+	/** How many jobs are waiting. `flypi status` prints it, and the health page carries it. */
+	queued(): number {
+		return Number((this.db.prepare("SELECT count(*) AS n FROM jobs").get() as unknown as { n: number }).n);
+	}
+
+	/**
+	 * On daemon start, any claim still held belongs to a process that is gone: the daemon is the only
+	 * writer (risk 3), and a row locked by nobody would never run again — while `queueJob` happily queues a
+	 * second row of the same kind beside it, because that one is not locked.
+	 */
+	releaseStaleClaims(): number {
+		return Number(this.db.prepare("UPDATE jobs SET locked_by = NULL, locked_at = NULL WHERE locked_at IS NOT NULL").run().changes);
+	}
+
+	/** What the scheduler tab shows: the queue, and the attempts that ran. Newest attempts first. */
+	snapshot(limit = 20): SchedulerSnapshot {
+		const jobs = this.db.prepare("SELECT kind, next_run_at, locked_by FROM jobs ORDER BY next_run_at, id").all() as unknown as { kind: string; next_run_at: string; locked_by: string | null }[];
+		// `job_runs.kind` is the record's own copy, so an attempt keeps its name after its queue row closes.
+		const runs = this.db
+			.prepare("SELECT job_runs.kind AS recorded, jobs.kind AS queued, job_runs.status, job_runs.started_at, job_runs.finished_at, job_runs.detail FROM job_runs LEFT JOIN jobs ON jobs.id = job_runs.job_id ORDER BY job_runs.id DESC LIMIT ?")
+			.all(limit) as unknown as { recorded: string; queued: string; status: string; started_at: string; finished_at: string | null; detail: string | null }[];
+		return {
+			jobs: jobs.map((job) => ({ kind: job.kind, nextRunAt: job.next_run_at, running: job.locked_by !== null } satisfies JobRow)),
+			jobRuns: runs.map((run) => ({
+				kind: run.recorded || run.queued,
+				status: run.status as JobRunRow["status"],
+				startedAt: run.started_at,
+				...(run.finished_at ? { finishedAt: run.finished_at } : {}),
+				...(run.detail ? { detail: run.detail } : {}),
+			})),
+		};
+	}
+}
+
+/**
+ * One pass: claim and run every job that is due, and record each attempt.
+ *
+ * A kind with no handler here is a `failed` row saying so: the queue is not the place that knows which
+ * phases have landed, and a job nobody runs should be visible in the scheduler tab rather than silently
+ * open. `memory.consolidate` and `wiki.render` get their handlers in Phase 6, `secrets.reencrypt` in
+ * Phase 5.5 — registering one is one line in that phase's `handlers` map.
+ */
+export async function runDueJobs(queue: JobQueue, handlers: Record<string, JobHandler>): Promise<JobAttempt[]> {
+	// The worker is this process: that is what makes a claim left behind recognisably one that a dead
+	// process abandoned.
+	const workerId = process.pid.toString();
+	const ran: JobAttempt[] = [];
+	for (const job of queue.dueNow()) {
+		// Someone else claimed it first: whoever won will run it. Not our job — literally.
+		if (!queue.claim(job.id, workerId)) continue;
+		const startedAt = queue.at();
+		let status: "ok" | "failed" = "ok";
+		let detail: string | undefined;
+		try {
+			const handler = handlers[job.kind];
+			if (!handler) throw new Error(`no handler for ${job.kind}: that phase has not landed`);
+			detail = (await handler(job)) ?? undefined;
+		} catch (error) {
+			status = "failed";
+			detail = (error as Error).message;
+		}
+		// A failed job's message quotes the command it failed, and that command may have had a credential in
+		// it. `job_runs.detail` is what an operator reads, so it is redacted on the way in (docs/secrets.md).
+		if (detail !== undefined) detail = redactSecrets(detail);
+		queue.record(job, startedAt, status, detail);
+		queue.release(job.id, { failed: status === "failed" });
+		ran.push({ id: job.id, kind: job.kind, status, ...(detail ? { detail } : {}) });
+	}
+	return ran;
+}
+
+/**
+ * The loop: one `setTimeout`, never `setInterval` — a pass that outlives its interval cannot overlap
+ * itself, and an unref'd timer never holds the process open on its own.
+ */
+export function startJobLoop(
+	queue: JobQueue,
+	handlers: Record<string, JobHandler>,
+	options: { intervalMs?: number; onPass?: (ran: JobAttempt[]) => void; beforePass?: () => void } = {},
+): () => void {
+	const intervalMs = options.intervalMs ?? 60_000;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let stopped = false;
+	const tick = () => {
+		// The pass can be told what to queue on its way in: the daemon asks "is a sweep due?" here, so the
+		// idle check happens at the moment the queue is about to run rather than on another timer that could
+		// decide while a turn was in flight.
+		try {
+			options.beforePass?.();
+		} catch (error) {
+			console.error(`flypi jobs: ${(error as Error).message}`);
+		}
+		void runDueJobs(queue, handlers)
+			.then((ran) => options.onPass?.(ran))
+			.catch((error) => console.error(`flypi jobs: ${(error as Error).message}`))
+			.finally(() => {
+				if (stopped) return;
+				timer = setTimeout(tick, intervalMs);
+				timer.unref();
+			});
+	};
+	timer = setTimeout(tick, 0);
+	timer.unref();
+	return () => {
+		stopped = true;
+		if (timer) clearTimeout(timer);
+	};
+}