seisin 0.2.0 → 0.4.0

package/src/intake.js

@@ -0,0 +1,243 @@
+/**
+ * The parent's intake: what arrives during a run, checked, and written down.
+ *
+ * Two sources, and they are not equally trustworthy. The hook runs inside the
+ * box, so everything it sends is a claim by the process being recorded. The
+ * kernel is the thing that actually refused. Both end up as log lines and,
+ * sometimes, as requests in front of a person; this module is where each is
+ * recomputed from the policy rather than believed.
+ *
+ * Every line written here carries two fields that make it evidence rather
+ * than a sentence:
+ *
+ *   - `run`, the id of the run that produced it — the same id as the nonce in
+ *     the kernel's command tag and the run's private directory (rundir.js).
+ *     Before, the log had no run marker and "how many runs since" was guessed
+ *     from 10-minute gaps.
+ *   - `policy`, a hash of the policy file the run STARTED with. The kernel
+ *     enforces that one for the whole run, whatever happens to the file
+ *     afterwards, and `review` reading today's policy over last week's lines
+ *     could not tell a grant made since from one that was always there.
+ *
+ * Pulled out of run.js, which held both handlers inline between the spawn and
+ * the signal handling — 180 lines of policy arithmetic inside the launcher.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { toRepoRelative } from "./paths.js";
+import { explain, ownersOf } from "./owners.js";
+import { append, logPath } from "./log.js";
+import { record, requestsPath } from "./requests.js";
+import { inScope, scopeOf, reachedForContent } from "./violations.js";
+import { mcpServer } from "./hook.js";
+
+/** A hash of the policy file as it is now, short: it names a version, it proves nothing. */
+export function policyId(config) {
+  try {
+    return createHash("sha256").update(readFileSync(config.path)).digest("hex").slice(0, 12);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The handlers for one run.
+ *
+ * `fromHook(to, entry)` is the spool's sink; `fromKernel(denial)` is
+ * watchDenials' callback; `stats` counts what the kernel said that was left
+ * out on purpose, for the line at the end of the run.
+ */
+export function intake({ config, role, runId, observe = false, settings, notify }) {
+  const stamp = { run: runId.slice(0, 8), policy: policyId(config) };
+  const log = (entry) => append(logPath(config.root), { ...entry, ...stamp });
+  const ask = (asked) => { record(requestsPath(config.root), asked); notify?.maybe(asked); };
+
+  const scope = scopeOf(settings, config.root);
+  const keyDirs = (config.keyDirs ?? []).map((d) => (d.startsWith("/") ? d : join(config.root, d)));
+  const connects = new Set();         // one line per refused target per run
+  const stats = { offPolicy: 0, walks: 0 };
+
+  /**
+   * Nothing from inside the box is taken at its word.
+   *
+   * The sender is the process being recorded, so every field it supplies is
+   * a claim. Two of them matter. `role` decides whose request this is — left
+   * alone, a frontend agent could file one as backend and wait for a human to
+   * approve it. `owners` decides who the queue says it belongs to, and the
+   * parent can work that out itself from the policy.
+   *
+   * So the role is overwritten with the role of this run, the owners are
+   * recomputed, and anything shaped wrong is dropped. Forging a *log* line is
+   * noise. Forging a *request* is a sentence placed in front of a person for
+   * approval, and that is a different thing entirely.
+   */
+  function fromHook(to, entry) {
+    if (!entry || typeof entry !== "object") return;
+
+    /**
+     * An MCP tool call. It names a resource, not a path, so it is recorded and
+     * never queued — which servers a role may load is a change to its `mcp`
+     * list, not a grant a person approves, the same shape as never_writes. The
+     * verdict is recomputed here from the same list rather than believed from
+     * inside the box: the server is parsed from the tool name and asked of the
+     * policy, so a line claiming "allowed" for a server the role may not load
+     * comes back marked `disputed`.
+     */
+    if (to === "log" && entry.action === "use") {
+      if (typeof entry.target !== "string" || !entry.target.trim()) return;
+      if (!["allowed", "denied", "observed"].includes(entry.verdict)) return;
+      const server = mcpServer(entry.target);
+      const v = server ? explain(config, role, "mcp", server) : { allowed: false };
+      const expected = observe ? "observed" : v.allowed ? "allowed" : "denied";
+      return void log({
+        at: entry.at, role,
+        tool: String(entry.tool ?? "").slice(0, 40),
+        action: "use", kind: "tool",
+        target: entry.target.slice(0, 1000),
+        verdict: entry.verdict, owners: [],
+        reason: String(entry.reason ?? "").slice(0, 500),
+        ...(expected !== entry.verdict ? { disputed: expected } : {}),
+      });
+    }
+
+    if (entry.action !== "read" && entry.action !== "write") return;
+    if (typeof entry.target !== "string" || !entry.target.trim()) return;
+
+    if (to === "log") {
+      // The same treatment the queue already got. The role was overwritten but
+      // everything else was passed through, so a process inside the box could
+      // write "allowed" lines for paths it never touched — which would not move
+      // the boundary, but would move `review`, and `init --from-observations`
+      // builds a policy out of exactly this.
+      if (!["allowed", "denied", "observed"].includes(entry.verdict)) return;
+      /**
+       * The verdict is the hook's account of what it did, so it stays — but it
+       * is checked. The parent works out what the policy this run started with
+       * says, and when the two differ the line carries `disputed` with the
+       * parent's answer. Two causes, both worth seeing: the policy file changed
+       * since the run started (the hook reads it fresh, the kernel does not), or
+       * the line was not written by the hook at all.
+       */
+      const expected = observe
+        ? "observed"
+        : explain(config, role, entry.action, entry.target).allowed ? "allowed" : "denied";
+      return void log({
+        at: entry.at,
+        role,
+        tool: String(entry.tool ?? "").slice(0, 40),
+        action: entry.action,
+        kind: entry.kind === "key" ? "key" : "file",
+        target: entry.target.slice(0, 1000),
+        verdict: entry.verdict,
+        owners: ownersOf(config, entry.target),      // recomputed, never taken
+        reason: String(entry.reason ?? "").slice(0, 500),
+        ...(expected !== entry.verdict ? { disputed: expected } : {}),
+      });
+    }
+
+    /**
+     * The policy has to actually refuse it, or it does not belong in a queue.
+     *
+     * Nothing checked. A process inside the box could file a request for a path
+     * its own role already owns, and the queue would print *first refused on
+     * …* about something that was never refused — a sentence placed in front of
+     * a person for approval, describing an event that did not happen.
+     *
+     * Same treatment as `owners` above: the claim is recomputed here rather
+     * than believed. It is the policy answering a question about itself, which
+     * is arithmetic, and it is the parent asking — the one process the confined
+     * side cannot reach.
+     *
+     * This does not require the agent to have *tried*. Asking for a permission
+     * before reaching for it is a reasonable thing to do, and the wording says
+     * "asked" rather than "refused" for exactly that case. What it rules out is
+     * a request for something that is not refused at all — nor for a
+     * `never_writes` path, git's metadata, or a protected one, none of which a
+     * grant can open.
+     */
+    const v = explain(config, role, entry.action, entry.target);
+    if (v.allowed || v.neverWrites || v.gitMetadata || v.protected) return;
+    // The owners explain found: for a key that is who declares it, not who
+    // writes the directory it sits in — the queue said "owned by dev" about
+    // backend's key because dev writes `**`.
+    ask({ role, action: entry.action, target: entry.target, owners: v.owners });
+  }
+
+  function fromKernel(d) {
+    /**
+     * A refused connection: logged, never queued.
+     *
+     * Once per target per run, because the thing that dials a closed port is
+     * usually a readiness loop, and a loop polling a database every half second
+     * would otherwise write the log the size of the wait. And no request: a port
+     * is not a territory anyone owns, so there is nobody to hand it to — the
+     * sentence says what the policy would have to change instead.
+     */
+    if (d.action === "connect") {
+      if (connects.has(d.path)) return;
+      connects.add(d.path);
+      const v = explain(config, role, "connect", d.path);
+      log({
+        at: new Date().toISOString(), role, tool: "kernel", source: "kernel",
+        action: "connect", kind: "network", target: d.path, verdict: "denied",
+        owners: [], reason: d.operation, ...(v.listed ? { listed: true } : {}),
+      });
+      return;
+    }
+    if (!inScope(d.path, scope)) { stats.offPolicy++; return; }
+    if (!reachedForContent(d)) { stats.walks++; return; }
+    // Relative inside the repo, absolute outside it. A role can be refused at
+    // ~/.ssh under `isolate`, and "../../../.ssh/id_rsa" would be a worse
+    // answer to "what was refused" than the path itself.
+    const rel = toRepoRelative(config, d.path);
+
+    /**
+     * A refusal the hook never saw still leaves a request behind.
+     *
+     * Without this the two halves of the record disagree in the worst
+     * direction: `review` would show a role stopped repeatedly on a directory
+     * while the queue held nothing to approve, so the one refusal a person most
+     * needed to see — the one that escaped the hook — would be the one with no
+     * way to act on it.
+     *
+     * There is no double counting to avoid. When the hook catches something it
+     * denies the tool call outright and the command never runs, so the kernel
+     * never sees it. These are the ones that got past it, which is the whole
+     * reason this exists. Inside the repo only: `~/.ssh` is refused on purpose
+     * under `isolate` and is not a territory anyone is meant to ask for.
+     */
+    const verdict = rel !== d.path && d.action === "write"
+      ? explain(config, role, "write", rel)
+      : null;
+    const barred = verdict?.neverWrites ?? null;
+    const unaskable = verdict?.gitMetadata === true || verdict?.protected != null;
+    // A request for something the policy already grants cannot be approved into
+    // anything: it is misattribution or a kernel/policy mismatch, and either way
+    // the line in the log is the evidence, not a question for a person. The hook
+    // path has always had this check; the kernel path did not, which is how a
+    // role ended up asking for its own territory.
+    const granted = verdict?.allowed === true;
+    if (rel !== d.path && !barred && !unaskable && !granted)
+      ask({ role, action: d.action, target: rel, owners: ownersOf(config, rel) });
+
+    log({
+      at: new Date().toISOString(),
+      role,
+      tool: "kernel",
+      source: "kernel",
+      action: d.action,
+      kind: keyDirs.some((k) => d.path === k || d.path.startsWith(k + "/")) ? "key" : "file",
+      target: rel,
+      verdict: "denied",
+      owners: ownersOf(config, rel),
+      reason: d.operation,
+      // So the log can tell a subtraction doing its job from a missing permission,
+      // and a protected file from a territory somebody could be asked for.
+      ...(barred ? { neverWrites: barred } : {}),
+      ...(verdict?.protected ? { protected: verdict.protected } : {}),
+    });
+  }
+
+  return { fromHook, fromKernel, stats };
+}

package/src/keys.js

@@ -41,9 +41,21 @@
  */
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { resolve, isAbsolute } from "node:path";
+import { resolve, isAbsolute, delimiter } from "node:path";
 import { BASE, DEFAULTS } from "./env.js";
 import { SOCK_ENV } from "./spool.js";
+import { resolveExecutable, trustedPath } from "./surface.js";
+
+/**
+ * How long a provider may take. A minute, because the slow case is a person:
+ * `op` and the keychain can put a prompt in front of someone who is not
+ * looking at the screen yet. Before this there was no limit, and a provider
+ * stuck on a prompt nobody could see held the run with no message at all.
+ */
+export const PROVIDER_TIMEOUT_MS = 60_000;
+
+/** A credential is bytes, not megabytes. Past this it is not a key. */
+const PROVIDER_MAX_BYTES = 1024 * 1024;
 
 /**
  * `scheme://rest`, and nothing cleverer.
@@ -202,15 +214,78 @@ function fromJson(obj, key, ref) {
   return String(v);
 }
 
+/**
+ * One `NAME=value` line's value, the way dotenv reads it — or a refusal.
+ *
+ * Compared against dotenv 16 on the same file (2026-09-23), three lines came
+ * back different, and a different value is a wrong credential handed over
+ * without a word:
+ *
+ *   - `A=abc # comment` — dotenv drops the comment; this kept it.
+ *   - a name defined twice — dotenv takes the last; this took the first.
+ *   - a quoted value spanning lines — dotenv reads it whole; this returned
+ *     the first line with its quote.
+ *
+ * The comment is read like dotenv, because there is one reading of it. The
+ * other two are refused, because loaders disagree about them and picking one
+ * is guessing which credential somebody meant.
+ */
+function dotEnvValue(raw, ref, key) {
+  const v = raw.trim();
+  const q = v[0];
+  if (q === '"' || q === "'" || q === "`") {
+    // The closing quote is the first one not escaped with a backslash, as in
+    // dotenv's own pattern: `"a\"b"` is one value, `a\"b`, not `a\`.
+    let end = -1;
+    for (let i = 1; i < v.length; i++) {
+      if (v[i] === "\\") { i++; continue; }
+      if (v[i] === q) { end = i; break; }
+    }
+    if (end === -1)
+      throw new Error(
+        `key "${ref}": ${key}= opens a ${q} quote that does not close on its line.\n` +
+        `  A value across several lines is read differently by different loaders, so seisin ` +
+        `does not read it. Put the credential on one line, or in a file of its own.`);
+    // Only a comment may follow the closing quote. `A="a" b` is read by dotenv
+    // as the whole line, quotes included, and by others as `a`.
+    const rest = v.slice(end + 1).trim();
+    if (rest && !rest.startsWith("#"))
+      throw new Error(
+        `key "${ref}": ${key}= has text after its closing quote (${rest.slice(0, 20)}…).\n` +
+        `  Loaders disagree on what that value is. Quote the whole value.`);
+    const inner = v.slice(1, end);
+    // Inside double quotes dotenv turns \n and \r into the characters — the
+    // shape a PEM key takes in a .env. Handed over literally, the key has a
+    // backslash and an n where its line breaks go, and it does not parse.
+    return q === '"' ? inner.replace(/\\n/g, "\n").replace(/\\r/g, "\r") : inner;
+  }
+  const bare = v.replace(/\s+#.*$/, "");
+  // A `#` inside an unquoted value: dotenv 16 cuts the value there
+  // (`tok_#_123` → `tok_`), python-dotenv and docker compose keep it.
+  if (bare.includes("#"))
+    throw new Error(
+      `key "${ref}": the value of ${key}= contains a # without quotes.\n` +
+      `  Some loaders read everything after it as a comment and some do not, so the ` +
+      `credential depends on who reads the file. Quote it: ${key}="…".`);
+  return bare;
+}
+
 function fromDotEnv(text, key, ref) {
   let sawAny = false;
+  let found = null;
   for (const line of text.split(/\r?\n/)) {
     const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
     if (!m) continue;
     sawAny = true;
     if (m[1] !== key) continue;
-    return m[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+    if (found !== null)
+      throw new Error(
+        `key "${ref}": ${key}= is defined more than once in that file.\n` +
+        `  dotenv takes the last one and other loaders the first, so which credential is meant ` +
+        `is not written down. Keep one.`);
+    found = dotEnvValue(m[2], ref, key);
   }
+  if (found !== null) return found;
   /**
    * Two different failures, and telling them apart is the whole message.
    *
@@ -437,16 +512,43 @@ export function modeOf(config, role, entry) {
  *     is — a provider that prints the secret and then exits non-zero would
  *     otherwise put it in the terminal and the log.
  */
-export function resolveRef(entry, provider, { run = spawnSync, root = "." } = {}) {
+export function resolveRef(entry, provider, { run = spawnSync, root = ".", config = null, env = process.env } = {}) {
   if (provider?.builtin === "file" || (provider === undefined && entry.scheme === "file"))
     return readFileRef(entry, root);
   const argv = provider.command.map((part) => part.replaceAll("{ref}", entry.ref));
-  const r = run(argv[0], argv.slice(1), { encoding: "utf8" });
+  /**
+   * Found where no role can write, and handed the same PATH.
+   *
+   * `spawnSync("fakeprov")` searched the parent's PATH, and a PATH directory
+   * inside a territory made the next run execute whatever that role had put
+   * there — outside the box, as you. Measured on 2026-09-23 with a marker file.
+   * The provider's own PATH is narrowed the same way, because a provider that
+   * is a script starts with `#!/usr/bin/env bash` and looks its interpreter up
+   * again. Without a config (a caller embedding seisin), or with a `run` of the
+   * caller's own, the argv is handed over as given: finding the program is part
+   * of spawning it, and whoever replaced the spawn owns that too.
+   */
+  const opts = { encoding: "utf8", timeout: PROVIDER_TIMEOUT_MS, maxBuffer: PROVIDER_MAX_BYTES };
+  if (config && run === spawnSync) {
+    argv[0] = resolveExecutable(argv[0], config, env);
+    opts.env = { ...env, PATH: trustedPath(config, env).join(delimiter) };
+  }
+  const r = run(argv[0], argv.slice(1), opts);
+  if (r.error?.code === "ETIMEDOUT")
+    throw new Error(
+      `key "${entry.raw}": the ${entry.scheme} provider (${argv[0]}) did not answer in ` +
+      `${PROVIDER_TIMEOUT_MS / 1000} s and was stopped.\n` +
+      `  A provider that waits on a prompt nobody sees would otherwise hold the run forever.`);
   if (r.error)
     throw new Error(
       `key "${entry.raw}": could not run the ${entry.scheme} provider (${argv[0]}): ${r.error.message}`);
   if (r.status !== 0) {
-    const said = (r.stderr ?? "").trim().split("\n").slice(0, 3).join("\n    ");
+    // Whatever it printed on stdout is taken out of stderr before stderr is
+    // shown: a provider that echoes the secret to both and then fails would
+    // otherwise put it in the terminal through the error meant to explain it.
+    const leaked = (r.stdout ?? "").trim();
+    const clean = leaked.length >= 4 ? (r.stderr ?? "").split(leaked).join("‹redacted›") : (r.stderr ?? "");
+    const said = clean.trim().split("\n").slice(0, 3).map((l) => l.slice(0, 200)).join("\n    ");
     throw new Error(
       `key "${entry.raw}": the ${entry.scheme} provider exited ${r.status ?? "on a signal"}.` +
       (said ? `\n    ${said}` : "") +
@@ -473,7 +575,7 @@ export function resolveRef(entry, provider, { run = spawnSync, root = "." } = {}
  * should say so without asking anyone's keychain for a password first.
  */
 export function resolveKeys(config, role, opts = {}) {
-  opts = { root: config.root ?? ".", ...opts };
+  opts = { root: config.root ?? ".", config, ...opts };
   const refs = role.keyEntries.filter((e) => e.kind === "ref");
   const plan = refs.map((entry) => ({ entry, mode: modeOf(config, role, entry) }));
   return plan.map((p) => ({

package/src/log.js

@@ -13,8 +13,9 @@
  * tries the parent's socket first for exactly that reason; writing the file
  * directly is what happens when there is no parent, outside the box.
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, join } from "node:path";
 import { STATE_DIR, LOG_NAME } from "./layout.js";
 import { send } from "./spool.js";
 
@@ -37,13 +38,211 @@ export function append(file, entry) {
   if (send("log", entry)) return true;
   try {
     mkdirSync(dirname(file), { recursive: true });
-    appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...entry }) + "\n");
+    withLock(file, () => {
+      // Rotate first, under the same lock: a full segment is renamed away and a
+      // fresh one seeded so the chain continues, then this line lands in the new
+      // segment. Done here so the size check and the append never race.
+      maybeRotate(file);
+      // `prev` goes last and is computed from the previous line exactly as it
+      // sits on disk, so verifying needs nothing but the file.
+      const line = JSON.stringify({ at: new Date().toISOString(), ...entry, prev: hashOf(lastLine(file)) });
+      appendFileSync(file, line + "\n");
+    });
     return true;
   } catch {
     return false;
   }
 }
 
+/**
+ * When the current segment fills, retire it and start a fresh one that still
+ * chains.
+ *
+ * An append-only file that only grows is the right default and the wrong
+ * forever: a busy team writes megabytes of it, and `verify` walks all of them
+ * on every run. Rotation caps the size of the file three tools tail while
+ * keeping the property that made the chain worth having — that a deletion shows.
+ *
+ * The retired segment keeps its own chain intact; the new segment's first line
+ * is a `rotated` marker whose `prev` is the retired segment's last hash, so the
+ * two verify as one chain across the cut (`verifyLog`). The comment on GENESIS
+ * asked for exactly this. Segments are numbered upward, `.1` the oldest, and
+ * the oldest beyond the keep count are dropped — the only place seisin removes
+ * a record, and it removes whole retired segments, never a line.
+ */
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;   // 8 MiB per segment
+const DEFAULT_KEEP = 5;                        // retired segments kept beside the current one
+
+function envInt(name, fallback) {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+/** Every segment of the log, oldest → newest, current last. */
+export function logSegments(file) {
+  const dir = dirname(file);
+  const base = basename(file);
+  let names = [];
+  try { names = readdirSync(dir); } catch { return existsSync(file) ? [file] : []; }
+  const archives = names
+    .map((n) => {
+      if (!n.startsWith(base + ".")) return null;
+      const seq = Number(n.slice(base.length + 1));
+      return Number.isInteger(seq) && seq > 0 ? { seq, path: join(dir, n) } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.seq - b.seq)
+    .map((a) => a.path);
+  if (existsSync(file)) archives.push(file);
+  return archives;
+}
+
+function maybeRotate(file) {
+  let sz = 0;
+  try { sz = statSync(file).size; } catch { return; }
+  if (sz < envInt("SEISIN_LOG_MAX_BYTES", DEFAULT_MAX_BYTES)) return;
+
+  const tail = hashOf(lastLine(file));
+  const archives = logSegments(file).filter((p) => p !== file);
+  const seqs = archives.map((p) => Number(p.slice((file + ".").length))).filter(Number.isInteger);
+  const next = (seqs.length ? Math.max(...seqs) : 0) + 1;
+  renameSync(file, `${file}.${next}`);
+  // Seed the new current so the first real append chains from the retired tail.
+  const marker = JSON.stringify({ at: new Date().toISOString(), event: "rotated", from: `${basename(file)}.${next}`, prev: tail });
+  appendFileSync(file, marker + "\n");
+
+  const keep = envInt("SEISIN_LOG_KEEP", DEFAULT_KEEP);
+  const retired = logSegments(file).filter((p) => p !== file); // oldest → newest, includes the new archive
+  for (let i = 0; i < retired.length - keep; i++) { try { unlinkSync(retired[i]); } catch {} }
+}
+
+/**
+ * The log is chained: every line carries `prev`, the hash of the line before it.
+ *
+ * The log is the record of who touched what and who was refused what, and it
+ * could be edited without a trace. A chain does not stop anyone with write
+ * access from rewriting it — nothing inside a file can — but it makes an edit,
+ * a deletion or a reordering show, and `seisin log verify` says where. Taken
+ * from nono's audit trail; the Merkle root and the signature it adds on top
+ * are left for when someone asks for them.
+ *
+ * The first chained line of a file points at GENESIS. A file started by
+ * rotation should point at the last line of the one before it; there is no
+ * rotation yet, and when there is, that is what it has to do.
+ */
+export const GENESIS = "0".repeat(32);
+
+export function hashOf(line) {
+  return line == null ? GENESIS : createHash("sha256").update(line).digest("hex").slice(0, 32);
+}
+
+/** The last complete line of the file, or null when there is none. */
+function lastLine(file) {
+  if (!existsSync(file)) return null;
+  const { size } = statSync(file);
+  if (size === 0) return null;
+  const from = Math.max(0, size - 64 * 1024);
+  const fd = openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(size - from);
+    readSync(fd, buf, 0, buf.length, from);
+    const lines = buf.toString("utf8").split("\n").filter((l) => l.trim());
+    return lines.length ? lines[lines.length - 1] : null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * One writer at a time. Several roles of a round run at once and write this
+ * same file; two of them reading the same last line would fork the chain.
+ * A lock left by a killed process is taken over after a few seconds.
+ */
+function withLock(file, fn) {
+  const lock = file + ".lock";
+  const deadline = Date.now() + 2000;
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx"));
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      try { if (Date.now() - statSync(lock).mtimeMs > 5000) { unlinkSync(lock); continue; } } catch {}
+      if (Date.now() > deadline) break;          // never block the run over bookkeeping
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+    }
+  }
+  try { return fn(); } finally { try { unlinkSync(lock); } catch {} }
+}
+
+/**
+ * Walk the file and say where the chain breaks.
+ *
+ * Lines written before the chain existed have no `prev`; they are counted as an
+ * unchained prefix, not reported as tampering. After the first chained line,
+ * a line without `prev` is itself a break.
+ */
+function walk(file, { seed = GENESIS, startLine = 0 } = {}) {
+  const out = { lines: 0, unchained: 0, chained: 0, breaks: [], tail: null };
+  if (!existsSync(file)) return out;
+  let previous = null;
+  let started = false;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    out.lines++;
+    let e = null;
+    try { e = JSON.parse(line); } catch {}
+    const prev = e?.prev;
+    if (!started && prev === undefined) { out.unchained++; previous = line; continue; }
+    started = true;
+    const first = out.chained === 0 && out.unchained === 0;
+    // A rotation marker leading a segment we have nothing to check it against —
+    // a file verified on its own, or the oldest segment left after the prefix
+    // was pruned for retention (seed still GENESIS) — is accepted rather than
+    // called a break. For any later segment the seed is the real previous tail,
+    // so the marker's `prev` IS checked, and a whole segment deleted or
+    // reordered in the middle shows.
+    const rotationStart = first && e?.event === "rotated" && seed === GENESIS;
+    const expected = first ? seed : hashOf(previous);
+    const ok = rotationStart || prev === expected || (first && prev === hashOf(previous));
+    if (!ok) out.breaks.push({ line: startLine + out.lines, expected, found: prev ?? null });
+    out.chained++;
+    previous = line;
+  }
+  out.tail = previous;
+  return out;
+}
+
+export function verifyChain(file, seed = GENESIS) {
+  const r = walk(file, { seed });
+  return { lines: r.lines, unchained: r.unchained, chained: r.chained, breaks: r.breaks };
+}
+
+/**
+ * Verify the whole log, across every rotated segment, as one chain.
+ *
+ * Each retired segment is walked in order, and its last hash becomes the seed
+ * the next segment's `rotated` marker must match — so deleting or reordering a
+ * whole segment shows, not only an edit inside one. With no rotation there is a
+ * single segment and this is exactly `verifyChain`. What it cannot see is a
+ * segment dropped off the *oldest* end by the keep limit: that is retention, not
+ * tampering, and the count of segments is reported so the drop is not silent.
+ */
+export function verifyLog(file) {
+  const segs = logSegments(file);
+  const agg = { lines: 0, unchained: 0, chained: 0, breaks: [], segments: segs.length };
+  let seed = GENESIS;
+  for (const seg of segs) {
+    const r = walk(seg, { seed, startLine: agg.lines });
+    agg.lines += r.lines;
+    agg.unchained += r.unchained;
+    agg.chained += r.chained;
+    agg.breaks.push(...r.breaks);
+    seed = hashOf(r.tail);
+  }
+  return agg;
+}
+
 /** Reads entries, newest last. A malformed line is skipped, never fatal. */
 export function read(file, { role, verdict, since, limit = 0 } = {}) {
   if (!existsSync(file)) return [];
@@ -56,6 +255,7 @@ export function read(file, { role, verdict, since, limit = 0 } = {}) {
     } catch {
       continue; // a half-written line from a killed process is not an error
     }
+    if (e.event === "rotated") continue; // a structural marker, not a decision
     if (role && e.role !== role) continue;
     if (verdict && e.verdict !== verdict) continue;
     if (since && e.at < since) continue;