toolroll 0.5.0

package/dist/lead-status.js

@@ -0,0 +1,285 @@
+/** Cheap lead-facing status. Every fact comes from indexed SQLite records;
+ * this module never opens a repository, retained evidence, or a live log. */
+import { COMPLETION_ACTION } from "./result-completion.js";
+import { windowLabel } from "./provider-limits.js";
+import { BUILT_IN, checkSuitesOf } from "./store.js";
+const maybeNumber = (value) => value === null || value === undefined || !Number.isInteger(Number(value)) ? null : Number(value);
+const CHECK_COLUMNS = "rc.status AS check_status, rc.exit_code AS check_exit_code, rc.suites_json AS check_suites_json";
+function checkOf(row) {
+    const status = row?.["check_status"];
+    return {
+        status: status === "passed" || status === "failed" || status === "not-run" ? status : "unknown",
+        exitCode: maybeNumber(row?.["check_exit_code"]),
+        suites: checkSuitesOf(row?.["check_suites_json"]),
+    };
+}
+function phaseOf(row) {
+    const phase = row["phase"] == null ? null : String(row["phase"]);
+    if (phase !== null)
+        return phase;
+    const role = String(row["role"] ?? "builder");
+    return role === "planner" ? "planning" : role === "scout" ? "researching" : role === "reviewer" ? "reviewing" : "preparing";
+}
+const phaseWords = (phase) => ({
+    "agent-running": "agent working",
+    "validating-handoff": "checking handoff",
+    "capturing-evidence": "saving result",
+    committing: "committing",
+    "verifying-proof": "running checks",
+    "correcting-proof": "correcting result",
+    planning: "planning",
+    researching: "researching",
+    reviewing: "reviewing",
+    preparing: "preparing",
+}[phase] ?? phase.replace(/-/g, " "));
+function latestResult(store, taskRef) {
+    return store.handle.prepare(`SELECT run.id, run.outcome, run.reason, run.phase, run.finished_at, ${CHECK_COLUMNS}
+    FROM run INDEXED BY work_result LEFT JOIN run_check AS rc ON rc.run = run.id
+    WHERE run.task_ref = ? AND run.finished_at IS NOT NULL AND run.role IN ('builder','scout')
+    ORDER BY run.id DESC LIMIT 1`).get(taskRef);
+}
+function unfinishedAttempt(store, taskRef) {
+    return store.handle.prepare(`SELECT run.id, run.role, run.outcome, run.reason, run.phase, run.finished_at, ${CHECK_COLUMNS}
+    FROM run INDEXED BY work_unfinished LEFT JOIN run_check AS rc ON rc.run = run.id
+    WHERE run.task_ref = ? AND run.outcome IS NULL ORDER BY run.id DESC LIMIT 1`).get(taskRef);
+}
+function latestAttempt(store, taskRef) {
+    return store.handle.prepare(`SELECT run.id, run.role, run.outcome, run.reason, run.phase, run.finished_at, ${CHECK_COLUMNS}
+    FROM run INDEXED BY lead_status_task_run LEFT JOIN run_check AS rc ON rc.run = run.id
+    WHERE run.task_ref = ? AND run.finished_at IS NOT NULL ORDER BY run.id DESC LIMIT 1`).get(taskRef);
+}
+function newestAttemptSince(store, taskRef, run) {
+    return store.handle.prepare(`SELECT run.id, run.role, run.outcome, run.reason, run.phase, run.finished_at, ${CHECK_COLUMNS}
+    FROM run INDEXED BY lead_status_task_run LEFT JOIN run_check AS rc ON rc.run = run.id
+    WHERE run.task_ref = ? AND run.id >= ? ORDER BY run.id DESC LIMIT 1`).get(taskRef, run);
+}
+/** One indexed observation for `task wait`. `watchedRun` is the attempt the
+ * caller first saw. Each poll follows the task's newest attempt from there, so
+ * a retry that lands between polls is reported with its own run and outcome,
+ * and `replacedRun` says which attempt it replaced. Undefined means no attempt
+ * has been observed yet. */
+export function taskWaitSnapshot(store, taskId, now, watchedRun) {
+    const task = store.handle.prepare(`SELECT task.id, task.state, ref.id AS task_ref, ref.plan, ref.strikes
+    FROM task INDEXED BY sqlite_autoindex_task_1
+    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
+    WHERE task.id = ?`).get(BUILT_IN, taskId);
+    if (task === undefined)
+        return null;
+    const taskRef = Number(task["task_ref"]);
+    const state = String(task["state"]);
+    const attempt = watchedRun === undefined ? unfinishedAttempt(store, taskRef) : newestAttemptSince(store, taskRef, watchedRun);
+    const followed = maybeNumber(attempt?.["id"]);
+    const replacedRun = watchedRun !== undefined && followed !== null && followed !== watchedRun ? watchedRun : null;
+    const result = state === "done" ? latestResult(store, taskRef) : undefined;
+    const terminalAttempt = state === "failed" || state === "cancelled" ? latestAttempt(store, taskRef) : undefined;
+    const shown = attempt ?? result ?? terminalAttempt;
+    const run = maybeNumber(shown?.["id"]);
+    const check = checkOf(shown);
+    const phase = shown === undefined ? null : phaseWords(phaseOf(shown));
+    const answer = (outcome, next, terminal, exitCode, reason) => ({ task: taskId, outcome, run, replacedRun, phase, check, next, terminal, exitCode, reason });
+    // The followed attempt's own failure is the answer, even if the task's state
+    // has already moved on; a task-level success must not stand in for it.
+    if (watchedRun !== undefined && attempt !== undefined && attempt["outcome"] !== null && state !== "failed" && state !== "cancelled") {
+        const outcome = String(attempt["outcome"]);
+        if (outcome === "parked")
+            return answer("Needs a person", "Answer the task's question", true, 1, "needs-person");
+        if (outcome !== "built" && outcome !== "no-change")
+            return answer("Failed", "Inspect attempt", true, 1, "failed");
+        if (state !== "done")
+            return answer("Ready", "Review result", true, 0, "ready");
+    }
+    const completion = result === undefined ? undefined : store.handle.prepare(`SELECT 1 AS hit FROM action_ledger INDEXED BY work_completion
+    WHERE task_id = ? AND action = ? AND source = 'work' AND run_id = ? LIMIT 1`).get(taskId, COMPLETION_ACTION, Number(result["id"]));
+    if (state === "done" && completion !== undefined)
+        return answer("Complete", "No action needed", true, 0, "complete");
+    if (state === "done")
+        return answer("Ready", "Review result", true, 0, "ready");
+    if (state === "failed" || state === "cancelled")
+        return answer("Failed", state === "cancelled" ? "Review cancellation" : "Inspect failure", true, 1, "failed");
+    const decision = store.handle.prepare(`SELECT decision.id FROM run INDEXED BY lead_status_task_run
+    JOIN decision INDEXED BY work_open_decision ON decision.run = run.id
+    WHERE run.task_ref = ? AND decision.state <> 'answered' AND decision.answered_at IS NULL LIMIT 1`).get(taskRef);
+    if (decision !== undefined)
+        return answer("Needs a person", "Answer question", true, 1, "needs-person");
+    const hold = store.handle.prepare(`SELECT owner_kind FROM hold INDEXED BY hold_by_task
+    WHERE task_ref = ? AND (until IS NULL OR until > ?)
+    ORDER BY CASE owner_kind WHEN 'decision' THEN 0 WHEN 'incident' THEN 1 WHEN 'operator' THEN 2 WHEN 'revision' THEN 3 WHEN 'stop' THEN 4 WHEN 'contest' THEN 5 ELSE 6 END, id LIMIT 1`)
+        .get(taskRef, now.toISOString());
+    const holdKind = hold === undefined ? null : String(hold["owner_kind"]);
+    if (holdKind !== null && holdKind !== "backoff") {
+        const next = holdKind === "operator" ? "Remove hold" : holdKind === "revision" ? "Review plan" : holdKind === "stop" ? "Resume or close attempt" : holdKind === "contest" ? "Choose a result" : "Review task";
+        return answer("Needs a person", next, true, 1, "needs-person");
+    }
+    if (task["plan"] === "drafted")
+        return answer("Needs a person", "Review plan", true, 1, "needs-person");
+    if (Number(task["strikes"] ?? 0) >= 3)
+        return answer("Needs a person", "Review repeated failures", true, 1, "needs-person");
+    // An admitted attempt is already the work being watched. Its immutable
+    // approval snapshot lives on the run, so a damaged or later-edited current
+    // scope must not make `wait` abandon that attempt before it settles.
+    if (attempt !== undefined)
+        return answer("Running", phase === null ? "Wait for attempt" : `Wait — ${phase}`, false, null, null);
+    const scope = store.handle.prepare("SELECT digest, approved_digest, profile_state FROM task_scope WHERE task_id = ?").get(taskId);
+    if (scope === undefined)
+        return answer("Needs a person", "Add scope", true, 1, "needs-person");
+    if (scope["approved_digest"] !== scope["digest"] || scope["profile_state"] !== "resolved")
+        return answer("Needs a person", "Approve task", true, 1, "needs-person");
+    if (state === "running" && attempt === undefined) {
+        const liveClaim = store.handle.prepare(`SELECT 1 AS hit FROM claim INDEXED BY claim_by_task
+      WHERE task_ref = ? AND released_at IS NULL AND expires_at > ?
+        AND lease_generation = (SELECT MAX(newest.lease_generation) FROM claim AS newest INDEXED BY claim_by_task WHERE newest.task_ref = ?)
+      LIMIT 1`).get(taskRef, now.toISOString(), taskRef);
+        if (liveClaim !== undefined)
+            return answer("Queued", "Wait for attempt to start", false, null, null);
+        return answer("Needs a person", "Reconcile unfinished work", true, 1, "needs-person");
+    }
+    if (holdKind === "backoff")
+        return answer("Queued", "Wait for retry", false, null, null);
+    return answer("Queued", "Wait for a worker", false, null, null);
+}
+function queueReason(row) {
+    const hold = row["hold_kind"] == null ? null : String(row["hold_kind"]);
+    if (hold === "decision")
+        return "needs a decision";
+    if (hold === "incident")
+        return "needs attention";
+    if (hold === "operator")
+        return "on hold";
+    if (hold === "revision")
+        return "needs plan review";
+    if (hold === "stop")
+        return "stopped";
+    if (hold === "contest")
+        return "needs a result choice";
+    if (hold === "backoff")
+        return "retrying later";
+    if (row["plan"] === "drafted")
+        return "needs plan review";
+    if (Number(row["strikes"] ?? 0) >= 3)
+        return "stalled after failures";
+    if (Number(row["blocked"] ?? 0) === 1)
+        return "waiting for another task";
+    if (row["scope_digest"] == null)
+        return "needs a scope";
+    if (row["approved_digest"] !== row["scope_digest"] || row["profile_state"] !== "resolved")
+        return "needs approval";
+    return "ready for a worker";
+}
+/** Whole-installation status, deliberately aggregated and bounded. */
+export function installationStatus(store, now) {
+    const runningRows = store.handle.prepare(`SELECT run.id, run.role, run.phase, ref.external_id AS task
+    FROM run INDEXED BY work_unfinished
+    JOIN task_ref AS ref ON ref.id = run.task_ref
+    JOIN claim ON claim.lease_id = run.lease_id
+    WHERE run.outcome IS NULL AND claim.released_at IS NULL AND claim.expires_at > ?
+      AND claim.lease_generation = (SELECT MAX(newest.lease_generation) FROM claim AS newest INDEXED BY claim_by_task WHERE newest.task_ref = run.task_ref)
+    ORDER BY run.id`).all(now.toISOString());
+    const phases = new Map();
+    const runningTasks = runningRows.map(row => {
+        const phase = phaseWords(phaseOf(row));
+        phases.set(phase, (phases.get(phase) ?? 0) + 1);
+        return { task: String(row["task"]), run: Number(row["id"]), phase };
+    });
+    const queuedRows = store.handle.prepare(`SELECT task.id, ref.plan, ref.strikes, scope.digest AS scope_digest,
+      scope.approved_digest, scope.profile_state,
+      EXISTS (SELECT 1 FROM task_edge WHERE task_edge.blocked = task.id
+        AND EXISTS (SELECT 1 FROM task AS blocker WHERE blocker.id = task_edge.blocker AND blocker.state <> 'done')) AS blocked,
+      (SELECT owner_kind FROM hold INDEXED BY hold_by_task WHERE hold.task_ref = ref.id AND (hold.until IS NULL OR hold.until > ?)
+        ORDER BY CASE owner_kind WHEN 'decision' THEN 0 WHEN 'incident' THEN 1 WHEN 'operator' THEN 2 ELSE 3 END, id LIMIT 1) AS hold_kind
+    FROM task INDEXED BY task_by_state
+    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
+    LEFT JOIN task_scope AS scope ON scope.task_id = task.id
+    WHERE task.state = 'queued'`).all(now.toISOString(), BUILT_IN);
+    const reasons = new Map();
+    const queuedTasks = [];
+    for (const row of queuedRows) {
+        const reason = queueReason(row);
+        reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+        if (queuedTasks.length < 8)
+            queuedTasks.push({ task: String(row["id"]), reason });
+    }
+    const waitingCount = Number(store.handle.prepare(`SELECT COUNT(*) AS n FROM task INDEXED BY task_by_state
+    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
+    WHERE task.state = 'done' AND EXISTS (SELECT 1 FROM run INDEXED BY work_result
+      WHERE run.task_ref = ref.id AND run.finished_at IS NOT NULL AND run.role IN ('builder','scout'))
+      AND NOT EXISTS (SELECT 1 FROM action_ledger INDEXED BY work_completion
+        WHERE action_ledger.task_id = task.id AND action_ledger.action = ? AND action_ledger.source = 'work'
+          AND action_ledger.run_id = (SELECT id FROM run INDEXED BY work_result WHERE task_ref = ref.id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1))`)
+        .get(BUILT_IN, COMPLETION_ACTION)?.["n"] ?? 0);
+    const waitingRows = store.handle.prepare(`SELECT task.id AS task, result.id, ${CHECK_COLUMNS}
+    FROM task INDEXED BY task_done_recent
+    JOIN task_ref AS ref INDEXED BY sqlite_autoindex_task_ref_1 ON ref.backend = ? AND ref.external_id = task.id
+    JOIN run AS result ON result.id = (SELECT id FROM run INDEXED BY work_result WHERE task_ref = ref.id AND finished_at IS NOT NULL AND role IN ('builder','scout') ORDER BY id DESC LIMIT 1)
+    LEFT JOIN run_check AS rc ON rc.run = result.id
+    WHERE task.state = 'done' AND NOT EXISTS (SELECT 1 FROM action_ledger INDEXED BY work_completion
+      WHERE action_ledger.task_id = task.id AND action_ledger.action = ? AND action_ledger.source = 'work' AND action_ledger.run_id = result.id)
+    ORDER BY task.updated_at DESC, task.id DESC LIMIT 5`).all(BUILT_IN, COMPLETION_ACTION);
+    // Run ids grow with time, so the newest finished release check is the
+    // first finished row down the partial index.
+    const release = store.handle.prepare(`SELECT run.id, run.finished_at, ${CHECK_COLUMNS}, ref.external_id AS task
+    FROM run_check AS rc INDEXED BY run_check_release
+    JOIN run ON run.id = rc.run
+    JOIN task_ref AS ref ON ref.id = run.task_ref
+    WHERE rc.release = 1 AND run.finished_at IS NOT NULL
+    ORDER BY rc.run DESC LIMIT 1`).get();
+    return {
+        generatedAt: now.toISOString(),
+        running: { count: runningTasks.length, phases: [...phases].map(([phase, count]) => ({ phase, count })), tasks: runningTasks.slice(0, 8) },
+        queued: {
+            count: queuedRows.length,
+            reasons: [...reasons].map(([reason, count]) => ({ reason, count })).sort((a, b) => b.count - a.count || a.reason.localeCompare(b.reason)),
+            tasks: queuedTasks,
+        },
+        waitingForReview: { count: waitingCount, results: waitingRows.map(row => ({ task: String(row["task"]), run: Number(row["id"]), check: checkOf(row) })) },
+        releaseCheck: release === undefined ? null : { task: String(release["task"]), run: Number(release["id"]), finishedAt: release["finished_at"] == null ? null : String(release["finished_at"]), check: checkOf(release) },
+        planWindows: store.handle.prepare(`SELECT provider, window, used_percent, window_minutes, resets_at, reached, plan, observed_at
+      FROM provider_limit INDEXED BY sqlite_autoindex_provider_limit_1 ORDER BY provider, window`).all().map(row => ({
+            provider: String(row["provider"]),
+            plan: row["plan"] == null ? null : String(row["plan"]),
+            window: String(row["window"]),
+            usedPercent: Number(row["used_percent"]),
+            windowMinutes: row["window_minutes"] == null ? null : Number(row["window_minutes"]),
+            resetsAt: row["resets_at"] == null ? null : String(row["resets_at"]),
+            reached: Number(row["reached"]) === 1,
+            observedAt: String(row["observed_at"]),
+        })),
+    };
+}
+export function renderInstallationStatus(status) {
+    const lines = [];
+    lines.push(status.running.count === 0 ? "Running: none" : `Running: ${status.running.count} — ${status.running.tasks.map(one => `${one.task} (#${one.run}, ${one.phase})`).join(", ")}${status.running.count > status.running.tasks.length ? ", …" : ""}`);
+    lines.push(status.queued.count === 0 ? "Queued: none" : `Queued: ${status.queued.count} — ${status.queued.tasks.map(one => `${one.task} (${one.reason})`).join(", ")}${status.queued.count > status.queued.tasks.length ? ", …" : ""}`);
+    lines.push(status.waitingForReview.count === 0 ? "Ready for review: none" : `Ready for review: ${status.waitingForReview.count} — ${status.waitingForReview.results.map(one => `${one.task} (#${one.run})`).join(", ")}${status.waitingForReview.count > status.waitingForReview.results.length ? ", …" : ""}`);
+    if (status.releaseCheck === null) {
+        lines.push("Release check: none recorded");
+    }
+    else {
+        const check = status.releaseCheck.check;
+        lines.push(`Release check: ${status.releaseCheck.task} #${status.releaseCheck.run} — ${check.status}${check.exitCode === null ? "" : ` (exit ${check.exitCode})`}`);
+        if (check.suites.length > 0) {
+            lines.push(`  Suites: ${check.suites.map(suite => `${suite.name} ${suite.status}${suite.exitCode === null ? "" : ` (exit ${suite.exitCode})`}`).join("; ")}`);
+        }
+    }
+    if (status.planWindows.length === 0) {
+        lines.push("Plan windows: none recorded");
+    }
+    else {
+        const providers = new Map();
+        for (const window of status.planWindows) {
+            const key = `${window.provider}${window.plan === null ? "" : ` ${window.plan}`}`;
+            const list = providers.get(key) ?? [];
+            list.push(window);
+            providers.set(key, list);
+        }
+        for (const [provider, windows] of providers) {
+            const detail = windows.map(window => `${windowLabel(window.window, window.windowMinutes)} ${window.usedPercent}%${window.reached ? " (limit reached)" : ""}`).join(", ");
+            lines.push(`Plan windows: ${provider} — ${detail}`);
+        }
+    }
+    return lines.slice(0, 12);
+}
+export function renderTaskWait(snapshot, outcome = snapshot.outcome) {
+    const check = snapshot.check.status === "unknown" ? "checks unknown" : snapshot.check.status === "not-run" ? "checks not run" : `checks ${snapshot.check.status}${snapshot.check.exitCode === null ? "" : ` (exit ${snapshot.check.exitCode})`}`;
+    const run = snapshot.run === null ? "no run" : snapshot.replacedRun === null ? `run #${snapshot.run}` : `run #${snapshot.run}, a retry that replaced run #${snapshot.replacedRun}`;
+    return `${outcome} | ${run} | ${check} | next: ${snapshot.next}`;
+}

package/dist/ledger-chain.d.ts

@@ -0,0 +1,46 @@
+import type { Database } from "./store.js";
+export declare const LEDGER_CHAIN_SCHEMA = "\nCREATE TABLE IF NOT EXISTS ledger_seal (\n  id   INTEGER PRIMARY KEY,\n  prev TEXT NOT NULL,\n  hash TEXT NOT NULL\n);\nCREATE TRIGGER IF NOT EXISTS ledger_seal_no_update BEFORE UPDATE ON ledger_seal\nBEGIN SELECT RAISE(ABORT, 'the ledger chain is append-only'); END;\nCREATE TRIGGER IF NOT EXISTS ledger_seal_no_delete BEFORE DELETE ON ledger_seal\nBEGIN SELECT RAISE(ABORT, 'the ledger chain is append-only'); END;\nCREATE TABLE IF NOT EXISTS ledger_checkpoint (\n  id      INTEGER PRIMARY KEY AUTOINCREMENT,\n  through INTEGER NOT NULL,\n  hash    TEXT NOT NULL,\n  at      TEXT NOT NULL,\n  by      TEXT NOT NULL\n);\nCREATE TRIGGER IF NOT EXISTS ledger_checkpoint_no_update BEFORE UPDATE ON ledger_checkpoint\nBEGIN SELECT RAISE(ABORT, 'ledger checkpoints are append-only'); END;\nCREATE TRIGGER IF NOT EXISTS ledger_checkpoint_no_delete BEFORE DELETE ON ledger_checkpoint\nBEGIN SELECT RAISE(ABORT, 'ledger checkpoints are append-only'); END;\n";
+/** Where the chain starts: the previous fingerprint of the first entry. */
+export declare const LEDGER_GENESIS: string;
+/** A whole number column as JavaScript can hold it: one past 2^53 (only a hand edit puts one there) reads as its text,
+ * which `rowProblem` names, instead of failing the read. */
+export declare const safeWhole: (column: string, as?: string) => string;
+/** An entry's fingerprint: the previous one and the entry's own fields, in a fixed order. */
+export declare function entryHash(prev: string, row: Record<string, unknown>): string;
+export declare const IN_RANGE: string;
+/** Why a row can't be an entry the ledger wrote: each field is exactly the kind of value its writers store. */
+export declare function rowProblem(row: Record<string, unknown>): string | null;
+/** Seal every entry written since the last seal, in id order. Returns how many were sealed. Call inside a write transaction. */
+export declare function sealLedger(db: Database): number;
+export type LedgerChainReport = {
+    ok: boolean;
+    /** Entries checked, and the last sealed entry's id and fingerprint (the head). */
+    entries: number;
+    through: number | null;
+    head: string;
+    /** Entries written after the last seal (sealed on the next pass; not yet part of the proof). */
+    unsealed: number;
+    checkpoints: number;
+    /** The first place the chain breaks, in words. */
+    problem: {
+        id: number | null;
+        what: string;
+    } | null;
+    /** When the whole chain was last walked from its first entry (later entries were checked as they were added). */
+    checkedAt: string | null;
+};
+/** Where a walk may start instead of the first entry: a head this process walked to before. */
+export type VerifiedHead = {
+    through: number;
+    head: string;
+    entries: number;
+};
+/** Walk the chain: every entry sealed, every seal an entry, each fingerprint right and linked to the one before,
+ * and every checkpoint still matching. With `from`, the walk starts at a head verified earlier, after checking that
+ * the head is still there (a chain rebuilt since doesn't match it). Reads only; call inside one read transaction. */
+export declare function verifyLedgerChain(db: Database, from?: VerifiedHead, checkedAt?: string | null): LedgerChainReport;
+/** Whether the chain still ends at a head someone copied off the machine (`<through>:<hash>`). */
+export declare function matchesOutsideCheckpoint(db: Database, checkpoint: string): {
+    ok: boolean;
+    what: string;
+};

package/dist/ledger-chain.js

@@ -0,0 +1,187 @@
+/**
+ * v103: the action ledger as a hash chain. Every entry is sealed, in id
+ * order, with a fingerprint of its own fields and the previous entry's
+ * fingerprint; changing, removing or slipping in an entry breaks the chain
+ * from that point, and `verifyLedgerChain` names the first place it breaks.
+ *
+ * The ledger itself is append-only (its triggers refuse UPDATE and DELETE);
+ * the chain is what still shows it when someone with the database file drops
+ * those triggers. It has no secret key: someone who can rewrite the file can
+ * also drop seals and let the next pass reseal, so what proves history is a
+ * checkpoint's head copied off the machine (and, from sprint 6, streamed to
+ * the customer's log system), plus a running console noticing that a head it
+ * already walked to has changed.
+ *
+ * Entries are sealed shortly after they're written (by the worker, and
+ * before anything reads, verifies or exports the chain), so the triggers
+ * that write the ledger stay plain SQL any build can run.
+ */
+import { createHash } from "node:crypto";
+export const LEDGER_CHAIN_SCHEMA = `
+CREATE TABLE IF NOT EXISTS ledger_seal (
+  id   INTEGER PRIMARY KEY,
+  prev TEXT NOT NULL,
+  hash TEXT NOT NULL
+);
+CREATE TRIGGER IF NOT EXISTS ledger_seal_no_update BEFORE UPDATE ON ledger_seal
+BEGIN SELECT RAISE(ABORT, 'the ledger chain is append-only'); END;
+CREATE TRIGGER IF NOT EXISTS ledger_seal_no_delete BEFORE DELETE ON ledger_seal
+BEGIN SELECT RAISE(ABORT, 'the ledger chain is append-only'); END;
+CREATE TABLE IF NOT EXISTS ledger_checkpoint (
+  id      INTEGER PRIMARY KEY AUTOINCREMENT,
+  through INTEGER NOT NULL,
+  hash    TEXT NOT NULL,
+  at      TEXT NOT NULL,
+  by      TEXT NOT NULL
+);
+CREATE TRIGGER IF NOT EXISTS ledger_checkpoint_no_update BEFORE UPDATE ON ledger_checkpoint
+BEGIN SELECT RAISE(ABORT, 'ledger checkpoints are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS ledger_checkpoint_no_delete BEFORE DELETE ON ledger_checkpoint
+BEGIN SELECT RAISE(ABORT, 'ledger checkpoints are append-only'); END;
+`;
+/** Where the chain starts: the previous fingerprint of the first entry. */
+export const LEDGER_GENESIS = createHash("sha256").update("standing-orders/action-ledger/v103", "utf8").digest("hex");
+const FIELDS = ["id", "at", "actor", "repo", "task_id", "run_id", "action", "outcome", "source", "detail"];
+/** A whole number column as JavaScript can hold it: one past 2^53 (only a hand edit puts one there) reads as its text,
+ * which `rowProblem` names, instead of failing the read. */
+export const safeWhole = (column, as = column) => `CASE WHEN typeof(${column}) = 'integer' AND ${column} NOT BETWEEN -9007199254740991 AND 9007199254740991 THEN CAST(${column} AS TEXT) ELSE ${column} END AS ${as}`;
+/** The fields a seal covers, read safely. */
+const SEALED = FIELDS.map(name => name === "id" || name === "run_id" ? safeWhole(name) : name).join(", ");
+/** An entry's fingerprint: the previous one and the entry's own fields, in a fixed order. */
+export function entryHash(prev, row) {
+    const fields = FIELDS.map(name => { const value = row[name]; return value === undefined ? null : typeof value === "bigint" ? Number(value) : value; });
+    return createHash("sha256").update(`${prev}\n${JSON.stringify(fields)}`, "utf8").digest("hex");
+}
+/** The largest entry number a seal can name (JavaScript's safe integers); anything outside 1..LARGEST was put there by hand. */
+const LARGEST = Number.MAX_SAFE_INTEGER;
+export const IN_RANGE = `BETWEEN 1 AND ${LARGEST}`;
+/** Outside it, written so SQLite finds such rows by key rather than reading every row. */
+const OUTSIDE = (column) => `${column} < 1 OR ${column} > ${LARGEST}`;
+/** Why a row can't be an entry the ledger wrote: each field is exactly the kind of value its writers store. */
+export function rowProblem(row) {
+    const whole = (value) => typeof value === "number" && Number.isSafeInteger(value);
+    const text = (value) => typeof value === "string";
+    if (!whole(row["id"]))
+        return "a number the ledger never writes";
+    if (row["run_id"] !== null && !whole(row["run_id"]))
+        return "a run number the ledger never writes";
+    for (const name of ["at", "actor", "action", "outcome", "source"])
+        if (!text(row[name]))
+            return `a ${name} the ledger never writes`;
+    for (const name of ["repo", "task_id", "detail"])
+        if (row[name] !== null && !text(row[name]))
+            return `a ${name} the ledger never writes`;
+    return null;
+}
+/** Seal every entry written since the last seal, in id order. Returns how many were sealed. Call inside a write transaction. */
+export function sealLedger(db) {
+    const last = db.prepare(`SELECT id, hash FROM ledger_seal WHERE id ${IN_RANGE} ORDER BY id DESC LIMIT 1`).get();
+    let prevId = last === undefined ? 0 : Number(last["id"]);
+    let prev = last === undefined ? LEDGER_GENESIS : String(last["hash"]);
+    let sealed = 0;
+    const insert = db.prepare("INSERT INTO ledger_seal (id, prev, hash) VALUES (?, ?, ?)");
+    const next = db.prepare(`SELECT ${SEALED} FROM action_ledger WHERE id > ? AND id <= ${LARGEST} ORDER BY id LIMIT 1000`);
+    for (;;) {
+        const rows = next.all(prevId);
+        if (rows.length === 0)
+            return sealed;
+        for (const row of rows) {
+            const hash = entryHash(prev, row);
+            insert.run(Number(row["id"]), prev, hash);
+            prev = hash;
+            prevId = Number(row["id"]);
+            sealed++;
+        }
+    }
+}
+const PAGE = 1000;
+/** Rows of a keyset query (`WHERE id > ? ... ORDER BY id LIMIT n`), a page at a time. */
+function* pages(db, sql, from) {
+    const statement = db.prepare(sql);
+    let after = from;
+    for (;;) {
+        const page = statement.all(after);
+        yield* page;
+        if (page.length < PAGE)
+            return;
+        after = Number(page[page.length - 1]["id"]);
+    }
+}
+/** Walk the chain: every entry sealed, every seal an entry, each fingerprint right and linked to the one before,
+ * and every checkpoint still matching. With `from`, the walk starts at a head verified earlier, after checking that
+ * the head is still there (a chain rebuilt since doesn't match it). Reads only; call inside one read transaction. */
+export function verifyLedgerChain(db, from, checkedAt = null) {
+    let prev = from?.head ?? LEDGER_GENESIS, entries = from?.entries ?? 0, through = from?.through ?? null, kept = 0;
+    const report = (problem, unsealed = 0) => ({ ok: problem === null, entries, through, head: prev, unsealed, checkpoints: kept, problem, checkedAt });
+    // Entries, seals and checkpoints are numbered from 1 up to what a seal can name; anything outside was put there by hand.
+    const outside = db.prepare(`SELECT CAST(id AS TEXT) AS id FROM action_ledger WHERE ${OUTSIDE("id")} LIMIT 1`).get();
+    if (outside !== undefined)
+        return report({ id: null, what: `entry #${String(outside["id"])} was added outside the sealed history` });
+    const strayed = db.prepare(`SELECT CAST(id AS TEXT) AS id FROM ledger_seal WHERE ${OUTSIDE("id")} LIMIT 1`).get();
+    if (strayed !== undefined)
+        return report({ id: null, what: `a seal for entry #${String(strayed["id"])} was added outside the chain` });
+    const astray = db.prepare(`SELECT CAST(through AS TEXT) AS through FROM ledger_checkpoint WHERE typeof(through) <> 'integer' OR ${OUTSIDE("through")} LIMIT 1`).get();
+    if (astray !== undefined)
+        return report({ id: null, what: `a checkpoint names entry #${String(astray["through"])}, outside the chain` });
+    const checkpoints = db.prepare("SELECT through, hash FROM ledger_checkpoint ORDER BY id").all()
+        .map(one => ({ through: Number(one["through"]), hash: String(one["hash"]) }));
+    kept = checkpoints.length;
+    if (from !== undefined) {
+        const still = db.prepare("SELECT hash FROM ledger_seal WHERE id = ?").get(from.through);
+        if (still === undefined || String(still["hash"]) !== from.head)
+            return report({ id: from.through, what: `the chain was rewritten since it was last checked (entry #${from.through} changed)` });
+    }
+    const rows = pages(db, `SELECT ${SEALED} FROM action_ledger WHERE id > ? AND id <= ${LARGEST} ORDER BY id LIMIT ${PAGE}`, from?.through ?? 0);
+    const seals = pages(db, `SELECT id, prev, hash FROM ledger_seal WHERE id > ? AND id <= ${LARGEST} ORDER BY id LIMIT ${PAGE}`, from?.through ?? 0);
+    const wanted = new Set(checkpoints.map(one => one.through));
+    const reached = new Map();
+    let row = rows.next();
+    for (let next = seals.next(); !next.done; next = seals.next()) {
+        const seal = next.value;
+        const id = Number(seal["id"]);
+        const entry = row.done ? undefined : row.value;
+        if (entry === undefined || Number(entry["id"]) > id)
+            return report({ id, what: `entry #${id} was removed after it was sealed` });
+        if (Number(entry["id"]) < id)
+            return report({ id: Number(entry["id"]), what: `entry #${Number(entry["id"])} was added inside the sealed history` });
+        const odd = rowProblem(entry);
+        if (odd !== null)
+            return report({ id, what: `entry #${id} holds ${odd}` });
+        if (String(seal["prev"]) !== prev)
+            return report({ id, what: `entry #${id} doesn't follow the entry before it` });
+        const hash = entryHash(prev, entry);
+        if (hash !== String(seal["hash"]))
+            return report({ id, what: `entry #${id} was changed after it was sealed` });
+        prev = hash;
+        through = id;
+        if (wanted.has(id))
+            reached.set(id, hash);
+        entries++;
+        row = rows.next();
+    }
+    // Every checkpoint row, each on its own: a later row for the same entry can't cover for an earlier one.
+    const sealedAt = db.prepare("SELECT hash FROM ledger_seal WHERE id = ?");
+    for (const checkpoint of checkpoints) {
+        const walked = reached.get(checkpoint.through) ?? (from !== undefined && checkpoint.through <= from.through ? sealedAt.get(checkpoint.through)?.["hash"] : undefined);
+        if (walked !== checkpoint.hash)
+            return report({ id: checkpoint.through, what: `the chain no longer matches the checkpoint at entry #${checkpoint.through}` });
+    }
+    let unsealed = 0;
+    for (; !row.done; row = rows.next())
+        unsealed++;
+    return report(null, unsealed);
+}
+/** Whether the chain still ends at a head someone copied off the machine (`<through>:<hash>`). */
+export function matchesOutsideCheckpoint(db, checkpoint) {
+    const match = /^(\d+):([a-f0-9]{64})$/.exec(checkpoint.trim());
+    if (match === null)
+        return { ok: false, what: "A checkpoint looks like 1234:<64 hex characters>." };
+    if (!Number.isSafeInteger(Number(match[1])))
+        return { ok: false, what: "A checkpoint looks like 1234:<64 hex characters>." };
+    const seal = db.prepare("SELECT hash FROM ledger_seal WHERE id = ?").get(Number(match[1]));
+    if (seal === undefined)
+        return { ok: false, what: `The chain has no sealed entry #${match[1]}.` };
+    return String(seal["hash"]) === match[2]
+        ? { ok: true, what: `The chain still matches the checkpoint at entry #${match[1]}.` }
+        : { ok: false, what: `The chain does NOT match the checkpoint at entry #${match[1]}: history up to it was rewritten.` };
+}

package/dist/ledger-csv.d.ts

@@ -0,0 +1,4 @@
+import type { LedgerEntry } from "./action-ledger.js";
+export declare function csvCell(value: string | number | null): string;
+export declare const LEDGER_CSV_HEADER: string;
+export declare function ledgerCsvRows(rows: readonly LedgerEntry[]): string;

package/dist/ledger-csv.js

@@ -0,0 +1,11 @@
+// Quotes and CR/LF survive a CSV round trip. Prefix spreadsheet formulas
+// with an apostrophe, including formulas hidden behind whitespace.
+export function csvCell(value) {
+    const raw = value === null ? "" : String(value);
+    const safe = /^[\s\uFEFF]*[=+@-]/u.test(raw) || /^[\t\r\n]/u.test(raw) ? "'" + raw : raw;
+    return `"${safe.replaceAll('"', '""')}"`;
+}
+export const LEDGER_CSV_HEADER = "\uFEFF" + ["ID", "Time (UTC)", "Actor", "Project", "Task", "Run", "Action", "Outcome", "Source", "Detail"].map(csvCell).join(",") + "\r\n";
+export function ledgerCsvRows(rows) {
+    return rows.map(row => [row.id, row.at, row.actor, row.repo, row.taskId, row.runId, row.action, row.outcome, row.source, row.detail].map(csvCell).join(",") + "\r\n").join("");
+}

package/dist/ledger-view.d.ts

@@ -0,0 +1,24 @@
+import type { LedgerEntry } from "./action-ledger.js";
+/** v103: the chain's state in one line, and (for an instance operator) a checkpoint to copy off the machine. */
+export type LedgerChainView = {
+    ok: boolean;
+    entries: number;
+    through: number | null;
+    head: string;
+    unsealed: number;
+    problem: {
+        id: number | null;
+        what: string;
+    } | null;
+    /** When the whole chain was last walked. */
+    checkedAt: string | null;
+    latest: {
+        through: number;
+        hash: string;
+        at: string;
+    } | null;
+    csrf: string | null;
+    /** Today (UTC, YYYY-MM-DD): the audit export's default range ends here. */
+    today: string;
+};
+export declare function ledgerBody(rows: LedgerEntry[], projects: readonly string[], params: URLSearchParams, chain?: LedgerChainView): string;

package/dist/ledger-view.js

@@ -0,0 +1,58 @@
+import { projectName } from "./project.js";
+const html = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+/** The ledger's kinds of event, as the filter names them. */
+const EVENT_KINDS = [["work", "Work"], ["request", "Requests"], ["access", "Access"], ["sign-in", "Sign-ins"], ["policy", "Policy changes"]];
+function chainHtml(chain) {
+    const html = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+    const status = chain.ok
+        ? `<p class="ledger-chain ok" data-ledger-chain="ok"><strong>Chain verified</strong> · ${chain.entries} entries through #${chain.through ?? 0} · head <code>${html(chain.head.slice(0, 16))}…</code>${chain.checkedAt === null ? "" : ` · checked in full ${html(chain.checkedAt.slice(11, 16))} UTC`}</p>`
+        : `<p class="ledger-chain problem" role="alert" data-ledger-chain="broken"><strong>Chain broken</strong> · ${html(chain.problem?.what ?? "the chain doesn't verify")}</p>`;
+    const latest = chain.latest === null ? "" : `<p class="meta ledger-checkpoint">Latest checkpoint (${html(chain.latest.at.slice(0, 16).replace("T", " "))} UTC), copy it somewhere outside this machine: <code class="ledger-checkpoint-value">${chain.latest.through}:${html(chain.latest.hash)}</code></p>`;
+    const make = chain.csrf === null ? "" : `<form method="post" action="/ledger/checkpoint" class="ledger-checkpoint-form"><input type="hidden" name="csrf" value="${html(chain.csrf)}"><button type="submit">Make a checkpoint</button></form>`;
+    const start = new Date(Date.parse(`${chain.today}T00:00:00Z`) - 29 * 86_400_000).toISOString().slice(0, 10);
+    const exportForm = `<details class="ledger-filter-panel"><summary>Audit export</summary><form method="get" action="/ledger/export" class="ledger-filters ledger-export" aria-label="Audit export">` +
+        `<label>From<input type="date" name="from" value="${html(start)}" required></label><label>To<input type="date" name="to" value="${html(chain.today)}" required></label>` +
+        `<button type="submit">Download</button></form><p class="meta">Every entry in the range with its seal, and an evidence pack for each task it names. JSON.</p></details>`;
+    return `<section class="ledger-chain-panel" aria-label="Ledger integrity">${status}${latest}${make}${exportForm}</section>`;
+}
+export function ledgerBody(rows, projects, params, chain) {
+    const selected = (key, value) => params.get(key) === value ? " selected" : "";
+    const more = rows.length > 50;
+    const shown = rows.slice(0, 50);
+    const fresh = new URLSearchParams();
+    for (const key of ["project", "actor", "source", "outcome", "task"]) {
+        const value = params.get(key);
+        if (value)
+            fresh.set(key, value);
+    }
+    const next = new URLSearchParams(fresh);
+    if (shown.length)
+        next.set("before", String(shown.at(-1).id));
+    const csv = new URLSearchParams(fresh);
+    csv.set("format", "csv");
+    return `<style>
+.ledger-heading{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap}.ledger-heading h1{margin:0}.ledger-caption{margin:8px 0 12px}
+.ledger-filter-panel{margin-bottom:12px}.ledger-filter-panel summary{font-size:13px;padding:6px 0;cursor:pointer}.ledger-filters{display:grid;grid-template-columns:repeat(5,minmax(0,1fr)) auto auto;gap:8px;align-items:end;margin:0 0 12px}.ledger-filters label{display:grid;gap:3px;min-width:0;font-size:12px}.ledger-filters input,.ledger-filters select{width:100%;min-width:0;box-sizing:border-box;margin:0;padding:6px 8px;font-size:13px}.ledger-filters button{padding:7px 12px}.ledger-filters>a{padding:8px 0;font-size:13px}
+.ledger-detail{display:block;color:var(--muted-foreground);font-size:12px}.ledger-list{border:1px solid var(--border);border-radius:8px;overflow:hidden}.ledger-event{display:grid;grid-template-columns:140px minmax(90px,1fr) minmax(160px,2fr) minmax(100px,1fr) minmax(100px,1fr);gap:8px;align-items:baseline;padding:7px 10px;border-bottom:1px solid var(--border);font-size:13px;line-height:1.4;overflow-wrap:anywhere}.ledger-event:last-child{border-bottom:0}.ledger-event .actor{color:inherit;font-weight:600;text-decoration:none}.ledger-time,.ledger-place,.ledger-result small{font-size:11px;color:var(--muted-foreground)}.ledger-time time{font-variant-numeric:tabular-nums}.ledger-place a{display:block}.ledger-result small{display:block}.ledger-labels{font-size:11px;color:var(--muted-foreground);font-weight:600}.ledger-empty{padding:12px}
+@media(max-width:1000px){.ledger-filters{grid-template-columns:repeat(3,minmax(0,1fr)) auto}.ledger-event{grid-template-columns:122px minmax(80px,1fr) minmax(130px,2fr) minmax(85px,1fr)}.ledger-place{grid-column:2/4}.ledger-result{grid-column:4;grid-row:1/3}.ledger-labels{display:none}}
+@media(max-width:600px){.ledger-filters{grid-template-columns:repeat(2,minmax(0,1fr))}.ledger-event{grid-template-columns:minmax(0,1fr) auto;gap:2px 8px;padding:8px 10px}.ledger-actor{grid-column:1;grid-row:1}.ledger-action{grid-column:1;grid-row:2}.ledger-result{grid-column:2;grid-row:1/3;text-align:right}.ledger-time{grid-column:1;grid-row:3}.ledger-place{grid-column:2;grid-row:3;text-align:right}.ledger-place a{display:inline}.ledger-heading>a{font-size:13px}}
+.ledger-chain-panel{margin:0 0 12px}.ledger-chain{margin:0 0 4px;font-size:13px}.ledger-chain.ok strong{color:var(--success)}.ledger-checkpoint code{overflow-wrap:anywhere;user-select:all}.ledger-checkpoint-form{margin:6px 0 0}.ledger-export{grid-template-columns:repeat(2,minmax(0,180px)) auto;margin-bottom:4px}
+</style><div class="ledger-heading"><h1>Action ledger</h1><a href="/ledger?${html(csv.toString())}" download>Export CSV</a></div>${chain === undefined ? "" : chainHtml(chain)}
+<p class="meta ledger-caption">${shown.length} actions on this page · CSV includes all matching actions · Times in UTC</p>
+<details class="ledger-filter-panel"><summary>Filters · ${fresh.size === 0 ? "all actions" : `${fresh.size} active`}</summary>
+<form method="get" action="/ledger" class="ledger-filters" aria-label="Filter action ledger">
+<label>Project<select name="project"><option value="">All accessible projects</option>${projects.map(repo => `<option value="${html(repo)}"${selected("project", repo)}>${html(projectName(repo))}</option>`).join("")}</select></label>
+<label>Person or worker<input type="text" name="actor" value="${html(params.get("actor") ?? "")}" placeholder="Any actor"></label>
+<label>Events<select name="source"><option value="">All events</option>${EVENT_KINDS.map(([value, label]) => `<option value="${value}"${selected("source", value)}>${label}</option>`).join("")}</select></label>
+<label>Outcome<input type="text" name="outcome" value="${html(params.get("outcome") ?? "")}" placeholder="Any outcome"></label>
+<label>Task<input type="text" name="task" value="${html(params.get("task") ?? "")}" placeholder="Any task"></label>
+<button type="submit">Filter</button><a href="/ledger">Clear</a></form></details>
+<div class="ledger-list" aria-label="Action history"><div class="ledger-event ledger-labels" aria-hidden="true"><span>Time (UTC)</span><span>Actor</span><span>Action</span><span>Project / work</span><span>Outcome / event</span></div>${shown.length === 0 ? `<p class="ledger-empty">No actions match these filters yet.</p>` : shown.map(row => {
+        const subject = row.runId !== null ? `<a href="/r/${row.runId}">Run #${row.runId}</a>` : row.taskId !== null ? `<a href="/t/${encodeURIComponent(row.taskId)}">${html(row.taskId)}</a>` : "";
+        const byActor = new URLSearchParams(fresh);
+        byActor.set("actor", row.actor);
+        return `<article class="ledger-event" data-ledger-id="${row.id}"><div class="ledger-time"><time datetime="${html(row.at)}" title="${html(row.at)}">${html(row.at.slice(0, 19).replace("T", " "))}</time></div><div class="ledger-actor"><a class="actor" href="/ledger?${html(byActor.toString())}" title="Filter by this actor">${html(row.actor)}</a></div><div class="ledger-action">${html(row.action)}${row.detail === null ? "" : `<small class="ledger-detail">${html(row.detail)}</small>`}</div><div class="ledger-place">${row.repo === null ? "Instance" : html(projectName(row.repo))} ${subject}</div><div class="ledger-result">${html(row.outcome)}<small>${html(row.source)}</small></div></article>`;
+    }).join("")}</div>
+<p class="row"><a href="/ledger?${html(fresh.toString())}">Newest actions</a>${more ? `<a rel="next" href="/ledger?${html(next.toString())}">Older actions</a>` : ""}</p>
+<p class="meta">Accepted requests record acceptance; worker events record results. History starts from this upgrade. Review evidence is on each task or run.</p>`;
+}