seisin 0.1.0

package/src/inspect.js

@@ -0,0 +1,477 @@
+/**
+ * What `check` knows, without printing any of it.
+ *
+ * The warnings below used to live inside the command, interleaved with the
+ * writes that printed them, which made them unreachable from a test: the only
+ * way to assert that seisin notices a repo sitting inside shared scratch was to
+ * run the binary and grep its output. They are the most valuable thing `check`
+ * does — each one is a way the policy silently does not hold — so they belong
+ * where they can be exercised directly.
+ */
+import { resolve, dirname, basename, relative } from "node:path";
+import { realpathSync, lstatSync, readdirSync } from "node:fs";
+import { ownersOf } from "./owners.js";
+import { wired } from "./commands/wire.js";
+import { RUNTIME_WRITES, CREDENTIAL_HOMES, expand, settingsFor } from "./srt.js";
+
+/**
+ * A report on one config: the roles, and every way the map lies.
+ *
+ * `only` narrows to a single role, and an unknown name is an error rather than
+ * an empty report — asking about a role that does not exist is a typo, and
+ * answering it with silence is how a typo becomes a belief.
+ */
+export function inspect(config, only = null, where = config.path) {
+  if (only && !config.roles[only]) throw new Error(`unknown role "${only}"`);
+  const roles = only ? [config.roles[only]] : Object.values(config.roles);
+
+  return {
+    where,
+    roles: roles.map((r) => ({ name: r.name, writes: r.writes, keys: r.keys })),
+    shared: sharedPaths(config, roles),
+    warnings: warningsFor(config, roles),
+    limits: LIMITS,
+  };
+}
+
+/**
+ * What the tool cannot do at all — as opposed to `warnings`, which are things
+ * wrong with *this* config.
+ *
+ * Kept apart on purpose. A limit printed as a warning reads as something the
+ * operator could fix, and after the third run it reads as nothing at all.
+ *
+ * These are the sentences someone needs before they trust the map on screen
+ * more than it deserves, so `check` prints them every time rather than behind a
+ * flag: the moment to learn that deletes are not covered is while you are
+ * looking at the policy, not afterwards.
+ */
+const LIMITS = [
+  ...(process.platform === "darwin" ? [] : [{
+    kind: "kernel-denials-unreadable",
+    headline: "refusals by the kernel are not recorded on this platform",
+    detail:
+      "on macOS `seisin run` reads them out of the system log, so a denial the hook never " +
+      "saw still lands in `seisin log` with its owner and still queues a request. There is no " +
+      "equivalent to read here — bubblewrap does not log refusals, and the runtime's substitute " +
+      "is not reachable from outside it. The boundary holds exactly as well; what you lose is " +
+      "seeing it work. Run `seisin wire` so the hook records what it can. The ask is upstream: " +
+      "github.com/carlostapiaolguin3-stack/seisin/blob/main/docs/upstream/cli-violations.md",
+  }]),
+  {
+    kind: "keys-only-what-you-declared",
+    headline: "key isolation covers the directory you declared, and nothing else",
+    detail:
+      "a credential sitting in the repo outside [keys] dir is ordinary readable " +
+      "content to every role. Run `seisin scan` to find them — check does not, " +
+      "because reading the whole tree on every invocation is how a command stops " +
+      "being run.",
+  },
+  {
+    kind: "observe-cannot-see-the-network",
+    headline: "`--observe` opens the filesystem, never the network",
+    detail:
+      "so it cannot tell you which domains an agent needs. The runtime does record every " +
+      "refusal the proxy makes — host, port and reason — but only a caller that embeds the " +
+      "library can read them; nothing reaches a caller that runs the binary, which is what " +
+      "seisin does. So for an agent whose endpoints are not published, the options are to " +
+      "find them another way or drop the network restriction for it. The ask is upstream: " +
+      "github.com/carlostapiaolguin3-stack/seisin/blob/main/docs/upstream/cli-violations.md",
+  },
+  {
+    kind: "unlink-uncovered",
+    headline: "a role can delete inside its own territory",
+    detail:
+      // The path that used to be here ships with the repo and not with the npm
+      // package, so for most readers it named a file they do not have.
+      "writes and deletes are one permission to the kernel, so `rm` inside a " +
+      "role's own folders succeeds. Closing it needs denyUnlink in the sandbox " +
+      "runtime: github.com/carlostapiaolguin3-stack/seisin#how-it-holds",
+  },
+];
+
+/**
+ * Paths more than one role claims.
+ *
+ * Overlap is allowed and sometimes right — a hotfix role deliberately reaches
+ * into the territory of the role that normally owns a repo. It is reported so
+ * that it stays a decision somebody made rather than a thing that drifted.
+ */
+export function sharedPaths(config, roles = Object.values(config.roles)) {
+  const seen = new Set();
+  for (const r of roles)
+    for (const glob of r.writes)
+      if (ownersOf(config, glob.replace(/\/\*\*$/, "")).length > 1) seen.add(glob);
+  return [...seen];
+}
+
+/**
+ * What a role can still read in YOUR home, which is the limit people are most
+ * surprised by.
+ *
+ * `~/.ssh`, `~/.aws/credentials`, `~/.npmrc` and `~/.config/gh/hosts.yml` are
+ * ordinary readable files to every role unless `[runtime] isolate` says
+ * otherwise, and nothing on screen said so. Reads outside the key directories
+ * being open is a deliberate trade - an agent that cannot read the machine
+ * cannot work - but a trade nobody was shown is not a trade they made.
+ *
+ * It reports the level rather than pushing one. `credentials` closes those four
+ * and leaves the agent logged in; `home` closes the agent's own directories too
+ * and costs the session. Which of the two you want is the threat model, which
+ * is why there is no default beyond off.
+ */
+function homeReachWarning(config) {
+  const level = config.isolate === true ? "home" : config.isolate;
+  if (level === "home") return null;             // nothing left to say
+
+  const where = CREDENTIAL_HOMES.slice(0, 4).join(" ");
+  return level === "credentials"
+    ? {
+        kind: "home-partly-open",
+        headline: "your credentials are closed to every role; the agent's own directories are not",
+        detail:
+          `isolate = "credentials" denies ${where} and the rest. What stays open is ` +
+          "~/.claude and ~/.codex, which is what keeps the agent logged in, so the roles " +
+          'share one session and can read each other. `isolate = "home"` closes those ' +
+          "too, and then every CLI in the box will ask you to log in again.",
+      }
+    : {
+        kind: "home-open",
+        headline: `every role can read ${where} and the rest of your home`,
+        detail:
+          "reads outside the [keys] dir are open on purpose - an agent that cannot read the " +
+          "machine cannot work - but that includes the places credentials live. " +
+          '`[runtime] isolate = "credentials"` closes them, and the agent stays logged in.',
+      };
+}
+
+
+/** Every way this policy does not hold, each with what to do about it. */
+function warningsFor(config, roles) {
+  const warnings = [];
+
+  // A pattern the kernel cannot be given is not a policy, it is a sentence that
+  // reads like one. `run` refuses it; `check` exists precisely so you find that
+  // out while reading the map rather than mid-turn.
+  for (const r of roles) {
+    try {
+      settingsFor(config, r.name);
+    } catch (e) {
+      // Whatever settingsFor refuses, `run` will refuse too. The label used to
+      // say "unenforceable-glob" for every one of them, which mislabelled the
+      // key-outside-its-directory error as a glob problem — a warning that
+      // names the wrong cause sends the reader to the wrong line.
+      warnings.push({
+        kind: "cannot-be-enforced",
+        headline: `${r.name}: ${e.message.split("\n")[0]}`,
+        detail: e.message.split("\n").slice(1).map((s) => s.trim()).filter(Boolean).join(" "),
+      });
+    }
+  }
+  const shared = sharedPaths(config, roles);
+
+  if (shared.length)
+    warnings.push({
+      kind: "shared",
+      headline: `${shared.length} path(s) claimed by more than one role: ${shared.join(" ")}`,
+      detail: "Overlap is allowed — seisin will name every owner. It is listed so it stays a decision.",
+    });
+
+  // Scratch is granted to every role, so a repo sitting inside it is writable
+  // by all of them no matter what the territory says. Saying so is the
+  // difference between a limitation and a trap — and it is not hypothetical:
+  // the test fixture lived in the temp dir and made a boundary test pass for
+  // the wrong reason.
+  // Both sides resolved, or the comparison is a coin flip. `expand()` follows
+  // symlinks — it has to, because on macOS /tmp is a link to /private/tmp and a
+  // grant written as /tmp grants nothing — so the root has to be followed too.
+  // Without this a repo at /tmp/x is never reported as sitting in scratch,
+  // which is the one case where the warning matters most.
+  const scratch = (config.runtimeWrites ?? RUNTIME_WRITES).map(expand);
+  const root = realOrSelf(resolve(config.root));
+  const inside = scratch.filter((s) => root === s || root.startsWith(s + "/"));
+  if (inside.length)
+    warnings.push({
+      kind: "scratch",
+      headline: `this repo lives inside shared scratch space (${inside[0]})`,
+      detail: "Every role can write scratch, so territory does not hold here. Move the repo, or set [runtime] writes = [].",
+    });
+
+  /**
+   * A role that can write code and cannot reach any inference API.
+   *
+   * Reported three separate times, by three different people, with the same
+   * shape each time: a list of what agents need, written somewhere that does
+   * not know which agent will run. The last instance cost six bench runs that
+   * finished in eight seconds with `403 Connection blocked by network
+   * allowlist` — which in a results table reads as "this model cannot do the
+   * task", not as a policy error.
+   *
+   * What is deliberately NOT here: a registry of agents and their endpoints.
+   * That is the same defect in a new place, and the reporter said so before I
+   * could. The list below is only ever consulted to decide whether to print a
+   * sentence, so being wrong about it costs a false warning — never a broken
+   * run. That asymmetry is the whole reason it is allowed to exist, and the
+   * warning says out loud that the list is ours and may not know your agent.
+   */
+  const INFERENCE = /(anthropic|openai|googleapis|generativelanguage|bedrock|azure|openrouter|mistral|groq|together|deepseek|x\.ai|cohere|ollama|localhost|127\.0\.0\.1)/i;
+  for (const r of roles) {
+    const domains = r.network ?? config.allowedDomains ?? [];
+    if (domains.some((d) => INFERENCE.test(d))) continue;
+    warnings.push({
+      kind: "no-model-endpoint",
+      headline: domains.length
+        ? `${r.name} has ${domains.length} allowed domain(s) and none looks like a model API`
+        : `${r.name} may reach no network at all`,
+      detail:
+        "an agent that cannot reach its own model fails at startup with a 403 from the " +
+        "egress proxy, which reads as a broken install or a bad model rather than a policy. " +
+        "This check knows a handful of providers and will not know yours — it is a question, " +
+        "not a verdict.",
+    });
+  }
+
+  // Without the hook, half the record is missing rather than all of it: on macOS
+  // `seisin run` reads the kernel's own refusals, so denials still land and
+  // still queue a request. What goes unrecorded is everything the kernel
+  // allowed — which is the half `init --from-observations` is built out of, and
+  // the half that tells "nothing was denied" apart from "nobody was watching".
+  // The one limit that is about YOUR machine rather than about the repo.
+  const reach = homeReachWarning(config);
+  if (reach) warnings.push(reach);
+
+  if (!wired(config.root))
+    warnings.push({
+      kind: "hook-not-wired",
+      headline: "only denials are being recorded: the agent has not been told to run the hook",
+      detail:
+        process.platform === "darwin"
+          ? "the boundary holds either way, and refusals are still logged and still queue a " +
+            "request — `seisin run` reads them from the kernel. What is missing is every " +
+            "action that was allowed, so `review` cannot tell you which grants are dead and " +
+            "`init --from-observations` has nothing to build from. Run `seisin wire` once in " +
+            "this repo."
+          : "the boundary holds either way — but on this platform the kernel's refusals are " +
+            "not readable either, so log, watch, requests, grant and review all read a record " +
+            "that nobody is writing. Run `seisin wire` once in this repo.",
+    });
+
+  // A territory that leaves the repo is supported — a role can own its handover
+  // note one level up — but it is a different promise from "this repo, divided",
+  // and it should be a sentence somebody chose rather than a line that drifted.
+  const loose = [];      // roles granting individual files
+  const listed = [];     // role + folder pairs that enumerate
+
+  for (const r of roles) {
+    const out = r.writes.filter((w) => w.startsWith("/") || w.startsWith("../"));
+    if (out.length)
+      warnings.push({
+        kind: "territory-outside-repo",
+        headline: `${r.name} writes outside this repo: ${out.join(" ")}`,
+        detail: "the sandbox will grant it. Nothing here checks what lives there.",
+      });
+  }
+
+  /**
+   * A file granted by name does not come with its neighbours.
+   *
+   * Measured, in production, and it survived two human reviews of the policy:
+   * a role was granted its database file and still could not write the
+   * database. The database opens a second file beside the first — a journal —
+   * and the sibling was outside the grant, so the write failed in the
+   * database's own words ("readonly") rather than as a permission error.
+   *
+   * What is deliberately NOT here: a list of which programs write which
+   * siblings. That would ask seisin to know about databases, and the next
+   * question is why it does not know about a lock file, the temporary file of
+   * an atomic write, or an editor's backup. The list has no end and every entry
+   * is a guess about a repo nobody foresaw. The general form needs no list: the
+   * kernel grants a path and everything under it, so a grant on a file covers
+   * the file and nothing else. Whether a tool will want a neighbour is the
+   * reader's to know; that the neighbour is not granted is arithmetic.
+   */
+  for (const r of roles) {
+    const { files, subtrees } = territoryOf(config, r);
+    // A file inside one of the role's own subtrees has its siblings covered by
+    // that subtree, so naming it changes nothing and warns about nothing.
+    const alone = files.filter((f) => !subtrees.some((s) => under(dirname(f.abs), s)));
+    if (alone.length)
+      loose.push({ role: r.name, n: alone.length, of: r.writes.length, globs: alone.map((f) => f.glob) });
+
+
+    /**
+     * A territory written as a list of files is a photograph of the folder.
+     *
+     * A sandbox cannot say "the source files in this folder" — one level down
+     * is not a prefix, and `src/*` is refused above for exactly that reason,
+     * correctly. So a territory that means that has to be written as the files
+     * that exist today, and the day a file is added the policy is one behind:
+     * the owning role cannot write its own new file, and nothing fails loudly.
+     *
+     * Reported as a count, never as a verdict. "Comparable" here means only
+     * "a regular file in the same folder" — not the same extension, not the
+     * same shape of name, because either of those is a guess about what the
+     * territory *meant*, and a guess about intent is the thing this check
+     * exists to avoid. The unnamed files are listed by name instead, so the
+     * reader can see in one glance whether the gap is an oversight or a
+     * decision. seisin cannot tell, and does not pretend to.
+     *
+     * Silent when a folder has fewer than two named files (one file is a
+     * grant, not an enumeration) and when the folder is also granted as a
+     * subtree (then the list is decorative).
+     */
+    const byDir = new Map();
+    for (const f of alone) {
+      const dir = dirname(f.abs);
+      if (!byDir.has(dir)) byDir.set(dir, []);
+      byDir.get(dir).push(basename(f.abs));
+    }
+    for (const [dir, named] of byDir) {
+      if (named.length < 2) continue;
+      const onDisk = regularFilesIn(dir);
+      const unnamed = onDisk.filter((n) => !named.includes(n));
+      if (!unnamed.length) continue;
+      const shown = relative(resolve(config.root), dir);
+      const more = unnamed.length > 8 ? ` … and ${unnamed.length - 8} more` : "";
+      listed.push({ role: r.name, named: named.length, total: onDisk.length,
+                    where: shown ? shown + "/" : "the repo root", unnamed });
+
+    }
+  }
+
+  /**
+   * One warning per finding, not one per role.
+   *
+   * These were emitted inside the role loop, which reads fine on the two-role
+   * fixture they were written against and falls apart on a real policy: 30
+   * roles produced 39 of these lines and took `seisin check` from 30 lines to
+   * **297**. That is the defect the detail text below is about — a check nobody
+   * finishes reading protects nobody — reached from the other side.
+   *
+   * So the count leads and a few examples follow. Whoever wants the full list
+   * has `seisin check <role>`, which is the question they were asking anyway.
+   */
+  if (loose.length) {
+    const shown = loose.slice(0, 3).map((l) => `${l.role} (${l.n} of ${l.of})`).join(", ");
+    const more = loose.length > 3 ? `, and ${loose.length - 3} more` : "";
+    warnings.push({
+      kind: "siblings-uncovered",
+      headline:
+        `${loose.length} role(s) grant individual files rather than folders: ${shown}${more}`,
+      detail:
+        "the kernel grants exactly that path. Anything a tool creates beside it — a " +
+        "database's journal, a lock file, the temporary file of an atomic write — is a " +
+        "sibling, and a sibling is outside the grant; the failure arrives in the tool's " +
+        "own words, not as a permission error. Grant the folder where the tool needs " +
+        "neighbours. `seisin check <role>` names the paths for one role.",
+    });
+  }
+
+  if (listed.length) {
+    const shown = listed.slice(0, 3)
+      .map((l) => `${l.role} names ${l.named} of ${l.total} in ${l.where}`).join("; ");
+    const more = listed.length > 3 ? `; and ${listed.length - 3} more` : "";
+    warnings.push({
+      kind: "enumerated-territory",
+      headline: `${listed.length} territory(ies) list some files of a folder: ${shown}${more}`,
+      detail:
+        `not named, in the first of them: ${listed[0].unnamed.slice(0, 8).join(" ")}` +
+        `${listed[0].unnamed.length > 8 ? ` … and ${listed[0].unnamed.length - 8} more` : ""}` +
+        `. A sandbox grants a path, ` +
+        `not "the files of this kind here", so a territory that means that is the list of files ` +
+        `that existed when it was written — the next one added lands outside it, and nothing ` +
+        `fails loudly. Whether these are left out on purpose is not something a count can tell.`,
+    });
+  }
+
+  // `env` is a hole in the [keys] model, on purpose: some tools only take a
+  // credential through the environment. It should still be loud, because it is
+  // the one place a secret reaches a role without being a declared key.
+  const SECRETISH = /(TOKEN|KEY|SECRET|PASSWORD|PASSWD|AUTH|COOKIE|SESSION|PRIVATE|CREDENTIAL)/i;
+  for (const r of roles) {
+    const risky = (r.env ?? []).filter((n) => SECRETISH.test(n));
+    if (risky.length)
+      warnings.push({
+        kind: "secret-through-env",
+        headline: `${r.name} receives ${risky.join(", ")} through the environment`,
+        detail:
+          "that bypasses [keys] entirely: it is not scoped, not redacted by name, and not " +
+          "visible in the key map. Declare it as a key file where the tool allows one.",
+      });
+  }
+
+  if (config.keyDirs.length === 0 && Object.values(config.roles).some((r) => r.keys.length))
+    warnings.push({
+      kind: "keys-unscoped",
+      headline: "keys are listed but [keys] dir is unset — nothing will be scoped",
+      detail: null,
+    });
+
+  return warnings;
+}
+
+/**
+ * A role's territory, sorted by what the kernel will do with each line.
+ *
+ * Three shapes get through `settingsFor` (see EXPRESSIBLE in srt.js): the whole
+ * repo, a subtree `x/**`, and a literal path. The literal path is the one the
+ * text cannot settle on its own — `data/base.sqlite` and `data` are both
+ * literal, and to the kernel the second is a subtree because it is a directory.
+ * So the disk is asked, once per line: a regular file is a file, a directory is
+ * a subtree, and anything else — absent, a symlink, a socket — goes in neither
+ * count rather than being guessed at. That is one `lstat` per declared path,
+ * bounded by the length of the policy and not the size of the repo, which is
+ * the line `check` stays on.
+ *
+ * Subtrees come back as the absolute prefix the kernel will be handed, so that
+ * "is this file's folder inside that grant" is the same comparison the kernel
+ * makes — a prefix — and not a second reading of the glob.
+ */
+function territoryOf(config, role) {
+  const root = resolve(config.root);
+  const abs = (p) => resolve(root, p);
+  const files = [];
+  const subtrees = [];
+  for (const glob of role.writes) {
+    if (glob === "**" || glob.endsWith("/**")) {
+      subtrees.push(abs(glob === "**" ? "." : glob.slice(0, -3)));
+      continue;
+    }
+    if (/[*?[\]]/.test(glob)) continue;      // already refused above as cannot-be-enforced
+    const s = lstatOrNull(abs(glob));
+    if (s?.isFile()) files.push({ glob, abs: abs(glob) });
+    else if (s?.isDirectory()) subtrees.push(abs(glob));
+  }
+  return { files, subtrees };
+}
+
+/** Is `p` the prefix, or somewhere beneath it. The kernel's own test, in one line. */
+function under(p, prefix) {
+  return p === prefix || p.startsWith(prefix + "/");
+}
+
+/** The regular files directly inside `dir`, by name. Not folders, not links, not deeper. */
+function regularFilesIn(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+function lstatOrNull(p) {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/** The path with symlinks followed, or the path itself if it is not on disk. */
+function realOrSelf(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}

package/src/layout.js

@@ -0,0 +1,47 @@
+/**
+ * Where seisin's own files live. Names only — no logic, no imports.
+ *
+ * These were spread across the modules that happened to create each file, and
+ * that produced one dependency that points the wrong way: `srt.js`, whose job
+ * is translating a policy into a sandbox, imported `log.js` purely to learn the
+ * name of the state directory it has to keep writable. A module that decides
+ * what the kernel may allow should not know that logging exists.
+ *
+ * A leaf with no imports is the cheapest place to put a shared name, and it
+ * keeps the graph honest: everything here is depended upon, nothing here
+ * depends on anything.
+ */
+
+/** The policy file, looked up from the working directory upward. */
+export const CONFIG_NAME = "seisin.toml";
+
+/** Everything seisin writes goes under this, at the policy file's directory. */
+export const STATE_DIR = ".seisin";
+
+/** The append-only record of every decision, inside STATE_DIR. */
+export const LOG_NAME = "log.jsonl";
+
+/**
+ * A value, written as a TOML string — or refused.
+ *
+ * The subset has no escapes, so a quote or a newline cannot be represented at
+ * all. Every place that emits config went its own way about this: applyGrant
+ * checked, init did not, and renderObserved built lines out of log targets,
+ * which is text an agent chose. One rule, in one place, so the next emitter
+ * inherits it instead of rediscovering it.
+ */
+export function tomlString(s) {
+  const v = String(s);
+  if (/["\r\n]/.test(v))
+    throw new Error(
+      `cannot write ${JSON.stringify(v)} into ${CONFIG_NAME}: the format has no way to ` +
+      `represent a quote or a newline inside a value.`);
+  return `"${v}"`;
+}
+
+/** A role name, written as a table header — or refused. */
+export function tomlName(s) {
+  if (!/^[A-Za-z0-9_-]+$/.test(String(s)))
+    throw new Error(`cannot write role name ${JSON.stringify(s)}: letters, digits, _ and - only.`);
+  return String(s);
+}

package/src/log.js

@@ -0,0 +1,124 @@
+/**
+ * One append-only JSONL file, and that is the whole storage design.
+ *
+ * `seisin log`, `seisin watch` and the console all read this file. There is no
+ * daemon and no database, because the moment there is one, seisin stops being a
+ * launcher you can reason about and becomes a service you have to operate. A
+ * file that only grows is the version of "live" that survives a crash, a reboot
+ * and being read by three things at once.
+ *
+ * Append-only also means the log is evidence. Nothing here rewrites a line, so
+ * what an agent tried last night reads the same today — and since the change in
+ * spool.js, nothing inside the sandbox can rewrite one either. append() below
+ * 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 { STATE_DIR, LOG_NAME } from "./layout.js";
+import { send } from "./spool.js";
+
+export { STATE_DIR, LOG_NAME } from "./layout.js";
+
+export function logPath(root) {
+  return join(root, STATE_DIR, LOG_NAME);
+}
+
+/**
+ * Appends one decision.
+ *
+ * Failing to write must never take the agent down with it: a permission tool
+ * that breaks the build because its disk is full has done more damage than the
+ * thing it was watching for. Errors are swallowed on purpose, and the caller
+ * gets `false` if it cares.
+ */
+export function append(file, entry) {
+  // Confined: the parent owns the file, we only get to send a line. See spool.js.
+  if (send("log", entry)) return true;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...entry }) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Reads entries, newest last. A malformed line is skipped, never fatal. */
+export function read(file, { role, verdict, since, limit = 0 } = {}) {
+  if (!existsSync(file)) return [];
+  let out = [];
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue; // a half-written line from a killed process is not an error
+    }
+    if (role && e.role !== role) continue;
+    if (verdict && e.verdict !== verdict) continue;
+    if (since && e.at < since) continue;
+    out.push(e);
+  }
+  if (limit > 0 && out.length > limit) out = out.slice(-limit);
+  return out;
+}
+
+/** Byte offset of the end of the file, for `watch` to start from. */
+export function size(file) {
+  try {
+    return statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * What each role actually reached for, from the log.
+ *
+ * This is the reason the log exists. A policy written by hand on day one is a
+ * guess, and the first unjustified `denied` is when a tool gets uninstalled.
+ * Observed first, written second.
+ */
+export function observed(entries) {
+  const roles = new Map();
+  for (const e of entries) {
+    if (!e.role || !e.target) continue;
+    const r = roles.get(e.role) ?? { writes: new Set(), keys: new Set() };
+    if (e.action === "read" && e.kind === "key") r.keys.add(e.target);
+    else if (e.action === "write") r.writes.add(e.target);
+    roles.set(e.role, r);
+  }
+  return roles;
+}
+
+/**
+ * Collapses observed file paths into directory globs.
+ *
+ * A policy listing 400 individual files is not a policy, it is a transcript.
+ * The common parent of everything a role wrote is the honest generalisation,
+ * and it is deliberately shallow: one level below the shared root, so that a
+ * role that touched `src/api/a` and `src/api/b` gets `src/api/**` rather than
+ * `src/**`, which would hand it the whole tree on the strength of two files.
+ */
+export function generalise(paths) {
+  const dirs = new Set();
+  const files = new Set();          // things at the repo root have no directory
+
+  for (const p of paths) {
+    const parts = p.split("/").filter(Boolean);
+    parts.pop();                    // drop the file itself
+    // A path with nothing above it is a file at the root. It used to be added
+    // to `dirs` and then given a `/**` like everything else, so observing a
+    // write to NOTAS.md proposed `NOTAS.md/**` — the children of a directory
+    // that does not exist, which grants nothing over the file that was written.
+    if (parts.length === 0) files.add(p);
+    else dirs.add(parts.join("/"));
+  }
+
+  const kept = [...dirs].filter((d) => ![...dirs].some((o) => o !== d && d.startsWith(o + "/")));
+  // A root file already covered by a directory grant does not need naming.
+  const loose = [...files].filter((f) => ![...kept].some((d) => f.startsWith(d + "/")));
+  return [...kept.map((d) => d + "/**"), ...loose].sort();
+}