seisin 0.1.1 → 0.3.0

package/src/owners.js

@@ -10,6 +10,9 @@
  * agents have to read each other's code to do anything useful. Keys are the
  * exception, and they are handled separately below.
  */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { protectedBy } from "./surface.js";
 
 /**
  * Does this glob cover this path? Supports `**`, `*`, `?` and a trailing `/`.
@@ -37,13 +40,47 @@
  * kernel is already enforcing it. What was missing was seisin saying so.
  */
 export function covers(glob, path) {
-  const p = normalize(path);
-  let g = normalize(glob);
-  if (glob.endsWith("/")) g += "/**";
+  const p = normalized(path);
+  const m = matcherOf(glob);
   // The path itself, or anything beneath it. The `/` is load-bearing: without
   // it `src/api` would also cover `src/apifoo.ts`, which the kernel does not.
-  if (!WILD.test(g)) return p === g || p.startsWith(g + "/");
-  return toRegExp(g).test(p);
+  if (m.prefix !== null) return p === m.prefix || p.startsWith(m.prefix + "/");
+  return m.re.test(p);
+}
+
+/**
+ * The same glob and the same path, prepared once.
+ *
+ * `covers` is the inner loop of everything that asks "whose is this": owners of
+ * a path is every role's every glob against it, and the console asks that for
+ * every path of every role. On a real 32-role policy that was ~1.7M calls per
+ * refresh, each normalizing the glob again and compiling its regex again — 8 s
+ * of a console that polls, measured with a CPU profile (normalize alone 5 s).
+ * The answer never changes for the same string, so it is kept. Bounded: a
+ * server that runs for days sees paths from the log, and those keep coming.
+ */
+const MAX_CACHED = 50_000;
+const GLOBS = new Map();
+const PATHS = new Map();
+
+function matcherOf(glob) {
+  let m = GLOBS.get(glob);
+  if (m) return m;
+  let g = normalize(glob);
+  if (glob.endsWith("/")) g += "/**";
+  m = WILD.test(g) ? { prefix: null, re: toRegExp(g) } : { prefix: g, re: null };
+  if (GLOBS.size >= MAX_CACHED) GLOBS.clear();
+  GLOBS.set(glob, m);
+  return m;
+}
+
+function normalized(path) {
+  let p = PATHS.get(path);
+  if (p !== undefined) return p;
+  p = normalize(path);
+  if (PATHS.size >= MAX_CACHED) PATHS.clear();
+  PATHS.set(path, p);
+  return p;
 }
 
 /** The four characters toRegExp() treats as wildcards. */
@@ -103,13 +140,64 @@ function toRegExp(glob) {
   return new RegExp("^" + out + "$");
 }
 
+/** Is this path inside a `.git` directory (git's metadata, not a working file)? */
+export function isGitMetadata(path) {
+  return /(^|\/)\.git\//.test(normalize(path));
+}
+
 /** Every role whose territory covers `path`. Usually one; zero is a finding. */
 export function ownersOf(config, path) {
+  /**
+   * An absolute path is outside the repo, or it is made relative first.
+   *
+   * The kernel reports paths as it meets them, and toRepoRelative leaves the
+   * ones outside the repo absolute on purpose. They then met `writes = ["**"]`,
+   * which matches any string, so a refused write to ~/.claude/plugins was
+   * logged as "owned by dev, wide" — two roles that own nothing outside the
+   * repo. Measured on the first run of Claude Code under the new denies.
+   */
+  if (path.startsWith("/")) {
+    const root = config.root?.endsWith("/") ? config.root : `${config.root}/`;
+    if (!config.root || !path.startsWith(root)) return [];
+    path = path.slice(root.length);
+  }
   return Object.values(config.roles)
-    .filter((r) => r.writes.some((g) => covers(g, path)))
+    .filter((r) => r.writes.some((g) => covers(g, path)) && !neverWrites(r, path, config))
     .map((r) => r.name);
 }
 
+/**
+ * The `never_writes` entries the kernel will actually be given for this role.
+ *
+ * On macOS, all of them. On Linux, only the ones that exist on disk right now,
+ * and that is the runtime's shape rather than a choice: bubblewrap denies a
+ * path by mounting over it, and to mount over a path that does not exist it
+ * creates it on the host — an empty, read-only file that stays there while the
+ * role runs and forever if the process is killed. For `.git/index.lock`, the
+ * case the key exists for, that locks every other user of the repo out.
+ * Measured in Docker (Debian 12, bwrap 0.8.0) on 2026-09-23: present during the
+ * run, gone after a clean exit, still there after SIGKILL.
+ *
+ * `explain` asks this same function, so the sentence and the kernel agree: a
+ * document stricter than the boundary is the direction this project refuses.
+ * `check` names the entries that are not enforced.
+ */
+export function enforcedNeverWrites(config, role) {
+  const all = role?.neverWrites ?? [];
+  if (process.platform !== "linux" || !config?.root) return all;
+  return all.filter((g) => existsSync(join(config.root, g.replace(/\/\*\*$/, ""))));
+}
+
+/**
+ * The `never_writes` entry of `role` that covers `path`, or null.
+ *
+ * `?? []` because a caller embedding the library builds role objects itself,
+ * and one built before the key existed must keep meaning what it meant.
+ */
+export function neverWrites(role, path, config = null) {
+  return enforcedNeverWrites(config, role).find((g) => covers(g, path)) ?? null;
+}
+
 /** Every role allowed to read `key`, matched with or without its extension. */
 export function keyHolders(config, key) {
   const dirs = config.keyDirs ?? [];
@@ -149,7 +237,72 @@ export function keyHolders(config, key) {
  * not a permission problem, it is a hole in the map. Saying so is more useful
  * than denying quietly, and it is the only way the hole ever gets fixed.
  */
+/**
+ * A connection the kernel refused: `tcp:<port>` or a unix socket path.
+ *
+ * The kernel does not say which host — its line is `remote:*:<port>` — so the
+ * sentence says the port and what the policy gives for it, and nothing it
+ * cannot know. Three answers, because they send a person to three places:
+ *
+ *   - the port is not in `local_ports`: a policy question, add it or do not;
+ *   - it is, and was refused anyway: the client dialled directly instead of
+ *     through the proxy — a MySQL driver, Chromium, a raw socket — and adding
+ *     the port again will not change that;
+ *   - a unix socket: seisin grants none, on purpose. The one that comes up is
+ *     Docker's, and a role that can reach Docker can mount the whole disk.
+ *
+ * Never an owner and never a request: a port is not anybody's territory.
+ */
+function explainConnect(config, role, target) {
+  const r = config.roles[role];
+  const port = /^tcp:(\d+)$/.exec(target)?.[1];
+  if (port) {
+    const n = Number(port);
+    if (r?.localPorts?.includes(n))
+      return {
+        allowed: false, owners: [], network: true, listed: true,
+        reason: `port ${n} is in ${role}'s local_ports, but this client skipped the proxy. ` +
+          `curl, fetch and urllib use HTTP_PROXY on their own; a database driver or a browser ` +
+          `has to be pointed at it`,
+      };
+    // The kernel names no host, and every direct dial is refused — to an
+    // outside host as much as to localhost. So both readings, not a guess:
+    // advising `local_ports = [443]` for a client that skipped the proxy on
+    // its way to the internet opens a port and fixes nothing.
+    return {
+      allowed: false, owners: [], network: true,
+      reason: `port ${n}, host unknown. Local service: a person adds it to local_ports` +
+        `${r?.localPorts?.length ? ` (has ${r.localPorts.join(", ")})` : ""}. ` +
+        `Outside host: the client skipped HTTP_PROXY`,
+    };
+  }
+  return {
+    allowed: false, owners: [], network: true,
+    reason: `${target} is a unix socket, and roles get none` +
+      (/docker\.sock$/.test(target)
+        ? `. Docker's socket can mount any directory on this machine: start containers outside ` +
+          `the role and reach them by port`
+        : ""),
+  };
+}
+
+/** May this role load the MCP server `name`? A declaration, not something the kernel sees. */
+function explainMcp(config, role, name) {
+  const list = config.roles[role]?.mcp;
+  if (list == null)
+    return { allowed: true, owners: [], mcp: true, declared: false,
+      reason: `${role} has no mcp list, so the policy does not limit its MCP servers` };
+  if (list.includes(name))
+    return { allowed: true, owners: [], mcp: true, declared: true, reason: `${role} declares mcp = [${list.map((n) => `"${n}"`).join(", ")}]` };
+  return { allowed: false, owners: [], mcp: true, declared: true,
+    reason: list.length
+      ? `${role} may load only ${list.join(", ")}. Adding ${name} is a change to its mcp list`
+      : `${role} declares mcp = [], no MCP servers` };
+}
+
 export function explain(config, role, action, target) {
+  if (action === "connect") return explainConnect(config, role, target);
+  if (action === "mcp") return explainMcp(config, role, target);
   if (action === "read") {
     const holders = keyHolders(config, target);
     if (holders.includes(role)) return { allowed: true, owners: holders, reason: `${role} declares ${target}` };
@@ -159,7 +312,56 @@ export function explain(config, role, action, target) {
   }
 
   const owners = ownersOf(config, target);
+  /**
+   * Protected before anything else, because no territory reaches it.
+   *
+   * The policy, seisin's state, the key directories, what the parent executes
+   * or reads for a key, and the files that make git or Claude Code run
+   * something outside the box. The kernel denies all of them to every role —
+   * surface.js has the list and the reasons — so saying "belongs to dev" about
+   * `seisin.toml` sent a request to a person that no grant could satisfy.
+   */
+  const guard = protectedBy(config, target);
+  if (guard)
+    return {
+      allowed: false, owners, protected: guard.why,
+      reason: `${target} is protected (${guard.why}) — no role writes it, so there is nothing to grant`,
+    };
+  /**
+   * Named for what it is, and checked before "no owner".
+   *
+   * A path the role gave up through `never_writes` is not a permission it is
+   * missing. Said as "belongs to nobody", the agent files a request, a person
+   * approves it, and the subtraction is undone from the other side without
+   * anyone deciding to undo it.
+   */
+  const r = config.roles[role];
+  const barred = r && r.writes.some((g) => covers(g, target)) ? neverWrites(r, target, config) : null;
+  if (barred)
+    return {
+      allowed: false, owners, neverWrites: barred,
+      reason: `${target} is denied by never_writes of ${role} ("${barred}") — ` +
+        `a subtraction written into the policy, not a missing permission`,
+    };
   if (owners.includes(role)) return { allowed: true, owners, reason: `${target} is inside ${role}'s territory` };
+  /**
+   * Git's own bookkeeping in a repository this role does not write.
+   *
+   * Lock files, FETCH_HEAD, objects, refs, packed-refs: never a territory to
+   * hand over, because granting them is letting the role rewrite somebody
+   * else's history. Codex keeps `.git` read-only under a writable root for the
+   * same reason; nono and Gemini grant the whole of it. Here it stays refused
+   * and is said for what it is — not "belongs to X, ask them", which filed a
+   * request per lock file (327 of them for one index.lock on one portfolio)
+   * that nobody could sensibly approve. The requests side skips it too.
+   */
+  if (isGitMetadata(target))
+    return {
+      allowed: false, owners, gitMetadata: true,
+      reason: `${target} is git's own bookkeeping in a repository ${role} does not write — ` +
+        `not a permission to ask for. Read what you need (git log, git show, git ls-remote) ` +
+        `or work in a worktree of your own`,
+    };
   if (owners.length === 0)
     return { allowed: false, owners: [], reason: `${target} has no owner — no role can write it until one claims it` };
   return { allowed: false, owners, reason: `${target} belongs to ${owners.join(", ")}` };

package/src/paths.js

@@ -0,0 +1,50 @@
+/**
+ * One way to turn whatever path a caller holds into the repo-relative path the
+ * policy is written in.
+ *
+ * It was copied by hand into four places (explain, whose, the hook, run) and a
+ * fifth, the MCP server, never had it: `seisin_explain` answered "has no owner"
+ * for an absolute path the CLI called allowed — the same defect decisions.md
+ * records as closed, closed in one surface only. And none of the copies
+ * resolved symlinks, so on macOS a path under `/tmp` (a link to `/private/tmp`)
+ * was refused by the sentence while the kernel, which sees the real path,
+ * allowed it: the document tighter than the boundary, the direction this
+ * project refuses. Found by the read-only review of 2026-09-22.
+ */
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+
+/**
+ * `p` with its deepest existing ancestor resolved through symlinks and the rest
+ * appended as written. realpath alone fails on a path that does not exist yet,
+ * which is the shape of every file about to be created — a lock file included.
+ */
+export function realAncestor(p) {
+  let head = p, tail = "";
+  while (head !== dirname(head)) {
+    try {
+      const real = realpathSync(head);
+      return tail ? join(real, tail) : real;
+    } catch {
+      tail = tail ? join(basename(head), tail) : basename(head);
+      head = dirname(head);
+    }
+  }
+  return p;
+}
+
+/**
+ * Repo-relative when `target` is inside the repo, spelled either way; exactly as
+ * written when it is relative already or lies outside. A path outside keeps its
+ * honest "no owner" — it is a question about somewhere else.
+ */
+export function toRepoRelative(config, target) {
+  if (typeof target !== "string" || !isAbsolute(target)) return target;
+  const root = config.root;
+  const inside = (r, t) => t === r || t.startsWith(r + sep);
+  if (inside(root, target)) return relative(root, target) || ".";
+  const realRoot = realAncestor(root);
+  const realTarget = realAncestor(target);
+  if (inside(realRoot, realTarget)) return relative(realRoot, realTarget) || ".";
+  return target;
+}

package/src/render.js

@@ -30,18 +30,80 @@ export const err = (s) => process.stderr.write(s);
 
 /* ── the map ──────────────────────────────────────────────────────────── */
 
+/**
+ * A database's sidecars, shown as the database.
+ *
+ * `writes` carries the expansion because the grant and the sentence have to
+ * agree — see config.js. Printing all four is then honest and unreadable: on a
+ * real policy it turned eight databases into thirty-two rows of the same name
+ * with three suffixes, which is what the expansion existed to remove.
+ *
+ * So the list is collapsed back for DISPLAY only, and only where the base is
+ * present, and it says the sidecars are there rather than hiding them. A
+ * sidecar declared without its database still prints on its own line — that is
+ * unusual enough to be worth seeing.
+ */
+const SIDECAR_RE = /-(wal|shm|journal)$/;
+
+export function collapseSidecars(paths) {
+  const have = new Set(paths);
+  const out = [];
+  for (const p of paths) {
+    const base = p.replace(SIDECAR_RE, "");
+    if (SIDECAR_RE.test(p) && have.has(base)) continue;      // shown on its base
+    out.push(SIDECAR_RE.test(p) || !have.has(p + "-wal") ? p : `${p}${C.dim}+wal+shm+journal${C.off}`);
+  }
+  return out;
+}
+
 /** The `check` report, as text. Takes the object `inspect()` returns. */
 export function renderReport(report) {
   const lines = [`\n${C.b}${report.where}${C.off}\n\n`];
   const width = Math.max(...report.roles.map((r) => r.name.length), 4);
 
   for (const r of report.roles) {
-    const writes = r.writes.join(" ") || `${C.dim}nothing${C.off}`;
+    const writes = collapseSidecars(r.writes).join(" ") || `${C.dim}nothing${C.off}`;
     const keys = r.keys.length ? r.keys.join(" ") : `${C.dim}none${C.off}`;
     lines.push(`  ${C.b}${r.name.padEnd(width)}${C.off}  ${C.blue}writes${C.off} ${writes}\n`);
+    // Only when present: absent is the default, and a "never_writes nothing" line
+    // on every role is noise that teaches the reader to skip the one that matters.
+    if (r.neverWrites?.length)
+      lines.push(`  ${" ".repeat(width)}  ${C.yellow}never${C.off}  ${collapseSidecars(r.neverWrites).join(" ")}\n`);
+    if (r.trustd)
+      lines.push(`  ${" ".repeat(width)}  ${C.yellow}trustd${C.off} TLS through the system verifier (trustd)\n`);
+    if (r.localBinding)
+      lines.push(`  ${" ".repeat(width)}  ${C.yellow}listen${C.off} local ports (local_binding)\n`);
+    if (r.mcp)
+      lines.push(`  ${" ".repeat(width)}  ${C.yellow}mcp${C.off}    ${r.mcp.length ? r.mcp.join(" ") : "none"} ${C.dim}(declared; the launcher enforces it)${C.off}\n`);
+    if (r.localPorts?.length)
+      lines.push(`  ${" ".repeat(width)}  ${C.yellow}reach${C.off}  localhost ${r.localPorts.join(" ")} ${C.dim}(local_ports, through the proxy)${C.off}\n`);
     lines.push(`  ${" ".repeat(width)}  ${C.green}keys${C.off}   ${keys}\n\n`);
   }
 
+  if (report.providers?.length) {
+    lines.push(`  ${C.b}key providers${C.off} ${C.dim}— seisin runs these itself, outside the sandbox, as you${C.off}\n`);
+    for (const p of report.providers)
+      lines.push(`  ${C.green}${p.name}${C.off}  ${p.command.join(" ")}${p.mode ? `  ${C.dim}(${p.mode})${C.off}` : ""}\n`);
+    lines.push("\n");
+  }
+
+  // What the kernel refuses inside a territory, and why. Shown because each one
+  // takes something from a territory as written; capped because a monorepo has
+  // a hooks directory per package and the reader needs the shape, not all 200.
+  if (report.protected?.length) {
+    const root = report.where ? report.where.replace(/\/[^/]*$/, "/") : "";
+    const show = (p) => (root && p.startsWith(root) ? p.slice(root.length) : p.replace(/^\/Users\/[^/]+|^\/home\/[^/]+/, "~"));
+    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, refused anyway: something outside the box runs or reads it${C.off}\n`);
+    const LIMIT = 12;
+    for (const e of report.protected.slice(0, LIMIT)) {
+      const who = e.roles.length > 3 ? `${e.roles.slice(0, 3).join(", ")} +${e.roles.length - 3}` : e.roles.join(", ");
+      lines.push(`  ${show(e.path)}  ${C.dim}${e.why} · ${who}${C.off}\n`);
+    }
+    if (report.protected.length > LIMIT)
+      lines.push(`  ${C.dim}… and ${report.protected.length - LIMIT} more${C.off}\n`);
+    lines.push("\n");
+  }
+
   for (const w of report.warnings) {
     lines.push(`  ${C.yellow}${w.headline}${C.off}\n`);
     if (w.detail) lines.push(`  ${C.dim}${w.detail}${C.off}\n`);

package/src/requests.js

@@ -26,6 +26,7 @@
  * rewritten is not evidence. A request that is granted or refused is not
  * deleted — it is followed by a line saying what happened to it.
  */
+import { neverWrites, isGitMetadata, covers } from "./owners.js";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { STATE_DIR, tomlString } from "./layout.js";
@@ -173,6 +174,68 @@ export function pending(file, { includeSettled = false } = {}) {
   return includeSettled ? all : all.filter((r) => r.state === "pending");
 }
 
+/**
+ * How many runs of the role, after the last time it asked, make a request old.
+ *
+ * A request is recorded again on every refusal, so one the role still needs
+ * keeps a fresh `last`. One whose need went away — the work moved somewhere the
+ * role may write, or the task ended — stops being asked while the role keeps
+ * running. Three runs is enough to say "not since" and few enough that a queue
+ * does not carry a dead request for a week.
+ */
+export const STALE_RUNS = 3;
+
+/**
+ * Two log lines of a role this far apart belong to different runs — for lines
+ * written before the log had a run marker. Lines with `run` are counted by it.
+ */
+export const RUN_GAP_MS = 10 * 60_000;
+
+/**
+ * How many runs produced these lines, strictly after `since` (ms).
+ *
+ * By the `run` id when a line has one (intake.js writes it on every line since
+ * 2026-09-23), by the gap otherwise. The gap guessed: three runs started a
+ * minute apart by an orchestrator counted as one, and one run idle for eleven
+ * minutes counted as two.
+ */
+export function runsAfter(entries, since, gapMs = RUN_GAP_MS) {
+  const ids = new Set();
+  const untagged = [];
+  for (const e of entries) {
+    const t = Date.parse(e.at);
+    if (Number.isNaN(t) || t <= since) continue;
+    if (e.run) ids.add(e.run);
+    else untagged.push(t);
+  }
+  untagged.sort((a, b) => a - b);
+  let n = 0, prev = -Infinity;
+  for (const t of untagged) { if (t - prev > gapMs) n++; prev = t; }
+  return ids.size + n;
+}
+
+/**
+ * Marks the requests the role has stopped asking for, read off the log.
+ *
+ * Marked, never settled and never moved. Declining is a person's decision, and
+ * reordering would shift the numbers `grant <n>` is typed against while
+ * nobody decided anything. The mark says what is true — the role ran N times
+ * since and did not ask again — and leaves the rest to whoever reads it.
+ * `entries` are log lines (`read(logPath(root))`); `now` is for the tests.
+ */
+export function markStale(queue, entries, { runs = STALE_RUNS, gapMs = RUN_GAP_MS } = {}) {
+  const byRole = new Map();             // role -> its log lines
+  for (const e of entries) {
+    if (!e.role) continue;
+    (byRole.get(e.role) ?? byRole.set(e.role, []).get(e.role)).push(e);
+  }
+  for (const r of queue) {
+    const n = runsAfter(byRole.get(r.role) ?? [], Date.parse(r.last), gapMs);
+    if (n >= runs) r.stale = { runs: n, since: r.last };
+  }
+  return queue;
+}
+
 /**
  * Adds a granted glob to a role in the config text, with its provenance.
  *
@@ -195,6 +258,31 @@ export function pending(file, { includeSettled = false } = {}) {
  * is the worst possible bug, and it is not exotic: a role with only `keys`
  * declared is an ordinary config.
  */
+/**
+ * Refuses a grant that `never_writes` would cancel, before anything is written.
+ *
+ * A request filed before the subtraction existed can still be in the queue.
+ * Approving it would add the path to `writes` and change nothing — denyWrite
+ * wins — so the person would believe they granted something the kernel still
+ * refuses. The two keys contradict each other, and which one should win is the
+ * decision; seisin will not make it by writing one of them silently.
+ */
+export function refuseIfBarred(config, request) {
+  if (request.action === "read") return;
+  const role = config.roles?.[request.role];
+  const hit = role && neverWrites(role, request.target, config);
+  if (hit)
+    throw new Error(
+      `${request.target} is under never_writes of ${request.role} ("${hit}"), which wins over ` +
+      `writes. Granting it would change nothing. If the subtraction is wrong, remove that ` +
+      `entry from [roles.${request.role}]; otherwise decline this request.`);
+  // Only a repository the role does not write: its own `.git` is its own business.
+  if (isGitMetadata(request.target) && !(role?.writes ?? []).some((g) => covers(g, request.target)))
+    throw new Error(
+      `${request.target} is git's own bookkeeping, not a territory: granting it lets ${request.role} ` +
+      `rewrite another owner's history. Decline it; a role that needs to commit gets a worktree of its own.`);
+}
+
 export function applyGrant(toml, request, note = "") {
   const field = request.action === "read" ? "keys" : "writes";
   const header = new RegExp(`^\\[roles\\.${escapeRe(request.role)}\\]\\s*$`, "m");

package/src/review.js

@@ -73,7 +73,7 @@ function findings(config, entries, minDenials) {
   const stopped = new Map();                 // role + directory -> how often
   for (const e of entries) {
     if (e.verdict !== "denied" || !e.target) continue;
-    const dir = e.action === "read" ? e.target : dirOf(e.target);
+    const dir = e.action === "read" || e.action === "connect" ? e.target : dirOf(e.target);
     const key = `${e.role} ${e.action} ${dir}`;
     const seen = stopped.get(key) ?? {
       role: e.role, action: e.action, where: dir, times: 0,
@@ -81,7 +81,7 @@ function findings(config, entries, minDenials) {
       // Carried by the log from both writers — the hook sets it from the config
       // and so does the parent for a kernel denial. Recomputing it from the path
       // here would be a second opinion on a settled question.
-      kind: e.kind === "key" ? "key" : "file",
+      kind: e.kind === "key" || e.kind === "network" ? e.kind : "file",
     };
     seen.times++;
     stopped.set(key, seen);
@@ -91,8 +91,10 @@ function findings(config, entries, minDenials) {
     .filter((f) => f.times >= minDenials)
     .sort((a, b) => b.times - a.times);
 
-  const friction = repeated.filter((f) => f.kind !== "key");
+  const friction = repeated.filter((f) => f.kind !== "key" && f.kind !== "network");
   const guarded = repeated.filter((f) => f.kind === "key");
+  // Ports and sockets: repeated, and not a thing `grant` can answer.
+  const connects = repeated.filter((f) => f.kind === "network");
 
   /* ── 2. what was granted and never used ─────────────────────────────── */
 
@@ -144,7 +146,9 @@ function findings(config, entries, minDenials) {
 
   const unowned = new Map();
   for (const e of entries) {
-    if (!e.target || e.kind === "key") continue;
+    // A key directory is closed on purpose; a port or a socket is not a path
+    // anybody could own. Neither is a hole in the map.
+    if (!e.target || e.kind === "key" || e.kind === "network") continue;
     if (ownersOf(config, e.target).length) continue;
     const dir = dirOf(e.target);
     unowned.set(dir, (unowned.get(dir) ?? 0) + 1);
@@ -153,6 +157,7 @@ function findings(config, entries, minDenials) {
   return {
     friction,
     guarded,
+    connects,
     unused,
     unusedKnowable: knowable,
     unowned: [...unowned.entries()]

package/src/rundir.js

@@ -0,0 +1,113 @@
+/**
+ * One private directory per run, for everything that belongs to that run only:
+ * the audit socket, the sandbox settings, and `scratch` keys.
+ *
+ * ── Why ──
+ * These lived in two places and both leaked. The settings were written to
+ * `.seisin/<role>.json`, one file per ROLE, so two runs of the same role — an
+ * orchestrator does that all day — wrote the same file with different socket
+ * paths, and one could start with the other's. The socket and the scratch keys
+ * lived in `$TMPDIR/seisin-XXXX/`, private by mode, but every role runs as the
+ * same user and every role can read the temp dir: measured on 2026-09-23, one
+ * role read another's `scratch` key while it ran (`cat …/keys/S` → the value).
+ *
+ * ── How ──
+ * All runs live under one root, `$TMPDIR/snr/`, and each role's profile denies
+ * reading that root and allows reading its own run's directory — the shape the
+ * key directories and the isolated homes already use. The root is denied for
+ * writing too, so no role can swap it for a symlink between runs.
+ *
+ * Short names on purpose: the socket path is capped near 104 bytes on macOS.
+ */
+import { mkdirSync, mkdtempSync, lstatSync, chmodSync, writeFileSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { realOrSelf } from "./grants.js";
+import { channelName } from "./spool.js";
+
+export const RUNS_NAME = "snr";
+
+/**
+ * The root every run lives under, created private, and checked.
+ *
+ * Real path, because the kernel enforces on real paths and on macOS the temp
+ * dir sits behind /var → /private/var. Refused rather than used when it is not
+ * a directory of this user's with nobody else's bits on it: it holds keys.
+ */
+export function runsRoot(base = tmpdir()) {
+  const root = join(realOrSelf(base), RUNS_NAME);
+  try { mkdirSync(root, { mode: 0o700 }); } catch (e) { if (e.code !== "EEXIST") throw e; }
+  const st = lstatSync(root);
+  const mine = typeof process.getuid !== "function" || st.uid === process.getuid();
+  if (st.isSymbolicLink() || !st.isDirectory() || !mine)
+    throw new Error(
+      `${root} is not a directory of yours (${st.isSymbolicLink() ? "it is a symlink" : "wrong owner or type"}).\n` +
+      `  It holds each run's socket and keys, so seisin will not use it. Remove it and run again.`);
+  if (st.mode & 0o077) chmodSync(root, 0o700);
+  return root;
+}
+
+/** Is the process that owns a run directory still alive? */
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+/**
+ * Removes the directories of runs whose process is gone.
+ *
+ * A run cleans up after itself on exit. A run that is killed does not, and
+ * its directory keeps its `scratch` keys on disk indefinitely — measured by
+ * SIGKILL on a keyed run. Swept at the start of the next one; a directory
+ * without a pid file is younger than the write that creates it, and is left.
+ */
+function sweep(root) {
+  for (const name of readdirSync(root)) {
+    const dir = join(root, name);
+    let pid;
+    try { pid = Number(readFileSync(join(dir, "pid"), "utf8")); } catch { continue; }
+    if (pid && !alive(pid)) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Opens a run: its id, its directory, and the paths inside it.
+ *
+ * The id is the one the rest of the run uses — the nonce in the kernel's
+ * command tag, the `run` field on every log line — so one value ties the
+ * socket, the settings, the log and the kernel's reports together.
+ */
+export function openRun({ base = tmpdir(), id = randomUUID() } = {}) {
+  const root = runsRoot(base);
+  try { sweep(root); } catch { /* a sweep that fails is not a reason not to run */ }
+  const dir = mkdtempSync(join(root, `${id.slice(0, 6)}-`));
+  writeFileSync(join(dir, "pid"), String(process.pid), { mode: 0o600 });
+  return {
+    id,
+    dir,
+    root,
+    // A socket on macOS, a FIFO on Linux, where the runtime blocks every unix
+    // socket inside the box (spool.js).
+    sock: join(dir, channelName()),
+    keys: join(dir, "keys"),
+    /**
+     * `wx`: created by this call or not at all. A settings file that already
+     * exists is not this run's, and the runtime would read whatever it says.
+     */
+    writeSettings(settings) {
+      const file = join(dir, "settings.json");
+      writeFileSync(file, JSON.stringify(settings, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+      return file;
+    },
+    close() {
+      try { rmSync(dir, { recursive: true, force: true }); } catch {}
+    },
+  };
+}
+
+/** The runs root a socket path belongs to, or null when it is not one of ours. */
+export function runsRootOf(sock) {
+  if (!sock) return null;
+  const root = dirname(dirname(sock));
+  return basename(root) === RUNS_NAME ? root : null;
+}