@edgehero/pi-dispatch 4.3.1 → 5.1.0

package/src/console-audit.mjs

@@ -0,0 +1,604 @@
+/**
+ * The operator console's audit log (issue #640; INT-CONSOLE-AUDIT-LOG). One JSON row per line in
+ * `PI_LOGS_DIR/console-audit/YYYY-MM.jsonl` (the UTC month of the row's `at`), directory 0700, files 0600, appended with
+ * O_APPEND. A worker subpath (`@edgehero/pi-dispatch/console-audit`) and not an admin module, because doctor verifies the
+ * chain and the worker cannot import the admin.
+ *
+ * TAMPER-EVIDENT, NOT TAMPER-PROOF. Every row carries `seq` (one more than the row before it) and `prev` (sha256 hex of
+ * the previous row's raw line, without its newline; `null` only for the very first row ever written). Changing,
+ * removing or moving a row breaks the link of the row AFTER it, which `verifyConsoleAudit` names. Named residuals: the
+ * account that runs the console can rewrite the whole chain from any row on (nothing here is signed by a key it does not
+ * hold), and a change to the LAST row has no successor to break, so it shows only once the next row is written.
+ *
+ * The head is recovered from the newest month file on EVERY append, not cached after the first: `pi-dispatch-console
+ * token add` (a separate process) appends to the same chain while `serve` runs, and a cached head in `serve` would then
+ * fork the chain at its next row. The tail read is bounded (`TAIL_BYTES`), so a flood of refusals costs a constant read
+ * per row, not one that grows with the file. The head read and the write happen under a short append lock
+ * (`APPEND_LOCK`, created exclusively with a token of its own, removed in `finally` only while it still holds that token), so `serve` and a CLI command appending at once take turns
+ * instead of both writing a row with the same `seq` and `prev`. A lock whose holder pid is dead is taken over; a lock
+ * still held after `LOCK_WAIT_MS` makes the append throw, which refuses the write (see `withAppendLock`).
+ *
+ * Rows come from the console (`serve`), its CLI (actor role `shell`) and, since issue #642, the panel: the `/dispatch` TUI
+ * and the pi extension's tools write theirs as actor role `panel` (`admin/src/audited-write.mjs`). The role is an escaped
+ * string like the name, not a closed set. A write row may also carry `kind` (which write), `reserve` (micro-dollars a
+ * paid action holds) and `count` (a bulk action's size), all optional: a row without them verifies as it always did.
+ *
+ * ACROSS VERSIONS (issue #761): the writer writes only the actions and outcomes this build lists, and the verifier links
+ * any row whose action and outcome have their shape (`CONSOLE_AUDIT_ACTION_RE`, `CONSOLE_AUDIT_OUTCOME_RE`), so a chain
+ * a newer console wrote into is still intact here, and an intact chain counts the rows with a value it does not know as
+ * `unknown`. A row carries no version: a version an older verifier refused would bring back the false "chain is broken"
+ * this rule removes. Keys a row holds beyond the ones judged here are not judged, as before.
+ *
+ * A row is mirrored to Valkey (`console:audit`, LPUSH then LTRIM, the `alloc:log` precedent in `allocation.mjs`) as a
+ * VIEW: the file is the record, and a mirror that fails loses nothing the file does not hold.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { escapeControls } from "./projects.mjs";
+
+export const CONSOLE_AUDIT_DIR = "console-audit";
+export const CONSOLE_AUDIT_KEY = "console:audit";
+export const CONSOLE_AUDIT_ACTIONS = Object.freeze(["login", "login-failed", "login-code", "logout", "refused", "write", "write-applied", "token-added", "token-revoked", "token-rotated", "sessions-ended", "serve-started", "login-device", "device-remembered", "device-ended"]);
+export const CONSOLE_AUDIT_OUTCOMES = Object.freeze(["ok", "refused", "failed"]);
+// A string field's cap, in code points, AFTER its controls are written out: a row stays small enough for the bounded tail
+// read below whatever a caller hands in (a Host header, a refusal reason), and no field can bury the others.
+export const CONSOLE_AUDIT_FIELD_MAX = 200;
+// A write row's optional action name (issue #642: the console's action table and the panel's own writes), one short
+// lowercase word with dashes: a closed charset rather than an escaped free string, so a reader can group rows by it and
+// no caller can carry text in it. `action` itself stays the closed vocabulary above; `kind` only says which write.
+export const CONSOLE_AUDIT_KIND_RE = /^[a-z0-9-]{1,40}$/;
+// The SHAPE of an action and of an outcome (issue #761): what every value either list above has ever held, and what a
+// value a later release adds must keep (a test holds every member to it). The writer stays closed (`auditRowBody` writes
+// only the lists' members); the verifier links a row whose action or outcome it does not know but that has this shape,
+// and counts it as `unknown`: such a row is shaped and linked, which is what a newer console writes, so it is not
+// damage. Refusing it, as the verifier did before, reported an intact chain as broken at the first row a newer console
+// wrote, and the older console then said "a row was changed" about a row nobody changed. Letter first, like every value
+// so far, and `kind`'s cap of 40.
+export const CONSOLE_AUDIT_ACTION_RE = /^[a-z][a-z0-9-]{0,39}$/;
+export const CONSOLE_AUDIT_OUTCOME_RE = /^[a-z][a-z0-9-]{0,39}$/;
+// Only names of this shape are the log's: the reaper and the verifier never touch or read anything else an operator put
+// in the directory.
+const MONTH_FILE_RE = /^\d{4}-\d{2}\.jsonl$/;
+// The bounded read of a file's end, for its last line. A row is at most ten capped fields of 200 code points (4 bytes
+// each in UTF-8 at worst) plus its keys, far under this.
+const TAIL_BYTES = 65536;
+// The append lock, beside the month files (the reaper and the verifier only look at month-file names).
+export const APPEND_LOCK = ".append.lock";
+const LOCK_WAIT_MS = 2000;
+const LOCK_PAUSE = new Int32Array(new SharedArrayBuffer(4));
+
+function processAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err?.code === "EPERM";
+	}
+}
+
+/**
+ * Hold `dir`'s append lock while `fn` runs. Sync, like the append it guards; waits in short sleeps, never spins hot.
+ *
+ * The lock file holds its holder's pid and a random token (`<pid> <hex>`), and a lock is STALE only when that pid is dead
+ * (`alive`, the same rule as the console's single-instance lock). Never by age: an age is the filesystem's mtime against
+ * this process's clock, two clocks, and a skew between them (or the clock-shifted CI run) would make every live lock look
+ * stale and let two writers in at once, which is the fork this lock exists to prevent. The audit directory is local to
+ * the host whose console writes it, so a pid names a process here. A lock still held, or still empty (a writer between
+ * its create and its pid), after `LOCK_WAIT_MS` makes the append throw, which refuses the write it was recording.
+ *
+ * The token is what makes a removal safe. Two writers can both judge the same dead lock: the first removes it and
+ * creates its own, and a second that removed by path would then remove that FRESH lock and both would append with the
+ * same `seq` and `prev`. So a takeover re-reads the lock just before it removes it and removes it only while it still
+ * holds exactly the stale text that was judged dead, and the `finally` removes the lock only while it still holds this
+ * writer's own token. Named residual: the window between that re-read and the unlink (no portable compare-and-unlink
+ * exists on a path), in which a writer that judged the same dead lock can create its fresh one and lose it to this
+ * unlink. Two takers have to read the same dead text and interleave inside that window, after a holder crashed.
+ */
+function withAppendLock(dir, fs, fn, alive) {
+	const lock = join(dir, APPEND_LOCK);
+	const token = `${process.pid} ${randomBytes(8).toString("hex")}\n`;
+	const readLock = () => {
+		try {
+			return fs.readFileSync(lock, "utf8");
+		} catch (err) {
+			if (err?.code === "ENOENT") return null;
+			throw err;
+		}
+	};
+	const started = Date.now();
+	for (;;) {
+		try {
+			fs.writeFileSync(lock, token, { flag: "wx", mode: 0o600 });
+			break;
+		} catch (err) {
+			if (err?.code !== "EEXIST") throw err;
+		}
+		const stale = readLock();
+		if (stale === null) continue;
+		const holder = Number.parseInt(stale, 10);
+		if (Number.isSafeInteger(holder) && holder > 0 && !alive(holder)) {
+			// Only the text judged dead goes: another writer may have taken it over since, and its fresh lock is live.
+			if (readLock() === stale) {
+				try {
+					fs.unlinkSync(lock);
+				} catch (err) {
+					if (err?.code !== "ENOENT") throw err;
+				}
+			}
+			continue;
+		}
+		if (Date.now() - started > LOCK_WAIT_MS) {
+			throw Object.assign(new Error(`the console audit log is locked by another writer (${lock}${Number.isSafeInteger(holder) ? `, pid ${holder}` : ""}); try again, or remove the file if no console command is running`), { code: "EAUDITLOCKED" });
+		}
+		Atomics.wait(LOCK_PAUSE, 0, 0, 10);
+	}
+	try {
+		return fn();
+	} finally {
+		try {
+			// A lock that no longer holds our token was taken over (we were judged dead, or removed by hand): not ours.
+			if (readLock() === token) fs.unlinkSync(lock);
+		} catch {
+			// Already gone or unreadable: nothing of ours to remove.
+		}
+	}
+}
+
+function sha256(text) {
+	return createHash("sha256").update(text).digest("hex");
+}
+
+/**
+ * A string field as it is stored: controls and the other characters that change what a reader SEES written out as
+ * `\u{XXXX}` (the worker's `escapeControls`, the same class the admin panel scrubs), then capped. Written out, not
+ * deleted: an audit row that silently lost a character would hide exactly what a forged Host header tried to smuggle.
+ */
+function auditString(value, field) {
+	if (typeof value !== "string") throw new Error(`console audit row: ${field} must be a string`);
+	const text = escapeControls(value);
+	const points = [...text];
+	return points.length > CONSOLE_AUDIT_FIELD_MAX ? points.slice(0, CONSOLE_AUDIT_FIELD_MAX).join("") : text;
+}
+
+/** Watch rows name the other participant without admitting an arbitrary peer object into the journal. */
+export function consoleAuditDriver(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).sort().join() !== "name,role,session" || !/^[a-z0-9][a-z0-9._-]{0,31}$/.test(value.name ?? "") || value.role !== "operator" || !/^[a-f0-9]{12}$/.test(value.session ?? "")) return null;
+	return { name: value.name, role: value.role, session: value.session };
+}
+const WATCH_AUDIT_KINDS = new Set(["sandbox-watch-opening", "sandbox-watch-start", "sandbox-watch-end"]);
+/** The row as stored, from a caller's input, or a throw naming the field that is wrong (the caller refuses its write). */
+function auditRowBody(input) {
+	if (input === null || typeof input !== "object") throw new Error("console audit row must be an object");
+	const { actor, action, outcome } = input;
+	if (!CONSOLE_AUDIT_ACTIONS.includes(action)) throw new Error(`console audit row: unknown action ${JSON.stringify(escapeControls(String(action)))} (one of ${CONSOLE_AUDIT_ACTIONS.join(", ")})`);
+	if (!CONSOLE_AUDIT_OUTCOMES.includes(outcome)) throw new Error(`console audit row: unknown outcome ${JSON.stringify(escapeControls(String(outcome)))} (one of ${CONSOLE_AUDIT_OUTCOMES.join(", ")})`);
+	if (actor === null || typeof actor !== "object") throw new Error("console audit row: actor must be an object with name, role and session");
+	const body = {
+		actor: {
+			name: auditString(actor.name, "actor.name"),
+			role: auditString(actor.role, "actor.role"),
+			session: actor.session === null || actor.session === undefined ? null : auditString(actor.session, "actor.session"),
+		},
+		action,
+	};
+	const optional = (field) => (input[field] === undefined || input[field] === null ? {} : { [field]: auditString(input[field], field) });
+	const absent = (field) => input[field] === undefined || input[field] === null;
+	if (!absent("kind") && !(typeof input.kind === "string" && CONSOLE_AUDIT_KIND_RE.test(input.kind))) throw new Error("console audit row: kind must be 1 to 40 of a-z, 0-9 and -");
+	if (!absent("reserve") && !(Number.isSafeInteger(input.reserve) && input.reserve >= 0)) throw new Error("console audit row: reserve must be a non-negative whole number of micro-dollars");
+	if (!absent("count") && !(Number.isSafeInteger(input.count) && input.count >= 1)) throw new Error("console audit row: count must be a positive whole number");
+	const number = (field) => (absent(field) ? {} : { [field]: input[field] });
+	const driver = consoleAuditDriver(input.driver);
+	if (WATCH_AUDIT_KINDS.has(input.kind) ? !driver : !absent("driver")) throw new Error("console audit row: driver is required only on watch attachment rows");
+	// In reading order: who, did what (and which write), to what, how it went, why, what it holds and how many, then the
+	// digests and the ticket that tie it to a change.
+	return { ...body, ...(absent("kind") ? {} : { kind: input.kind }), ...optional("target"), outcome, ...optional("reason"), ...number("reserve"), ...number("count"), ...optional("beforeDigest"), ...optional("afterDigest"), ...optional("ticket"), ...(driver ? { driver } : {}) };
+}
+
+/**
+ * Whether a parsed row's optional issue #642 fields, where present, are what `auditRowBody` writes: `kind` in its
+ * charset, `reserve` a non-negative safe integer, `count` a positive one. A row without them is a row from before them,
+ * and is fine.
+ */
+function optionalFieldsWellFormed(row) {
+	if (row.kind !== undefined && !(typeof row.kind === "string" && CONSOLE_AUDIT_KIND_RE.test(row.kind))) return false;
+	if (row.reserve !== undefined && !(Number.isSafeInteger(row.reserve) && row.reserve >= 0)) return false;
+	if (row.count !== undefined && !(Number.isSafeInteger(row.count) && row.count >= 1)) return false;
+	return true;
+}
+
+/** Whether a parsed row's action or outcome is a string of `re`'s shape (issue #761). */
+function shapedWord(value, re) {
+	return typeof value === "string" && re.test(value);
+}
+
+/** The `YYYY-MM.jsonl` names in `dir`, oldest first; [] when the directory does not exist. Other errors throw. */
+function monthFiles(dir, fs) {
+	let names;
+	try {
+		names = fs.readdirSync(dir);
+	} catch (err) {
+		if (err?.code === "ENOENT") return [];
+		throw err;
+	}
+	return names.filter((n) => MONTH_FILE_RE.test(n)).sort();
+}
+
+/** The last non-empty line of a file, read from its end, or null for an empty file. */
+function lastLine(path, fs) {
+	const fd = fs.openSync(path, "r");
+	try {
+		const size = fs.fstatSync(fd).size;
+		const length = Math.min(size, TAIL_BYTES);
+		const buf = Buffer.alloc(length);
+		let got = 0;
+		while (got < length) {
+			const n = fs.readSync(fd, buf, got, length - got, size - length + got);
+			if (n === 0) break;
+			got += n;
+		}
+		const lines = buf.subarray(0, got).toString("utf8").split("\n").filter((l) => l !== "");
+		if (lines.length === 0) return null;
+		// A tail read that started mid-file and holds one partial line cannot vouch for it: refuse rather than chain a
+		// fragment.
+		if (lines.length === 1 && size > length) throw new Error(`the console audit file ${path} ends in a line longer than ${TAIL_BYTES} bytes; run \`pi-dispatch-console audit verify\``);
+		return lines[lines.length - 1];
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+/**
+ * The chain's head on disk: `{ seq, hash, month }`, seq 0 and hash null when no row exists. Read from the newest month
+ * file's last line, so a row in a new month links to the old month's last. A newest file that exists but is empty is
+ * skipped for the one before it (a crash between create and write leaves one).
+ */
+function readHead(dir, fs) {
+	const files = monthFiles(dir, fs);
+	for (let i = files.length - 1; i >= 0; i--) {
+		const line = lastLine(join(dir, files[i]), fs);
+		if (line === null) continue;
+		let row;
+		try {
+			row = JSON.parse(line);
+		} catch {
+			row = null;
+		}
+		if (row === null || typeof row !== "object" || !Number.isInteger(row.seq) || row.seq < 1) {
+			throw new Error(`the last line of the console audit file ${join(dir, files[i])} is not an audit row, so the next row cannot link to it; run \`pi-dispatch-console audit verify\` and move the damaged file aside`);
+		}
+		return { seq: row.seq, hash: sha256(line), month: files[i].slice(0, 7) };
+	}
+	return { seq: 0, hash: null, month: null };
+}
+
+/** Refuse a directory or file that is a symlink: the console's own account writes here, and a link would aim it elsewhere. */
+function refuseLink(path, fs, what) {
+	let st;
+	try {
+		st = fs.lstatSync(path);
+	} catch (err) {
+		if (err?.code === "ENOENT") return;
+		throw err;
+	}
+	if (st.isSymbolicLink()) throw new Error(`the console audit ${what} ${path} is a symlink; replace it with a real ${what} owned by this account`);
+}
+
+/**
+ * The audit writer. `append(row)` is SYNC and THROWS on any failure (a bad row, a full disk, a damaged head): the caller
+ * refuses the write it was about to make, because a change the record does not hold is the outcome this log exists to
+ * prevent. Returns the stored row. `head()` is the chain's head on disk, `{ seq, hash }`.
+ */
+export function makeConsoleAudit({ logsDir, fs = nodeFs, now = () => Date.now(), alive = processAlive }) {
+	const dir = join(logsDir, CONSOLE_AUDIT_DIR);
+	return {
+		dir,
+		append(input) {
+			const body = auditRowBody(input);
+			refuseLink(dir, fs, "directory");
+			fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+			return withAppendLock(dir, fs, () => {
+				const head = readHead(dir, fs);
+				const at = new Date(now()).toISOString();
+				// A clock that stepped back across a month boundary still appends to the NEWEST file: the chain is read file by
+				// file in name order, and a row written into an older file would sit before rows it follows.
+				const month = head.month !== null && head.month > at.slice(0, 7) ? head.month : at.slice(0, 7);
+				const row = { at, seq: head.seq + 1, prev: head.hash, ...body };
+				const path = join(dir, `${month}.jsonl`);
+				refuseLink(path, fs, "file");
+				fs.appendFileSync(path, `${JSON.stringify(row)}\n`, { flag: "a", mode: 0o600 });
+				return row;
+			}, alive);
+		},
+		head() {
+			const { seq, hash } = readHead(dir, fs);
+			return { seq, hash };
+		},
+	};
+}
+
+/**
+ * Walk the chain, oldest file first: `{ ok: true, rows, startsAt }` or `{ ok: false, rows, broken: { file, line, reason } }`
+ * with the FIRST broken link (`line` is 1-based within `file`; `rows` counts the rows read before it). The oldest
+ * surviving row's `prev` cannot be checked once the reaper took the file before it, so it is not: a chain that starts
+ * there is reported as `startsAt: { file, seq }`, not as broken. `startsAt` is null when the chain starts at its very
+ * first row (seq 1, prev null). Never throws: an unreadable directory or file is the broken link.
+ *
+ * The intact shape also carries `unknown: n` when n of its `rows` have an action or outcome this build does not know but
+ * of the shape the console writes (issue #761: shaped and linked, which a newer console writes), and only then. A broken
+ * result never carries it: the row before a break whose line shows no matching `prev` passed its own checks and is
+ * counted in `rows`, yet nothing vouches for it, so a count there would vouch for a row the chain does not, and no
+ * reader shows it for a broken chain.
+ *
+ * `withLast` (issue #737, the console's audit screen) adds three fields to both shapes, for a reader that marks rows by
+ * their place (the place is the one thing that tells two rows apart reliably: a damaged line has no seq, and a tampered
+ * file can hold one seq twice):
+ *
+ *   - `last: { file, line, seq }`, the last row the chain VOUCHES for (null when none). A row is vouched for only by
+ *     the line after it, when that line's `prev` matches the row's hash. On an intact chain `last` is the newest row
+ *     walked, though no line vouches for that one yet (none follows it). At a break whose line does not show a
+ *     `prev` that matches the row before it (it does not parse, its `prev` is not a hash or null, or its `prev` is
+ *     another hash), `last` is the row before THAT one: an edit to the row before the break leaves that row's own line
+ *     well formed and moves only its hash, so a line after it that does not show a matching `prev` cannot tell an
+ *     edited row from an intact one, and the row before the break is not vouched for. That is judged before the line's
+ *     action, outcome and fields are, so an unknown action does not hide it. Only a line whose `prev` matched and that
+ *     then fails another check (its seq, action, outcome or fields) is damaged alone, and the row before it stays
+ *     vouched for. A file that cannot be read stops the walk, and the row before it stays as the newest row read.
+ *   - `suspect: { file, line, seq }`, that row before a break whose line does not show a matching `prev`, which the
+ *     chain walked but cannot vouch for, or null for every other result.
+ *   - `files: [{ file, seq, rows }]`, oldest first: each month file the walk passed a row in, the seq of its first row
+ *     (always its line 1: a line that does not pass ends the walk) and how many rows the walk passed in it. Row `s` of an
+ *     entry is then at line `s - seq + 1` of its file, so the screen can open the page that holds a row by its number
+ *     without walking every row written since (it reads that place and checks the seq there, falling back to the walk
+ *     when the file no longer agrees). One entry a month, so it stays small.
+ *
+ * Opt-in, so the result doctor, the CLI and the tests compare whole stays as it was.
+ */
+export function verifyConsoleAudit({ logsDir, fs = nodeFs, withLast = false }) {
+	const dir = join(logsDir, CONSOLE_AUDIT_DIR);
+	let last = null; // { file, line, seq } of the last good row, for `withLast`
+	let beforeLast = null; // the good row before `last`, which a line that does not link to `last` leaves as the last vouched for
+	const index = []; // { file, seq, rows } per month file the walk passed a row in, for `withLast`
+	let unknown = 0; // rows that passed every check with an action or outcome this build does not know (issue #761)
+	// `unknown` only on an intact chain and only when some row has it (issue #761), so a chain of known rows answers
+	// exactly as it always did (doctor, the CLI and the tests compare this result whole), and a broken one never counts
+	// the row before its break, which nothing vouches for.
+	const shaped = (result, unlinked = false) => {
+		const counted = result.ok && unknown > 0 ? { ...result, unknown } : result;
+		if (!withLast) return counted;
+		return unlinked ? { ...counted, last: beforeLast, suspect: last, files: index } : { ...counted, last, suspect: null, files: index };
+	};
+	let files;
+	try {
+		files = monthFiles(dir, fs);
+	} catch (err) {
+		return shaped({ ok: false, rows: 0, broken: { file: null, line: 0, reason: `the audit directory ${dir} cannot be read (${err?.code ?? "error"})` } });
+	}
+	let rows = 0;
+	let prior = null; // { seq, hash } of the last good row
+	let startsAt = null;
+	for (const file of files) {
+		let i = -1;
+		try {
+			for (const line of fileLines(fs, join(dir, file))) {
+				i += 1;
+				let row;
+				try {
+					row = JSON.parse(line);
+				} catch {
+					row = undefined;
+				}
+				// Whether this line vouches for the row before it (`withLast`, see above), decided before anything else about
+				// the line is judged. `prior.hash` is a sha256, so only a well-formed `prev` can equal it. The first row walked
+				// has no row before it to vouch for.
+				const linked = prior !== null && row?.prev === prior.hash;
+				const broken = (reason) => shaped({ ok: false, rows, broken: { file, line: i + 1, reason } }, !linked);
+				if (row === undefined) return broken("the line is not a JSON row (damaged, or written by something else)");
+				if (row === null || typeof row !== "object" || Array.isArray(row) || !Number.isInteger(row.seq) || row.seq < 1 || !(row.prev === null || (typeof row.prev === "string" && /^[0-9a-f]{64}$/.test(row.prev)))) {
+					return broken("the row has no valid seq and prev");
+				}
+				// Known, or of the shape a newer console's value keeps (issue #761): linked either way, and an unknown one is
+				// counted below once the row passed every other check. Judged after `linked`, so an edited unknown row is still
+				// named by the broken link of the row after it, exactly as an edited known row is.
+				const known = CONSOLE_AUDIT_ACTIONS.includes(row.action) && CONSOLE_AUDIT_OUTCOMES.includes(row.outcome);
+				if (!known && !(shapedWord(row.action, CONSOLE_AUDIT_ACTION_RE) && shapedWord(row.outcome, CONSOLE_AUDIT_OUTCOME_RE))) {
+					return broken("the row's action or outcome is not of the shape the console writes");
+				}
+				if (WATCH_AUDIT_KINDS.has(row.kind) ? !consoleAuditDriver(row.driver) : row.driver !== undefined) return broken("the row's watch driver is not one the console writes");
+				if (!optionalFieldsWellFormed(row)) return broken("the row's kind, reserve or count is not one the console writes");
+				if (prior === null) {
+					if (row.prev === null) {
+						if (row.seq !== 1) return broken(`the first row has no prev but seq ${row.seq}; the chain's start was changed`);
+					} else {
+						// The rows before it were reaped (retention), or removed: the two look alike, so the start is reported.
+						startsAt = { file, seq: row.seq };
+					}
+				} else {
+					if (!linked) return broken(`prev does not match the row before it (seq ${prior.seq}): a row was changed, removed or moved`);
+					if (row.seq !== prior.seq + 1) return broken(`seq ${row.seq} follows seq ${prior.seq}`);
+				}
+				prior = { seq: row.seq, hash: sha256(line) };
+				beforeLast = last;
+				last = { file, line: i + 1, seq: row.seq };
+				if (index.length === 0 || index[index.length - 1].file !== file) index.push({ file, seq: row.seq, rows: 0 });
+				index[index.length - 1].rows += 1;
+				rows += 1;
+				if (!known) unknown += 1;
+			}
+		} catch (err) {
+			return shaped({ ok: false, rows, broken: { file, line: i + 1, reason: `the file cannot be read (${err?.code ?? "error"})` } });
+		}
+	}
+	return shaped({ ok: true, rows, startsAt });
+}
+
+/** The most rows one `readConsoleAudit` call returns, whatever it is asked for. */
+export const CONSOLE_AUDIT_READ_MAX = 500;
+
+/**
+ * An audit cursor, `YYYY-MM:<line>`: the month file's name without `.jsonl` and a 1-based line number in it (see
+ * `readConsoleAudit`). The line is at most 16 digits and must be a safe integer.
+ */
+export const CONSOLE_AUDIT_CURSOR_RE = /^(\d{4}-\d{2}):([1-9]\d{0,15})$/;
+
+/**
+ * The newest audit rows first, for the console's audit screen (issue #641): `{ rows, next }`, or `{ rows: [], next: null,
+ * unreadable }` when the directory cannot be listed or `before` is not a cursor. Never throws.
+ *
+ * Each line is parsed and returned as it is stored. A line that is not an audit row (not JSON, not an object, no
+ * positive integer `seq`) is NOT skipped: it comes back as `{ broken: true, file, line }` (`line` 1-based in `file`), in
+ * its place, because an audit screen that quietly drops a damaged line hides exactly what `verifyConsoleAudit` exists to
+ * name. A file that cannot be read (or stops being readable part-way) is one such entry with `line: 0`.
+ *
+ * THE CURSOR IS A PLACE IN THE FILES, NOT A ROW: `YYYY-MM:<line>` (`CONSOLE_AUDIT_CURSOR_RE`), the month file and the
+ * 1-based line an entry was read from (a read failure's entry sits one line past the last line read). `before` returns
+ * only entries above it in file order (an older month file, or the same file at a lower line), and `next` is the last
+ * returned entry's cursor, or null when nothing older exists. Every entry has its own place, so a page can end on any
+ * one of a run of damaged lines and the next page starts at the line under it. A place stays put because the files only
+ * ever grow at the end of the newest one (the reaper takes whole files). The seq was the cursor once, with a damaged
+ * line at a half step beside the good row before it; it was refuted, because two damaged lines in a row shared one half
+ * step (a page ending on the first skipped the second) and a file's leading damaged line shared it with the previous
+ * file's trailing one.
+ *
+ * BOUNDED MEMORY: files are walked newest first, each through the chunked `fileLines`, and only the newest `limit`
+ * qualifying entries of a file are held (a ring buffer), so a month file of any size costs `limit` entries of memory. A
+ * file newer than the cursor is not opened, and the cursor's own file is read only up to the cursor's line.
+ */
+export function readConsoleAudit({ logsDir, limit = 100, before = null, fs = nodeFs, positions = false } = {}) {
+	const cap = Math.min(CONSOLE_AUDIT_READ_MAX, Math.max(1, Number.isFinite(limit) ? Math.floor(limit) : 100));
+	// `positions` (issue #737) adds each entry's own place, `YYYY-MM:<line>`, parallel to `rows`: the console's audit screen
+	// compares it with `verifyConsoleAudit`'s `broken` and `last` to mark a row damaged, not verified or not yet checked,
+	// and a row's id on the page is built from it when its seq cannot be one. Opt-in, so the shape callers compare whole is
+	// unchanged.
+	const unread = (unreadable) => (positions ? { rows: [], next: null, positions: [], unreadable } : { rows: [], next: null, unreadable });
+	let bound = null; // { file, line }: entries strictly above this place
+	if (before !== null && before !== undefined) {
+		const m = typeof before === "string" ? CONSOLE_AUDIT_CURSOR_RE.exec(before) : null;
+		if (m === null || !Number.isSafeInteger(Number(m[2]))) return unread("the cursor is not an audit position (YYYY-MM:line)");
+		bound = { file: `${m[1]}.jsonl`, line: Number(m[2]) };
+	}
+	const dir = join(logsDir, CONSOLE_AUDIT_DIR);
+	let files;
+	try {
+		files = monthFiles(dir, fs);
+	} catch (err) {
+		return unread(`the audit directory cannot be read (${err?.code ?? "error"})`);
+	}
+	const out = []; // newest first, each { entry, pos }
+	let more = false;
+	for (let f = files.length - 1; f >= 0 && !more; f--) {
+		const file = files[f];
+		if (bound !== null && file > bound.file) continue;
+		// The first line that is NOT this page's: the cursor's own line in its file, none in an older one.
+		const stop = bound !== null && file === bound.file ? bound.line : Infinity;
+		const want = cap - out.length;
+		const ring = new Array(want);
+		let held = 0; // qualifying entries seen in this file
+		const keep = (entry, line) => {
+			ring[held % want] = { entry, pos: `${file.slice(0, 7)}:${line}` };
+			held += 1;
+		};
+		let i = 0;
+		try {
+			for (const line of fileLines(fs, join(dir, file))) {
+				i += 1;
+				if (i >= stop) break;
+				let row;
+				try {
+					row = JSON.parse(line);
+				} catch {
+					row = null;
+				}
+				if (row === null || typeof row !== "object" || Array.isArray(row) || !Number.isInteger(row.seq) || row.seq < 1) keep({ broken: true, file, line: i }, i);
+				else keep(row, i);
+			}
+		} catch (err) {
+			if (i + 1 < stop) keep({ broken: true, file, line: 0, reason: err?.code ?? "error" }, i + 1);
+		}
+		const n = Math.min(held, want);
+		for (let k = 1; k <= n; k++) out.push(ring[(held - k) % want]);
+		if (held > want) more = true;
+		// A page that filled exactly at the end of a file: an older file may still hold rows, so say there is more.
+		else if (out.length === cap && f > 0) more = true;
+	}
+	const page = { rows: out.map((x) => x.entry), next: more && out.length > 0 ? out[out.length - 1].pos : null };
+	return positions ? { ...page, positions: out.map((x) => x.pos) } : page;
+}
+
+/**
+ * The lines of `path`, read a chunk at a time, never the whole file at once: a month file can grow past what one
+ * string holds (V8's limit is about 512 MiB), and verify must still walk it rather than call it broken. A line is cut
+ * at the newline BYTE, so a multi-byte character split across two chunks is decoded whole. The newline after the last
+ * row ends nothing; a file cut mid-row yields its fragment as a last line, which the caller judges.
+ */
+function* fileLines(fs, path, chunkBytes = 1 << 20) {
+	const fd = fs.openSync(path, "r");
+	try {
+		const buf = Buffer.alloc(chunkBytes);
+		let carry = [];
+		for (;;) {
+			const n = fs.readSync(fd, buf, 0, chunkBytes, null);
+			if (n === 0) break;
+			let start = 0;
+			for (let at = buf.indexOf(10, 0); at !== -1 && at < n; at = buf.indexOf(10, at + 1)) {
+				carry.push(Buffer.from(buf.subarray(start, at)));
+				yield Buffer.concat(carry).toString("utf8");
+				carry = [];
+				start = at + 1;
+			}
+			if (start < n) carry.push(Buffer.from(buf.subarray(start, n)));
+		}
+		if (carry.length > 0) yield Buffer.concat(carry).toString("utf8");
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+/**
+ * The reaper of the audit files (a sibling of `makeAllocationLogReaper`), on `PI_CONSOLE_AUDIT_RETENTION_DAYS`, which
+ * inherits `PI_LOG_RETENTION_DAYS` when unset (issue #761: its own setting, so shortening the run history for privacy
+ * does not shorten the security trail; the caller passes the resolved days): a `YYYY-MM.jsonl` file whose last write
+ * (mtime) is older than the retention goes, 0 keeps everything, nothing of another name is touched. The NEWEST file is never reaped, however old: it holds the chain's
+ * head, and without it the next row would start a new chain at seq 1 that `verifyConsoleAudit` cannot tell from a
+ * forged one. Never throws.
+ */
+export function makeConsoleAuditReaper({ logsDir, retentionDays, fs = nodeFs, log = () => {}, now = () => Date.now() }) {
+	const dir = join(logsDir, CONSOLE_AUDIT_DIR);
+	return function reapConsoleAudit() {
+		if (retentionDays === 0) return;
+		let names;
+		try {
+			names = monthFiles(dir, fs);
+		} catch (err) {
+			log("console_audit_reaper_skipped", { reason: err?.code ?? "error" });
+			return;
+		}
+		const cutoff = now() - retentionDays * 86400000;
+		for (const name of names.slice(0, -1)) {
+			try {
+				const st = fs.lstatSync(join(dir, name));
+				if (st.isFile() && st.mtimeMs < cutoff) {
+					fs.unlinkSync(join(dir, name));
+					log("reaped_console_audit", { file: name });
+				}
+			} catch (err) {
+				log("console_audit_reaper_skipped", { file: name, reason: err?.code ?? "error" });
+			}
+		}
+	};
+}
+
+/**
+ * Best effort: the row onto `console:audit` (LPUSH, then LTRIM to `max`), for a screen that lists recent rows without
+ * reading files. Resolves true when both landed, false otherwise; never throws, and logs nothing (the caller has the
+ * row and knows the file holds it).
+ */
+export async function mirrorRow(redis, row, max = 500) {
+	try {
+		await redis.lpush(CONSOLE_AUDIT_KEY, JSON.stringify(row));
+		await redis.ltrim(CONSOLE_AUDIT_KEY, 0, max - 1);
+		return true;
+	} catch {
+		return false;
+	}
+}