seisin 0.4.2 → 0.6.0

package/src/territory.js

@@ -0,0 +1,261 @@
+/**
+ * `[runtime] read = "territory"`: reading denied where people keep their data,
+ * re-opened only along the paths a role needs.
+ *
+ * The default read model is a list of what not to read — key directories, the
+ * places credentials live, other agents' sign-in. It holds for agents you run
+ * yourself. Against one you would not trust it loses by one every time a new
+ * product leaves a folder of its own: measured on 2026-10-06 by an orchestrator that evaluates agents,
+ * a role confined that way could still list `~/.claude`, list the whole
+ * project tree of the person running it, and `cat` an evaluation check kept
+ * outside its worktree. None of the three was a credential, so none was on
+ * the list.
+ *
+ * So this mode turns the list around, but not all the way. Denying `/` and
+ * allowing back is the read allowlist decisions.md rejected, for a reason that
+ * still holds: every interpreter, library and cache a toolchain touches would
+ * have to be named. The data roots are what gets denied — homes, temp
+ * directories, mounted volumes — and the system stays readable, because there
+ * is nobody's data in `/usr`. What a role needs from inside a data root is
+ * finite and known before it starts: its repo, its territory, its run, its
+ * toolchain. That list is the short one, and it is the one written.
+ *
+ * **Denied whole, allowed back.** Each data root is one deny, and what the
+ * role keeps is an `allowRead` inside it. A deny covers what is created after
+ * it, so another run's directory made beside the repo an hour into this one
+ * is shut the moment it exists. That is the point of it.
+ *
+ * It was carved before — every sibling on the way to a kept path denied by
+ * name, which is a photograph: an entry created during the run beside a kept
+ * path was not covered, and read (measured, 2026-10-12). Two measured runtime
+ * behaviours kept the allow out then, and each is now handled where it bites:
+ *
+ *   - macOS: an allow is emitted after the denies, and a deny that sits inside
+ *     an allow is re-emitted after it whole (last match wins). For the key
+ *     directory inside the repo that re-emitted deny also shuts the key files
+ *     `[keys]` re-allows inside it. A deny spelt as a pattern is re-emitted
+ *     MINUS the allows inside it, so those denies are spelt as one
+ *     (outlastAllows, below).
+ *   - Linux: the runtime restores the write mounts a deny wiped and then the
+ *     read allows, read-only, on top of them — so a repo allowed back covers
+ *     the territory inside it and every write fails with "Read-only file
+ *     system" (srt 0.0.75/0.0.78). A kept path that holds a write path is
+ *     allowed back piece by piece around it (territoryReads, below).
+ *
+ * **What that costs, said where it is decided.** On Linux, inside a kept
+ * directory that is on the way to a write path, an entry created during the
+ * run is not there for the role until the next run: it fails closed, it does
+ * not leak. On both, the names of what the role keeps are visible where the
+ * runtime has to show them (a Linux `ls ~` lists the mount points), and
+ * nothing else in a data root is.
+ */
+import { readdirSync, lstatSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { realOrSelf, writePathsOf, expand } from "./grants.js";
+import { realAncestor } from "./paths.js";
+
+export const READ_MODES = ["all", "territory"];
+
+/** Files an agent reads at start that live outside its home directory. */
+export const AGENT_FILES = { claude: ["~/.claude.json"], codex: [] };
+
+/**
+ * Where data lives, per platform. Whole roots: what is under them belongs to
+ * somebody. `/opt/homebrew/var` and `/usr/local/var` hold the databases a
+ * package manager runs (Postgres, Redis); the rest of `/opt/homebrew` is the
+ * toolchain and stays readable.
+ */
+export const DATA_ROOTS = {
+  darwin: [
+    "/Users", "/private/tmp", "/private/var/folders", "/private/var/root", "/Volumes",
+    "/opt/homebrew/var", "/usr/local/var", "/Library/Keychains",
+  ],
+  linux: [
+    "/home", "/root", "/tmp", "/var/tmp", "/mnt", "/media", "/srv", "/run/user",
+    "/run/secrets", "/var/lib/docker",
+  ],
+};
+
+/** The data roots of this machine: the platform's, plus HOME and TMPDIR wherever they are. */
+export function dataRoots(platform = process.platform, home = homedir(), tmp = tmpdir(), real = realOrSelf) {
+  const base = DATA_ROOTS[platform] ?? DATA_ROOTS.linux;
+  return [...new Set([...base, home, tmp].map(real))];
+}
+
+/**
+ * The most entries one directory may have where a kept path is allowed back
+ * piece by piece (Linux, around a write path).
+ *
+ * Every piece is one allow, and one mount. The carving this replaced hit the
+ * same wall from the other side: a repo kept inside a Mac's TMPDIR, 9,105
+ * entries, made 9,163 denies, 815 KB of profile, and `spawn E2BIG` — no
+ * agent, and no reason anyone could read. Past this the answer is a refusal
+ * that names the directory, not a sandbox that cannot start.
+ */
+export const MAX_CARVE = 1000;
+
+/** What the runtime treats as glob syntax in a path (sandbox-utils containsGlobChars). */
+const GLOB = /[[\]*?]/;
+
+const under = (p, dir) => p === dir || p.startsWith(dir === "/" ? "/" : dir + "/");
+const inside = (p, dir) => p !== dir && under(p, dir);
+
+/**
+ * The read rules that leave exactly `keep` readable inside `roots`:
+ * `{ deny, allow }`, for denyRead and allowRead.
+ *
+ * Each root is denied whole, unless something kept covers it. Each kept path
+ * under a root is allowed back, in both spellings. On Linux a kept path that
+ * holds one of `writes` is not allowed back itself — its read mount would
+ * land on the write mount inside it — but walked toward the writes, and every
+ * child not on the way is allowed instead; the writes come back writable
+ * through the runtime's own restore. Nothing is denied by name, so nothing
+ * created later escapes the deny.
+ *
+ * Nothing at or under `denied` — the key directories, other roles' private
+ * folders, the credential homes — is allowed back: an allow there would win
+ * over the deny on macOS, and on Linux the deny's own mount restores it.
+ *
+ * `fs` is injectable for tests; it needs `readdir(dir) -> names`,
+ * `kind(path) -> "dir" | "link" | "other" | null` and `real(path) -> path`.
+ */
+export function territoryReads(roots, keep, { writes = [], denied = [], platform = process.platform, fs = realFs } = {}) {
+  // realAncestor, not realOrSelf: a territory not created yet still has to
+  // be spelt the way the kernel will meet it (`/tmp/x` is `/private/tmp/x`).
+  // Both spellings of each: where it resolves, and where its NAME lives (the
+  // directories above resolved, the last component as written). A kept
+  // symlink — `~/.local/bin/claude` — has to be reachable by name for a PATH
+  // lookup to find it, and by target for the read to land.
+  const nameOf = (k) => { const d = k.slice(0, k.lastIndexOf("/")) || "/"; const r = fs.real(d); return `${r === "/" ? "" : r}/${k.slice(k.lastIndexOf("/") + 1)}`; };
+  const no = [...new Set(denied.map(fs.real))];
+  const open = (p) => !no.some((d) => under(p, d));
+  const kept = [...new Set(keep.flatMap((k) => [fs.real(k), nameOf(k)]))].filter(open);
+  // Nested roots (`/private/var/folders/…/T` inside `/private/var/folders`)
+  // are covered by the outer deny; one kept whole needs no deny at all.
+  const real = [...new Set(roots.map(fs.real))].filter((r) => fs.kind(r) === "dir");
+  const deny = real.filter((r) => !real.some((o) => inside(r, o)) && !kept.some((k) => under(r, k)));
+  const shut = kept.filter((k) => deny.some((r) => inside(k, r)));
+  if (platform !== "linux") return { deny, allow: shut };
+
+  const w = [...new Set(writes.map(fs.real))];
+  const allow = [];
+  const walk = (dir) => {
+    let names;
+    try { names = fs.readdir(dir); } catch { return; }      // unreadable: nothing comes back
+    if (names.length > MAX_CARVE)
+      throw new Error(
+        `read = "territory" cannot keep ${dir} readable around what the role writes inside it: it holds ` +
+        `${names.length} entries, and on Linux each is one mount (the most it takes is ${MAX_CARVE} per directory).\n` +
+        `  Written inside it: ${w.filter((x) => inside(x, dir)).join(", ")}.\n` +
+        `  Move the repo to a directory with fewer neighbours, or narrow the reads entry that keeps this path.`);
+    for (const name of names.sort()) {
+      const child = dir === "/" ? `/${name}` : `${dir}/${name}`;
+      if (w.some((x) => under(child, x)) || !open(child)) continue;   // a write, or denied
+      if (fs.kind(child) === "dir" && w.some((x) => inside(x, child))) walk(child);
+      else allow.push(child);
+    }
+  };
+  for (const k of shut) {
+    if (w.some((x) => under(k, x))) continue;                // comes back as a write
+    if (w.some((x) => inside(x, k)) && fs.kind(k) === "dir") walk(k);
+    else allow.push(k);
+  }
+  return { deny, allow };
+}
+
+/**
+ * The denies, respelt so that each keeps its own allows open on macOS.
+ *
+ * A deny strictly inside an allow is re-emitted after the allows, because the
+ * last rule that matches wins and the allow would otherwise re-open it. A
+ * deny written as a path comes back whole, and that shuts every allow inside
+ * IT — the key files inside the key directory inside the repo. A deny written
+ * as a pattern comes back minus each allow its pattern covers (srt 0.0.78,
+ * macos-sandbox-utils lateReadDenyFilters). So those denies, and only those,
+ * are spelt as a pattern that matches exactly their own path: one character
+ * of the last name in brackets, `.secrets` as `.secret[s]`.
+ *
+ * A path that already holds glob syntax cannot be spelt that way without
+ * matching something else, and is refused.
+ */
+export function outlastAllows(denies, allows, real = (p) => p) {
+  const open = allows.map(real);
+  return denies.map((written) => {
+    const d = real(written);
+    if (!open.some((a) => inside(a, d)) || !open.some((a) => inside(d, a))) return written;
+    const slash = d.lastIndexOf("/");
+    let at = d.length - 1;
+    while (at > slash && !/[A-Za-z0-9_-]/.test(d[at])) at--;
+    if (GLOB.test(d) || at <= slash)
+      throw new Error(
+        `read = "territory" cannot keep ${d} shut around what is allowed inside it: its name holds ` +
+        `characters the sandbox reads as a pattern, or none it can bracket.\n  Rename it.`);
+    return `${d.slice(0, at)}[${d[at]}]${d.slice(at + 1)}`;
+  });
+}
+
+const realFs = {
+  real: realAncestor,
+  readdir: (d) => readdirSync(d),
+  kind: (p) => {
+    try {
+      const s = lstatSync(p);
+      return s.isSymbolicLink() ? "link" : s.isDirectory() ? "dir" : "other";
+    } catch { return null; }
+  },
+};
+
+/**
+ * What a role keeps readable: its repo, what it writes, its `reads` and its
+ * `toolchain`. One answer for the settings and for `check`, so the warning
+ * about an unreadable PATH entry and the kernel agree.
+ */
+export function keptFor(config, role, { observe = false, agent, program } = {}) {
+  return [
+    config.root,
+    // The program the run starts, and where its link points: without it there
+    // is no run. Measured: `claude` installs as ~/.local/bin/claude ->
+    // ~/.local/share/claude/versions/<v>, and the run died on `env: claude: No
+    // such file or directory`. The file, not its directory — the rest of
+    // ~/.local/bin stays shut.
+    ...(program ? [program, realOrSelf(program)] : []),
+    // The agent's own files that are not under its home directory. Its home
+    // (~/.claude) is scratch and kept with the writes; ~/.claude.json, its
+    // settings and session index, sits beside it, and without it Claude Code
+    // starts and says "Not logged in" (measured, 2026-10-09). A run of no
+    // agent, or of another, does not get it.
+    ...(agent ? (AGENT_FILES[agent] ?? []).map(expand) : []),
+    ...writePathsOf(config, role, { observe, agent }),
+    ...(role.reads ?? []).map((p) => readPath(config.root, p)),
+    ...(role.toolchain ?? []).map((p) => readPath(config.root, p)),
+  ];
+}
+
+/** Whether `p` is shut by the mode: under a data root, and under nothing kept. */
+export function shutByTerritory(p, keep, roots = dataRoots(), real = realAncestor) {
+  const r = real(p);
+  const kept = keep.map(real);
+  if (!roots.some((root) => under(r, root))) return false;
+  return !kept.some((k) => under(r, k));
+}
+
+/**
+ * The `bin` directory of each toolchain entry that has one, for the front of
+ * PATH. A venv, `~/.cargo`, a node install all keep their programs there;
+ * declaring the toolchain and then finding `python` resolves to another one
+ * would be a second way of not having it.
+ */
+export function toolchainBins(config, role, isDir) {
+  return (role.toolchain ?? []).map((p) => readPath(config.root, p))
+    .flatMap((p) => [p.endsWith("/bin") ? p : `${p}/bin`].filter(isDir));
+}
+
+/** `~` and relative spellings of a read entry, absolute. Missing paths are kept as written. */
+export function readPath(root, p) {
+  const trimmed = p.replace(/\/\*\*$/, "") || ".";
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/")) return `${homedir()}/${trimmed.slice(2)}`;
+  if (trimmed.startsWith("/")) return trimmed;
+  return `${root}/${trimmed}`.replace(/\/\.$/, "");
+}
+

package/src/trace.js

@@ -0,0 +1,33 @@
+/**
+ * The launcher's trace, carried into the log.
+ *
+ * A launcher that runs many agents (a team, a CI job) gives each run a W3C
+ * `TRACEPARENT`. Without it in the log, nothing says which of these lines belong
+ * to which of the launcher's runs, and the log cannot be joined with anything
+ * else that observed the same run (a tracer, the launcher's own spans). With it,
+ * any OpenTelemetry tool joins them by trace id; seisin does not need to know
+ * who else is looking.
+ *
+ * Only a well-formed value is used (W3C Trace Context, version 00): a malformed
+ * one is ignored rather than copied into a log that other tools will trust.
+ */
+
+const PART = { version: /^[0-9a-f]{2}$/, trace: /^[0-9a-f]{32}$/, span: /^[0-9a-f]{16}$/, flags: /^[0-9a-f]{2}$/ };
+
+/** `{ trace_id, span_id }` from a `TRACEPARENT` value, or null. */
+export function parseTraceparent(value) {
+  if (typeof value !== "string") return null;
+  const parts = value.trim().split("-");
+  if (parts.length < 4) return null;
+  const [version, trace, span, flags] = parts;
+  if (!PART.version.test(version) || version === "ff") return null;
+  if (version === "00" && parts.length !== 4) return null;
+  if (!PART.trace.test(trace) || !PART.span.test(span) || !PART.flags.test(flags)) return null;
+  if (/^0+$/.test(trace) || /^0+$/.test(span)) return null;
+  return { trace_id: trace, span_id: span };
+}
+
+/** The fields a log entry carries for the launcher's trace: `{}` when there is none. */
+export function traceFields(env = process.env) {
+  return parseTraceparent(env.TRACEPARENT) ?? {};
+}

package/src/uilink.js

@@ -18,17 +18,35 @@
  * The pid is stored so a file left by a crashed run is recognisable: a link
  * whose writer is gone is stale, not a running console.
  */
-import { writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { chmodSync, renameSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { runsRoot } from "./rundir.js";
+import { alive as processAlive } from "./log.js";
 
 function linkFile(port, base) {
   return join(runsRoot(base), `ui-${port}.url`);
 }
 
-/** Records this run's live URL for the port it bound. */
-export function writeUiLink(port, url, base) {
-  writeFileSync(linkFile(port, base), JSON.stringify({ url, pid: process.pid }) + "\n", { mode: 0o600 });
+/**
+ * Records this run's live URL for the port it bound, and the policy it serves.
+ *
+ * The record is per port, not per repo, so `ui --link` in one repo found the
+ * console another repo had started — and opened a page about the wrong policy
+ * with nothing on it to say so. The policy's path travels with the link now.
+ */
+export function writeUiLink(port, url, base, policy = null) {
+  const file = linkFile(port, base);
+  const temp = `${file}.tmp-${randomBytes(12).toString("hex")}`;
+  writeFileSync(temp, JSON.stringify({ url, pid: process.pid, policy }) + "\n", { flag: "wx", mode: 0o600 });
+  try {
+    // Replacing an existing record must neither inherit its mode nor follow
+    // its symlink. Readers see one complete record, including after a crash.
+    chmodSync(temp, 0o600);
+    renameSync(temp, file);
+  } finally {
+    try { unlinkSync(temp); } catch {}
+  }
 }
 
 /**
@@ -42,11 +60,8 @@ export function readUiLink(port, base) {
   try { e = JSON.parse(raw); } catch { return null; }
   if (!e || typeof e.url !== "string") return null;
   let alive = null;
-  if (typeof e.pid === "number") {
-    // Signal 0 tests for the process without touching it: it throws if gone.
-    try { process.kill(e.pid, 0); alive = true; } catch { alive = false; }
-  }
-  return { url: e.url, pid: e.pid ?? null, alive };
+  if (Number.isInteger(e.pid) && e.pid > 0) alive = processAlive(e.pid);
+  return { url: e.url, pid: e.pid ?? null, alive, policy: typeof e.policy === "string" ? e.policy : null };
 }
 
 /** Removes the record. Called on exit, and when a stale one is found. */

package/src/views.js

@@ -0,0 +1,315 @@
+/**
+ * What the console and the MCP server both say about the log, computed once.
+ *
+ * The two readers are different — a person opens the console, an agent calls
+ * the MCP — and they must not disagree about the same file. This held the
+ * shared arithmetic inside serve.js, so the MCP server imported node:http to
+ * group denials. Nothing here opens a socket or writes a file.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { explain, standingOf } from "./owners.js";
+import { kindsOf, KINDS, expectedOf } from "./kinds.js";
+import { walls } from "./walls.js";
+import { queueOf } from "./requests.js";
+
+/**
+ * An ISO date from what a person or an agent typed, or null for no filter.
+ *
+ * A date (`2026-10-01`, any ISO time) or a duration back from `now`: `7d`,
+ * `12h`, `2w`, `30m` (minutes — a month is not a fixed length). Anything that
+ * does not parse is null; the MCP ignores it rather than refusing (a bad filter
+ * should show everything, not an error), and the CLI says so instead.
+ */
+const UNIT_MS = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 7 * 86_400_000 };
+export function parseSince(raw, now = Date.now()) {
+  const d = /^\s*(\d+)\s*([mhdw])\s*$/i.exec(String(raw ?? ""));
+  if (d) return new Date(now - Number(d[1]) * UNIT_MS[d[2].toLowerCase()]).toISOString();
+  const t = raw ? Date.parse(raw) : NaN;
+  return Number.isNaN(t) ? null : new Date(t).toISOString();
+}
+
+/**
+ * `explain`, remembered while the policy file stays the same.
+ *
+ * Causes and walls ask the policy about every refused path, and a real log has
+ * two thousand of them: ~0.75 ms each, most of the console's two-second poll.
+ * The answer depends on the policy text, so that is the key — and a little on
+ * the disk (on Linux a control file is protected only once it exists), so the
+ * memory is dropped after a minute too, as standingOf does. A config that was
+ * not read from a file gets a memory for this call only.
+ */
+const VERDICT_TTL = 60_000;
+let verdictMemo = { key: null, at: 0, map: new Map() };
+
+export function verdicts(cfg, { now = Date.now() } = {}) {
+  let key = null;
+  try {
+    if (cfg.path) key = `${cfg.path}\u0000${createHash("sha256").update(readFileSync(cfg.path)).digest("hex")}`;
+  } catch {}
+  let map;
+  if (key === null) map = new Map();
+  else {
+    if (verdictMemo.key !== key || now - verdictMemo.at > VERDICT_TTL) verdictMemo = { key, at: now, map: new Map() };
+    map = verdictMemo.map;
+  }
+  return (c, role, action, target) => {
+    const k = `${role}\u0000${action}\u0000${target}`;
+    let v = map.get(k);
+    if (!v) map.set(k, (v = explain(c, role, action, target)));
+    return v;
+  };
+}
+
+/**
+ * Today's denials, grouped by what was denied rather than by who asked.
+ *
+ * Called `causes` and not `friction`: `seisin review` already has a `friction`
+ * that counts something narrower — repeated denials that are not about keys —
+ * and two screens of one product reporting different numbers under one label
+ * is the kind of thing nobody notices until they are compared.
+ *
+ * The console used to show them per role, which is the same list a hundred
+ * times over: measured on one deployment, 1,080 of 1,422 refusals were a
+ * single lock file across six repositories, and per-role that reads as six
+ * hundred identical rows instead of one sentence. Grouped, the shape of the
+ * day is visible at a glance and it is almost never a territory dispute.
+ *
+ * `stillDenied` is recomputed against the policy as it stands, not read out
+ * of the log — a cause that has been granted since is history, not friction,
+ * and leaving it on the page sends somebody to fix what is already fixed.
+ */
+export function causesOf(cfg, entries, { ask = explain, limit = 12 } = {}) {
+  const by = new Map();
+  for (const e of entries) {
+    if (e.verdict !== "denied" || !e.target || !e.action) continue;
+    // A probe the caller of the run asked to be denied (`--expect-denied`):
+    // in the log, and not a cause of anything.
+    if (e.expected === true) continue;
+    const k = `${e.action}\u0000${e.target}`;
+    const g = by.get(k) ?? { action: e.action, target: e.target, kind: e.kind, times: 0, roles: new Set(), ownersThen: e.owners ?? [] };
+    g.times++;
+    g.roles.add(e.role);
+    by.set(k, g);
+  }
+  const total = [...by.values()].reduce((n, g) => n + g.times, 0);
+
+  /**
+   * The same grouping again, one level coarser: by the NAME at the end of the
+   * path rather than the path.
+   *
+   * Grouping by path alone gets the most important reading backwards. Measured
+   * here: six of the top seven causes were `.git/index.lock` in six different
+   * repositories, no single one above 17% — so "no cause dominates" is what the
+   * arithmetic says and the opposite of what is true. Three quarters of the
+   * window was one *kind* of thing, and that is a tooling problem with a
+   * mechanical fix, not a territory question anybody needs to rule on.
+   *
+   * By last segment, and nothing cleverer. A regex that recognised lock files,
+   * caches and build outputs would be a list of guesses about other people's
+   * toolchains that quietly goes stale; a repeated filename is a fact about
+   * this log.
+   */
+  const fams = new Map();
+  for (const g of by.values()) {
+    const name = g.target.split("/").filter(Boolean).pop() ?? g.target;
+    const f = fams.get(name) ?? { name, times: 0, paths: 0, where: [], roles: new Set() };
+    f.times += g.times;
+    f.paths++;
+    // The places, so the console can show what a name is made of instead of
+    // asserting a percentage the reader has to take on faith.
+    f.where.push({ target: g.target, times: g.times });
+    for (const r of g.roles) f.roles.add(r);
+    fams.set(name, f);
+  }
+  const families = [...fams.values()]
+    .sort((a, b) => b.times - a.times)
+    .map((f) => ({
+      name: f.name, times: f.times, paths: f.paths,
+      share: total ? f.times / total : 0,
+      roles: [...f.roles].sort(),
+      where: f.where.sort((a, b) => b.times - a.times).slice(0, 20),
+    }));
+
+  /**
+   * What a `grep` over the log cannot tell you: where each refused path stands
+   * against the policy as it is now.
+   *
+   * The headline used to be "74% of it is one name", and a field review
+   * applied this project's own test to it: *did the number tell you something
+   * you did not know?* For somebody who reads the raw log, no. So the console
+   * added how many causes are on paths no role owns — a decision rather than a
+   * number — and then computed it from the `owners` each log line carried,
+   * which is the one thing the log already had. It said the policy and read
+   * the past: every grant made since left its refusals counted as "nobody's",
+   * and protected surfaces, ports and paths outside the repository, which
+   * nobody can ever own, were counted as waiting for somebody to claim them.
+   *
+   * Now every cause is classified by `standing` (owners.js), and the four
+   * piles are reported in paths and in refusals. `unowned` keeps its name and
+   * now means what the page always said it meant. The owners the log recorded
+   * are kept on each cause as `ownersThen`: evidence of what was true, not
+   * authority over what is.
+   */
+  const standOf = standingOf(cfg);
+  const piles = Object.fromEntries(["unowned", "owned", "protected", "outside"].map((k) => [k, { paths: 0, denials: 0 }]));
+  for (const g of by.values()) {
+    const s = standOf({ kind: g.kind, target: g.target });
+    g.standing = s;
+    piles[s.kind].paths++;
+    piles[s.kind].denials += g.times;
+  }
+
+  /**
+   * And for the unowned pile, what kind of thing each path is (kinds.js).
+   *
+   * Suggesting an owner was measured first and was right about one time in
+   * twenty; the rest widened a role over git's lock files, a test's scratch
+   * directories and a credential. What the reader needs is the kind and the
+   * move that fits it, and `territory` — the part that really is a decision —
+   * is what is left. Over every unowned cause, not the twelve shown: one rule
+   * needs the whole set (the same name made unique per run in many places).
+   */
+  const unowned = [...by.values()].filter((g) => g.standing.kind === "unowned");
+  const natures = kindsOf(unowned.map((g) => g.target), { keyDirs: cfg.keyDirs ?? [] });
+  piles.unowned.kinds = Object.fromEntries(Object.keys(KINDS).map((k) => [k, { paths: 0, denials: 0 }]));
+  for (const g of unowned) {
+    g.nature = natures.get(g.target);
+    piles.unowned.kinds[g.nature.kind].paths++;
+    piles.unowned.kinds[g.nature.kind].denials += g.times;
+  }
+
+  /**
+   * What each refusal was about — a file, a key, a network destination or an
+   * MCP tool — counted over every cause, not the ones listed. The console
+   * shows keys, network and tools apart from files: "no role owns this" is a
+   * sentence about paths, and said of a port or a tool it is simply wrong.
+   */
+  /**
+   * Refusals that are expected (kinds.js expectedOf) — Claude Code's plugin
+   * updater — counted apart so the page can say them as the boundary working
+   * rather than leave them at the top of the list as something to grant.
+   */
+  const expected = { paths: 0, denials: 0 };
+  for (const g of by.values()) {
+    g.expected = expectedOf(g.target);
+    if (!g.expected) continue;
+    expected.paths++;
+    expected.denials += g.times;
+  }
+
+  const about = Object.fromEntries(ABOUT.map((k) => [k, { paths: 0, denials: 0 }]));
+  for (const g of by.values()) {
+    const a = aboutOf(g.kind);
+    about[a].paths++;
+    about[a].denials += g.times;
+  }
+
+  return {
+    total,
+    unowned: piles.unowned.paths,
+    about,
+    standing: piles,
+    expected,
+    // The real number of distinct causes, not the length of the list below.
+    // The page says "over N distinct paths" and the list is capped at twelve,
+    // so taking N from the list reported the cap as if it were the count —
+    // a wrong number stated confidently, which is worse than no number.
+    distinct: by.size,
+    families: families.slice(0, 8),
+    causes: [...by.values()]
+      .sort((a, b) => b.times - a.times)
+      .slice(0, limit)
+      .map((g) => ({
+        about: aboutOf(g.kind),
+        action: g.action,
+        target: g.target,
+        times: g.times,
+        share: total ? g.times / total : 0,
+        roles: [...g.roles].sort(),
+        standing: g.standing.kind,
+        ...(g.standing.why && { why: g.standing.why }),
+        // Only on an unowned cause: what kind of thing it is, and what to do.
+        ...(g.nature && { kind: g.nature.kind, hint: g.nature.hint }),
+        ...(g.expected && { expected: g.expected }),
+        owners: g.standing.owners,
+        ownersThen: g.ownersThen,
+        // How many of the roles that hit this would still hit it. `some` and
+        // not `every`: two roles out of three still blocked is still friction,
+        // and requiring all of them would quietly retire a live cause the day
+        // one role got a grant.
+        stillDenied: [...g.roles].filter((r) => cfg.roles[r] && !ask(cfg, r, g.action, g.target).allowed).length,
+      })),
+  };
+}
+
+/** What a log line was about. Lines from before the field existed are files. */
+const ABOUT = ["file", "key", "network", "system", "tool"];
+function aboutOf(kind) {
+  return ABOUT.includes(kind) ? kind : "file";
+}
+
+/**
+ * Walls as the console shows them: each with what it was about and, when no
+ * role owns the path, the same kind and hint the Denied screen gives it.
+ *
+ * Without this the two screens contradicted each other about one path: Walls
+ * said `.env.local` "has no owner — no role can write it until one claims it",
+ * an invitation to give it one, while Denied said it is a credential and never
+ * to grant a write to it. The hint is kinds.js's, so it is the same sentence.
+ *
+ * A copy: the MCP server hands out walls() as it is, and this adds to it.
+ */
+export function describeWalls(cfg, byRole, entries) {
+  const kindOfLine = new Map();
+  for (const e of entries) if (e.verdict === "denied" && e.target) kindOfLine.set(`${e.role}\u0000${e.action}\u0000${e.target}`, e.kind);
+  const standOf = standingOf(cfg);
+  const out = {};
+  const unowned = [];
+  for (const [role, list] of Object.entries(byRole)) {
+    out[role] = list.map((w) => {
+      const about = aboutOf(kindOfLine.get(`${role}\u0000${w.action}\u0000${w.target}`));
+      // An expected wall (walls.js) is not the agent retrying anything.
+      const x = { ...w, about, retried: w.expected ? 0 : w.times - 1 };
+      // Every file wall, owned or not: a protected path can also lie inside
+      // someone's territory, and "owned" must not hide "never granted". The
+      // owners are today's, as Denied's are.
+      if (about === "file") {
+        const s = standOf({ kind: "file", target: w.target });
+        x.standing = s.kind;
+        x.owners = s.owners ?? [];
+        if (s.why) x.why = s.why;
+        if (s.kind === "unowned") unowned.push(x);
+      }
+      return x;
+    });
+  }
+  const natures = kindsOf(unowned.map((w) => w.target), { keyDirs: cfg.keyDirs ?? [] });
+  for (const w of unowned) Object.assign(w, natures.get(w.target));
+  return out;
+}
+
+/**
+ * Every role's walls, from one read of the log.
+ *
+ * `entries` are log lines of any verdict (walls keeps the denied ones); only
+ * roles with at least one wall appear. The MCP read the log once per role — 32
+ * reads on a real policy — to answer the same question.
+ */
+export function wallsByRole(cfg, entries, { ask } = {}) {
+  const denied = entries.filter((e) => e.verdict === "denied");
+  return Object.fromEntries(
+    Object.keys(cfg.roles)
+      .map((r) => [r, walls(cfg, r, { entries: denied, ...(ask && { ask }) })])
+      .filter(([, w]) => w.length));
+}
+
+/**
+ * The request queue as a person should read it: pending, each with its handoff
+ * decided, and the requests the role has stopped asking for marked. `history`
+ * is the whole log, every verdict — a run that was only allowed things is
+ * still a run.
+ */
+export function queue(cfg, history, { readOnly = false } = {}) {
+  return queueOf(cfg, history, { readOnly });
+}