@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/coordinator-journal.mjs

@@ -0,0 +1,282 @@
+/**
+ * Durable command journal for the View State Coordinator (issue #91, spec D3).
+ *
+ * Write order contract: the coordinator appends a command record here and
+ * fsyncs BEFORE materializing state.json/status.json, so a crash between the
+ * two can be repaired by replaying the journal on restart. The checkpoint
+ * records how much of the journal (`journalBytes`) is already reflected in
+ * materialized state; GC may only drop that prefix after the checkpoint write
+ * itself succeeded. Full-coverage GC truncates the journal to empty: the
+ * covered commands leave the journal, so post-GC idempotency dedupe is owned
+ * by the coordinator's in-memory ring of recent commandIds (older commandIds
+ * fall back to current-state re-decision, whose apply paths are idempotent).
+ * `screen.log`'s fs-injection and temp+rename patterns are
+ * reused so every fs call is injectable in tests.
+ */
+import {
+	closeSync,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export const JOURNAL_FILE_NAME = "state-journal.jsonl";
+export const CHECKPOINT_FILE_NAME = "state-journal.checkpoint.json";
+
+export const defaultJournalFs = Object.freeze({
+	closeSync,
+	existsSync,
+	fstatSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeSync,
+});
+
+/** @param {string} root @returns {string} */
+export function journalPath(root) {
+	return join(root, JOURNAL_FILE_NAME);
+}
+
+/** @param {string} root @returns {string} */
+export function checkpointPath(root) {
+	return join(root, CHECKPOINT_FILE_NAME);
+}
+
+/**
+ * Append one processed-command record and fsync it before returning.
+ * @param {string} root
+ * @param {{ command: object, result: { status: string, reason: string|null }, materializedRevision: number, at: number }} record
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {number} journal size in bytes after the append (usable as the next
+ *   checkpoint's `journalBytes`).
+ */
+export function appendCommand(root, record, fs = defaultJournalFs) {
+	const file = journalPath(root);
+	fs.mkdirSync(dirname(file), { recursive: true });
+	const payload = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
+	let fd;
+	try {
+		fd = fs.openSync(file, "a");
+		let offset = 0;
+		while (offset < payload.length) offset += fs.writeSync(fd, payload, offset, payload.length - offset);
+		fs.fsyncSync(fd);
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* already closed */ }
+		}
+	}
+	return fileSize(file, 0, fs);
+}
+
+/**
+ * Read every parseable journal record. A corrupt line (crash mid-append) is
+ * skipped — same semantics as atomic.mjs readJsonl, but with injectable fs.
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {Array<{ command: object, result: { status: string, reason: string|null }, materializedRevision: number, at: number }>}
+ */
+export function readJournal(root, fs = defaultJournalFs) {
+	const data = readAllBytes(journalPath(root), fs);
+	const entries = [];
+	for (const line of data.toString("utf8").split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			entries.push(JSON.parse(trimmed));
+		} catch {
+			/* skip corrupt line */
+		}
+	}
+	return entries;
+}
+
+/**
+ * Idempotency lookup: the recorded result of an already-processed commandId,
+ * or null. On the (never-intended) duplicate, the FIRST entry is the original.
+ * @param {string} root
+ * @param {string} commandId
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {{ status: string, reason: string|null } | null}
+ */
+export function findProcessedCommand(root, commandId, fs = defaultJournalFs) {
+	for (const entry of readJournal(root, fs)) {
+		if (entry?.command?.commandId === commandId) return entry.result ?? null;
+	}
+	return null;
+}
+
+/**
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {{ materializedRevision: number, journalBytes: number } | null}
+ */
+export function readCheckpoint(root, fs = defaultJournalFs) {
+	const file = checkpointPath(root);
+	if (!fs.existsSync(file)) return null;
+	let raw;
+	try {
+		raw = readAllBytes(file, fs).toString("utf8");
+	} catch {
+		return null;
+	}
+	if (!raw.trim()) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Atomically replace the checkpoint (temp file + fsync + rename, screen-log
+ * pattern). Callers may only run gcJournal after this returns true.
+ * @param {string} root
+ * @param {{ materializedRevision: number, journalBytes: number }} checkpoint
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {boolean} whether the checkpoint is durably on disk
+ */
+export function writeCheckpoint(root, checkpoint, fs = defaultJournalFs) {
+	const file = checkpointPath(root);
+	fs.mkdirSync(dirname(file), { recursive: true });
+	return replaceFile(file, Buffer.from(`${JSON.stringify(checkpoint, null, 2)}\n`, "utf8"), fs);
+}
+
+/**
+ * Drop the journal prefix already covered by a successful checkpoint. Without
+ * a checkpoint this is a no-op (nothing proves the prefix is materialized).
+ * A checkpoint covering the whole journal truncates the file to empty — every
+ * covered record is materialized, and keeping it would grow the journal (and
+ * every findProcessedCommand/boot-replay scan) without bound.
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {number} journal size in bytes after the call
+ */
+export function gcJournal(root, fs = defaultJournalFs) {
+	const file = journalPath(root);
+	const size = fileSize(file, 0, fs);
+	if (size === 0) return 0;
+	const checkpoint = readCheckpoint(root, fs);
+	if (!checkpoint || typeof checkpoint.journalBytes !== "number") return size;
+	const journalBytes = Math.floor(checkpoint.journalBytes);
+	if (journalBytes <= 0) return size;
+	if (journalBytes >= size) {
+		// Full coverage: everything in the file is materialized per the
+		// checkpoint. Truncate to empty; dedupe for covered commandIds is the
+		// coordinator's in-memory ring's job now.
+		if (!replaceFile(file, Buffer.alloc(0), fs)) return fileSize(file, size, fs);
+		return 0;
+	}
+	// journalBytes < size means the file exists with an un-checkpointed tail.
+	const tail = readAllBytes(file, fs, journalBytes);
+	if (!replaceFile(file, tail, fs)) return fileSize(file, size, fs);
+	return fileSize(file, tail.length, fs);
+}
+
+/**
+ * Truncate a crash-torn journal tail so the next append stays parseable.
+ *
+ * `appendCommand` writes `JSON+\n` in a partial-write loop; a process killed
+ * mid-append leaves bytes without a trailing newline. Without repair, the next
+ * append concatenates onto that torn line and the merged line is unparseable — the
+ * freshly fsynced+acked record becomes invisible to every readJournal /
+ * boot-replay / revision scan. The repair is byte-exact and cheap: scan
+ * backwards for the last newline and drop everything after it (a journal with
+ * no newline at all is torn from byte 0 and truncates to empty). Complete but
+ * corrupt lines are kept — readJournal already skips them.
+ * @param {string} root
+ * @param {typeof defaultJournalFs} [fs]
+ * @returns {number} journal size in bytes after the call
+ */
+export function repairJournalTail(root, fs = defaultJournalFs) {
+	const file = journalPath(root);
+	const size = fileSize(file, 0, fs);
+	if (size === 0) return 0;
+	const data = readAllBytes(file, fs);
+	const lastNewline = data.lastIndexOf("\n");
+	if (lastNewline === data.length - 1) return size;
+	const keep = lastNewline + 1;
+	if (!replaceFile(file, data.subarray(0, keep), fs)) return fileSize(file, size, fs);
+	return keep;
+}
+
+/**
+ * Read the file from `position` (default 0) to EOF via injectable readSync.
+ * @param {string} file
+ * @param {typeof defaultJournalFs} fs
+ * @param {number} [position]
+ * @returns {Buffer}
+ */
+function readAllBytes(file, fs, position = 0) {
+	if (!fs.existsSync(file)) return Buffer.alloc(0);
+	let fd;
+	try {
+		fd = fs.openSync(file, "r");
+		const size = Math.max(0, fs.fstatSync(fd).size - position);
+		if (size === 0) return Buffer.alloc(0);
+		const output = Buffer.allocUnsafe(size);
+		let offset = 0;
+		while (offset < size) {
+			const read = fs.readSync(fd, output, offset, size - offset, position + offset);
+			if (read === 0) break;
+			offset += read;
+		}
+		return offset === size ? output : output.subarray(0, offset);
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* already closed */ }
+		}
+	}
+}
+
+/**
+ * Temp file + fsync + rename replacement (screen-log replaceScreenLog pattern).
+ * @param {string} file
+ * @param {Buffer} data
+ * @param {typeof defaultJournalFs} fs
+ * @returns {boolean}
+ */
+function replaceFile(file, data, fs) {
+	const temp = `${file}.${process.pid}.${tempSequence++}.tmp`;
+	let fd;
+	try {
+		fs.mkdirSync(dirname(file), { recursive: true });
+		fd = fs.openSync(temp, "w");
+		let offset = 0;
+		while (offset < data.length) offset += fs.writeSync(fd, data, offset, data.length - offset, offset);
+		fs.fsyncSync(fd);
+		fs.closeSync(fd);
+		fd = undefined;
+		fs.renameSync(temp, file);
+		return true;
+	} catch {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* already closed */ }
+		}
+		try { fs.unlinkSync(temp); } catch { /* best effort */ }
+		return false;
+	}
+}
+
+/** @param {string} file @param {number} fallback @param {typeof defaultJournalFs} fs */
+function fileSize(file, fallback, fs) {
+	try {
+		return fs.statSync(file).size;
+	} catch {
+		return fallback;
+	}
+}
+
+let tempSequence = 0;

package/packages/board/src/core/coordinator-protocol.mjs

@@ -0,0 +1,14 @@
+/**
+ * Protocol version of the View State Coordinator control socket (issue #108).
+ *
+ * Bumped whenever a coordinator release adds command kinds or changes the
+ * envelope contract. A client built against version N refuses to talk to a
+ * coordinator reporting < N — a pong WITHOUT the field counts as version 1
+ * (the pre-#107 baseline) — and replaces the stale instance with a fresh one
+ * (SIGTERM via the coordinator lease pid, then respawn) instead of feeding
+ * it commands it cannot understand (`sync_foreground rejected (unknown_kind)`
+ * used to strand every foreground state write on extension updates).
+ *
+ * Version 3 adds mark_holding / clear_holding (issue #145).
+ */
+export const COORDINATOR_PROTOCOL_VERSION = 3;

package/packages/board/src/core/cwd-stats.mjs

@@ -0,0 +1,114 @@
+/**
+ * Persistent cwd usage stats for the launch dialog's directory favorites.
+ *
+ * Counts every successfully dispatched session per cwd, independent of the
+ * view lifecycle (deleting a view does not decrement). The dashboard reads
+ * the ranked list for the cwd picker's favorites mode. Pure node, no Pi imports.
+ */
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+import { readMeta, readRoster } from "./store.mjs";
+
+/**
+ * @typedef {Object} CwdStatsEntry
+ * @property {number} count
+ * @property {number} lastUsed  epoch ms, like meta.updatedAt
+ */
+
+/** @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+function emptyStats() {
+	return { version: 1, entries: {} };
+}
+
+/** @param {string} root @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+export function readCwdStats(root) {
+	const raw = readJson(P.cwdStatsPath(root), null);
+	if (!raw || typeof raw !== "object" || typeof raw.entries !== "object" || raw.entries === null) return emptyStats();
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const [dir, entry] of Object.entries(raw.entries)) {
+		if (!entry || typeof entry.count !== "number") continue;
+		entries[dir] = {
+			count: Math.max(0, Math.floor(entry.count)),
+			lastUsed: typeof entry.lastUsed === "number" ? entry.lastUsed : 0,
+		};
+	}
+	return { version: 1, entries };
+}
+
+/**
+ * One-time seed: aggregate cwd counts from every roster view's meta.json.
+ * No-op when cwd-stats.json already exists.
+ * @param {string} root
+ */
+export function seedCwdStatsFromViews(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const viewId of readRoster(root).views ?? []) {
+		const meta = readMeta(root, viewId);
+		const cwd = meta?.cwd;
+		if (!cwd) continue;
+		const lastUsed = typeof meta.updatedAt === "number" ? meta.updatedAt : Date.now();
+		const existing = entries[cwd];
+		if (existing) {
+			existing.count += 1;
+			existing.lastUsed = Math.max(existing.lastUsed, lastUsed);
+		} else {
+			entries[cwd] = { count: 1, lastUsed };
+		}
+	}
+	atomicWriteJson(P.cwdStatsPath(root), { version: 1, entries });
+}
+
+/**
+ * Seed when the stats file is missing; tolerate every failure (dashboard UX
+ * must never break because of stats bookkeeping).
+ * @param {string} root
+ */
+export function ensureCwdStatsSeeded(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	try {
+		seedCwdStatsFromViews(root);
+	} catch {
+		/* best effort */
+	}
+}
+
+/**
+ * Record one successful dispatch for `cwd`. Invalid dirs are ignored.
+ * @param {string} root @param {string} cwd
+ */
+export function recordCwdLaunch(root, cwd) {
+	if (!cwd || !existsSync(cwd)) return;
+	const stats = readCwdStats(root);
+	const existing = stats.entries[cwd] ?? { count: 0, lastUsed: 0 };
+	stats.entries[cwd] = { count: existing.count + 1, lastUsed: Date.now() };
+	atomicWriteJson(P.cwdStatsPath(root), stats);
+}
+
+/**
+ * Ranked candidates: count desc, then lastUsed desc; home appended at the
+ * end when absent so the user's home dir is always one keystroke away.
+ * `limit` is an optional cap for callers that explicitly want one; the
+ * default returns the whole history so the launch picker can search it.
+ * @param {string} root @param {number=} limit
+ * @returns {Array<{path: string, count: number}>}
+ */
+export function rankedCwdCandidates(root, limit = Number.POSITIVE_INFINITY) {
+	const stats = readCwdStats(root);
+	const rows = Object.entries(stats.entries).map(([dir, entry]) => ({
+		path: dir,
+		count: entry.count,
+		lastUsed: entry.lastUsed,
+	}));
+	rows.sort((a, b) => b.count - a.count || b.lastUsed - a.lastUsed);
+	const out = rows.slice(0, Math.max(1, limit)).map(({ path, count }) => ({ path, count }));
+	const home = os.homedir();
+	if (out.some((entry) => entry.path === home)) return out;
+	const homeRow = rows.find((entry) => entry.path === home);
+	out.push(homeRow ? { path: home, count: homeRow.count } : { path: home, count: 0 });
+	return out;
+}

package/packages/board/src/core/dashboard-render.mjs

@@ -0,0 +1,10 @@
+/**
+ * Request a differential dashboard repaint.
+ *
+ * Full-screen custom overlays still participate in Pi TUI's line diffing. Passing
+ * `true` here discards that state and clears the terminal before every repaint,
+ * which is visible as flicker on terminals without synchronized-output support.
+ */
+export function requestDashboardRender(tui) {
+	tui.requestRender();
+}

package/packages/board/src/core/derive.mjs

@@ -0,0 +1,117 @@
+/**
+ * State-machine + summary derivation. Pure functions over a RunStatus.
+ *
+ * Semantic-state rules (plan §9.1):
+ *   while alive:   queued → working (once assistant/tool activity begins)
+ *   clean exit:    needs_input (asked a question) | idle (user can mark completed)
+ *   bad exit:      failed
+ *   user stop:     stopped
+ * Summary priority (plan §9.3): model → active tool → blocker → first sentence → error → fallback.
+ */
+import { firstSentence, truncate } from "./heuristics.mjs";
+
+/** @typedef {import("./types.mjs").RunStatus} RunStatus */
+/** @typedef {import("./types.mjs").SemanticState} SemanticState */
+
+const GENERIC_STATUS_TEXT = {
+	queued: new Set(["Queued"]),
+	working: new Set(["Working", "Working…", "Running", "Running…"]),
+	needs_input: new Set(["Needs input", "Needs answer"]),
+	idle: new Set(["Idle", "In Progress", "Needs instructions"]),
+	holding: new Set(["On hold"]),
+	completed: new Set(["Completed", "Done"]),
+	failed: new Set(["Failed"]),
+	stopped: new Set(["Stopped"]),
+};
+
+const ALL_GENERIC_STATUS_TEXT = new Set(Object.values(GENERIC_STATUS_TEXT).flatMap((labels) => [...labels]));
+
+/**
+ * Compute the terminal semantic state for a finished run.
+ * @param {{ exitCode:number|null, stopReason:string|null, stoppedByUser:boolean, needsInput:boolean }} p
+ * @returns {SemanticState}
+ */
+export function finalizeSemanticState({ exitCode, stopReason, stoppedByUser, needsInput }) {
+	if (stoppedByUser) return "stopped";
+	const errored = (exitCode != null && exitCode !== 0) || stopReason === "error" || stopReason === "aborted";
+	if (errored) return "failed";
+	if (needsInput) return "needs_input";
+	return "idle";
+}
+
+/**
+ * Fallback status text when no richer summary is available.
+ * @param {SemanticState} state
+ * @returns {string}
+ */
+export function fallbackStatusText(state) {
+	switch (state) {
+		case "queued":
+			return "Queued";
+		case "working":
+			return "Running…";
+		case "needs_input":
+			return "Needs answer";
+		case "idle":
+			return "Needs instructions";
+		case "holding":
+			return "On hold";
+		case "completed":
+			return "Done";
+		case "failed":
+			return "Failed";
+		case "stopped":
+			return "Stopped";
+		default:
+			return "Unknown";
+	}
+}
+
+/** @param {string|null|undefined} text */
+export function isGenericStatusText(text) {
+	const trimmed = String(text || "").trim();
+	return !trimmed || ALL_GENERIC_STATUS_TEXT.has(trimmed);
+}
+
+/**
+ * Normalize generic fallback summaries to the current display label for a state.
+ * @param {SemanticState} state
+ * @param {string|null|undefined} text
+ */
+export function normalizeGenericStatusText(state, text) {
+	const trimmed = String(text || "").trim();
+	if (!trimmed || GENERIC_STATUS_TEXT[state]?.has(trimmed)) return fallbackStatusText(state);
+	return trimmed;
+}
+
+/**
+ * Heuristic summary for a run (no model). Honors the documented priority order.
+ * @param {RunStatus} status
+ * @param {number} [max] max characters
+ * @returns {string}
+ */
+export function deriveSummary(status, max = 80) {
+	const s = status;
+	// 2. active tool (only while still working)
+	if (s.processState === "alive" && s.currentTool?.name) {
+		// currentTool.summary is precomputed by the reducer; fall back to name.
+		const ct = /** @type {any} */ (s.currentTool);
+		if (typeof ct.summary === "string" && ct.summary) return truncate(ct.summary, max);
+		return truncate(ct.name, max);
+	}
+	// 3. explicit blocker / question
+	if (s.semanticState === "needs_input" && s.question) return truncate(s.question, max);
+	// 5. error (placed above generic preview for failed runs)
+	if (s.semanticState === "failed" && s.error) return truncate(s.error, max);
+	// 4. first sentence of latest assistant output (fall back to full text if the first
+	// sentence is uninformatively short, e.g. "Done.")
+	if (s.latestAssistantPreview) {
+		const fs = firstSentence(s.latestAssistantPreview);
+		const pick = fs.length >= 12 ? fs : s.latestAssistantPreview;
+		return truncate(pick, max);
+	}
+	if (s.question) return truncate(s.question, max);
+	if (s.error) return truncate(s.error, max);
+	// 6. fallback status text
+	return fallbackStatusText(s.semanticState);
+}

package/packages/board/src/core/diagnostics.mjs

@@ -0,0 +1,133 @@
+/** Diagnostics JSONL helpers for Agent Board rows. */
+import { atomicWrite, appendJsonl, readJsonl, readJsonlTail } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+
+const SECRET_KEY_RE = /token|secret|password|authorization|api[_-]?key/i;
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {Partial<import("./types.mjs").DiagnosticEvent>} patch
+ * @returns {import("./types.mjs").DiagnosticEvent}
+ */
+export function appendDiagnostic(root, viewId, patch = {}) {
+	const event = normalizeDiagnostic(viewId, patch);
+	appendJsonl(P.diagnosticsPath(root, viewId), event);
+	return event;
+}
+
+/**
+ * Append a diagnostic unless a recent event already carries the same code and the
+ * same `opts.match` detail values (issue #217 D4): repeated attach clicks on one
+ * unverifiable host must leave one trail, not a flood.
+ * @param {string} root
+ * @param {string} viewId
+ * @param {Partial<import("./types.mjs").DiagnosticEvent>} patch
+ * @param {{ match?: string[], limit?: number }} [opts] `match: []` never dedupes.
+ * @returns {import("./types.mjs").DiagnosticEvent|null} the appended event, or null when skipped
+ */
+export function appendDiagnosticOnce(root, viewId, patch = {}, opts = {}) {
+	const event = normalizeDiagnostic(viewId, patch);
+	const match = Array.isArray(opts.match) ? opts.match : [];
+	if (match.length > 0) {
+		const limit = opts.limit ?? 20;
+		const duplicate = readJsonlTail(P.diagnosticsPath(root, viewId), limit)
+			.map((e) => normalizeDiagnostic(viewId, e))
+			.some((e) => e.code === event.code && match.every((key) => e.details?.[key] === event.details?.[key]));
+		if (duplicate) return null;
+	}
+	appendJsonl(P.diagnosticsPath(root, viewId), event);
+	return event;
+}
+
+/** @param {string} root @param {string} viewId @returns {import("./types.mjs").DiagnosticEvent[]} */
+export function readDiagnostics(root, viewId) {
+	return readJsonl(P.diagnosticsPath(root, viewId)).map((e) => normalizeDiagnostic(viewId, e));
+}
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {{ limit?: number }} [opts]
+ * @returns {import("./types.mjs").DiagnosticEvent[]}
+ */
+export function tailDiagnostics(root, viewId, opts = {}) {
+	return readJsonlTail(P.diagnosticsPath(root, viewId), opts.limit ?? 50).map((e) => normalizeDiagnostic(viewId, e));
+}
+
+/** @param {string} root @param {string} viewId */
+export function clearDiagnostics(root, viewId) {
+	atomicWrite(P.diagnosticsPath(root, viewId), "");
+	return { ok: true };
+}
+
+/** @returns {import("./types.mjs").DiagnosticSummary} */
+export function emptyDiagnosticSummary() {
+	return {
+		count: 0,
+		warningCount: 0,
+		errorCount: 0,
+		lastAt: null,
+		lastLevel: null,
+		lastCode: null,
+		lastMessage: null,
+		stalled: false,
+		stallReason: null,
+	};
+}
+
+/** @param {import("./types.mjs").DiagnosticEvent[]} events @returns {import("./types.mjs").DiagnosticSummary} */
+export function summarizeDiagnostics(events) {
+	const summary = emptyDiagnosticSummary();
+	for (const event of events ?? []) {
+		summary.count += 1;
+		if (event.level === "warn") summary.warningCount += 1;
+		if (event.level === "error") summary.errorCount += 1;
+		summary.lastAt = event.at ?? summary.lastAt;
+		summary.lastLevel = event.level ?? summary.lastLevel;
+		summary.lastCode = event.code ?? summary.lastCode;
+		summary.lastMessage = event.message ?? summary.lastMessage;
+		if (event.code === "provider_stall" || event.code === "stalled") {
+			summary.stalled = true;
+			summary.stallReason = String(event.details?.reason ?? event.message ?? "stalled");
+		}
+		if (event.code === "provider_stall_resolved" || event.code === "stall_resolved") {
+			summary.stalled = false;
+			summary.stallReason = null;
+		}
+	}
+	return summary;
+}
+
+/** @param {string} root @param {string} viewId */
+export function readDiagnosticSummary(root, viewId) {
+	return summarizeDiagnostics(readDiagnostics(root, viewId));
+}
+
+/** @param {string} viewId @param {any} patch @returns {import("./types.mjs").DiagnosticEvent} */
+export function normalizeDiagnostic(viewId, patch = {}) {
+	const level = ["info", "warn", "error"].includes(patch.level) ? patch.level : "info";
+	const code = typeof patch.code === "string" && patch.code ? patch.code : "event";
+	return {
+		version: 1,
+		at: Number.isFinite(patch.at) ? patch.at : Date.now(),
+		viewId,
+		runId: typeof patch.runId === "string" ? patch.runId : null,
+		source: typeof patch.source === "string" && patch.source ? patch.source : "service",
+		level,
+		code,
+		message: typeof patch.message === "string" && patch.message ? patch.message : code,
+		details: redactDiagnosticDetails(patch.details ?? {}),
+	};
+}
+
+/** @param {any} value @returns {any} */
+export function redactDiagnosticDetails(value) {
+	if (Array.isArray(value)) return value.map((v) => redactDiagnosticDetails(v));
+	if (!value || typeof value !== "object") return value;
+	const out = {};
+	for (const [key, val] of Object.entries(value)) {
+		out[key] = SECRET_KEY_RE.test(key) ? "[redacted]" : redactDiagnosticDetails(val);
+	}
+	return out;
+}

package/packages/board/src/core/double-press.mjs

@@ -0,0 +1,26 @@
+/** How close two presses must be to count as one double press. */
+export const DOUBLE_PRESS_MS = 400;
+
+/** Longer than Pi's own 500ms, or a session could take the second Ctrl+C and quit by itself. */
+export const QUIT_PRESS_MS = 1000;
+
+/**
+ * Tells a second press apart from a first. Anything else in between starts over.
+ * @param {() => number} [now]
+ * @param {number} [windowMs]
+ * @returns {{ press(): boolean, reset(): void }} press() is true on the second press.
+ */
+export function createDoublePress(now = Date.now, windowMs = DOUBLE_PRESS_MS) {
+	let last = null;
+	return {
+		press() {
+			const at = now();
+			const second = last !== null && at - last <= windowMs;
+			last = second ? null : at;
+			return second;
+		},
+		reset() {
+			last = null;
+		},
+	};
+}