seisin 0.2.0 → 0.3.0

package/src/notify.js

@@ -0,0 +1,146 @@
+/**
+ * Tell a person when a request is filed.
+ *
+ * The queue is where a refusal becomes a handoff, and a queue only works if
+ * somebody looks at it. It was asynchronous with nothing to say it had moved:
+ * the handoff existed and the person did not know. This sends one message per
+ * new request — the role, the path, whose it is, and the command that answers
+ * it — to wherever the operator reads things (ntfy, Slack, a webhook).
+ *
+ * Approving is still a person at a terminal. This only notifies; it does not
+ * accept an answer, so it changes nothing about who decides. (Accepting one —
+ * nono's `approval-webhook-v1` — would, and is a separate decision.)
+ *
+ * Two rules, both from the review that found a role approving its own request
+ * through the console:
+ *   - the POST leaves from the parent, never from the role: the role's process
+ *     never holds the URL, and `SEISIN_NOTIFY_URL` is dropped from its
+ *     environment even if the role names it;
+ *   - the URL is not readable from any territory. A ntfy topic or a webhook is
+ *     a credential — whoever can read it can send the person a fake "approve
+ *     #3". So it lives in a key directory no role declares (`url_file`), or in
+ *     the parent's environment, and never as a plain value in seisin.toml,
+ *     which every role can read.
+ */
+import { readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { keyOf, pending, requestsPath, grantFor } from "./requests.js";
+
+export const FORMATS = ["text", "json", "slack"];
+export const ENV_URL = "SEISIN_NOTIFY_URL";
+
+/** The URL to notify, or null. Read in the parent only. */
+export function notifyUrl(config, env = process.env) {
+  if (env[ENV_URL]) return env[ENV_URL].trim();
+  if (!config.notify?.urlFile) return null;
+  try {
+    const url = readFileSync(join(config.root, config.notify.urlFile), "utf8").trim();
+    return url || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The body for one request, in the chosen format. */
+export function message(config, req, number, format = "text") {
+  const owner = req.owners?.length ? `It belongs to ${req.owners.join(", ")}.` : "Nobody owns it.";
+  const text =
+    `seisin (${basename(config.root)}): ${req.role} was refused ${req.action} on ${req.target}. ${owner} ` +
+    `Approve: seisin grant ${number} · decline: seisin decline ${number}`;
+  if (format === "slack") return { type: "application/json", body: JSON.stringify({ text }) };
+  if (format === "json")
+    return {
+      type: "application/json",
+      body: JSON.stringify({
+        text, repo: basename(config.root), number, role: req.role, action: req.action,
+        target: req.target, owners: req.owners ?? [], grant: grantFor(req),
+      }),
+    };
+  return { type: "text/plain; charset=utf-8", body: text };
+}
+
+/**
+ * One per run. `maybe(req)` after a request is recorded; `settle()` before the
+ * run exits, so a message still in flight is not cut off.
+ *
+ * Only the first time a request appears — the queue already counts repeats,
+ * and a person pinged on every retry stops reading the pings.
+ */
+export function notifier(config, { env = process.env, fetchImpl = globalThis.fetch, timeoutMs = 3000 } = {}) {
+  const url = notifyUrl(config, env);
+  const format = env.SEISIN_NOTIFY_FORMAT && FORMATS.includes(env.SEISIN_NOTIFY_FORMAT)
+    ? env.SEISIN_NOTIFY_FORMAT
+    : config.notify?.format ?? "text";
+  const file = requestsPath(config.root);
+  const known = url ? new Set(pending(file).map((p) => p.key)) : new Set();
+  const inflight = [];
+  const failures = [];
+
+  function maybe(req) {
+    if (!url) return false;
+    const key = keyOf(req);
+    if (known.has(key)) return false;
+    known.add(key);
+    const queue = pending(file);
+    const number = queue.findIndex((p) => p.key === key) + 1;
+    if (number < 1) return false;
+    const { type, body } = message(config, { ...req, owners: req.owners ?? queue[number - 1].owners }, number, format);
+    inflight.push(
+      fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": type },
+        body,
+        // A redirect would send the request to a place nobody configured.
+        redirect: "error",
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+        .then((r) => { if (!r.ok) failures.push(`HTTP ${r.status}`); })
+        .catch((e) => failures.push(e.name === "TimeoutError" ? "timed out" : e.message)),
+    );
+    return true;
+  }
+
+  async function settle(capMs = timeoutMs + 500) {
+    if (!inflight.length) return failures;
+    await Promise.race([Promise.allSettled(inflight), new Promise((ok) => setTimeout(ok, capMs))]);
+    return failures;
+  }
+
+  return { enabled: !!url, maybe, settle };
+}
+
+/**
+ * `[notify]` from seisin.toml, refused rather than guessed when it would leak.
+ * Called by the config loader.
+ */
+export function readNotify(table, { path, root, keyDirs, roles, own }) {
+  if (table === undefined) return null;
+  if (own(table, "url") !== undefined)
+    throw new Error(
+      `${path}: [notify] url is readable by every role — seisin.toml is not a secret. ` +
+      `Put the URL in a file inside a key directory no role declares and name it with url_file, ` +
+      `or set ${ENV_URL} in the environment that starts seisin.`);
+  const urlFile = own(table, "url_file");
+  const format = own(table, "format") ?? "text";
+  if (!FORMATS.includes(format))
+    throw new Error(`${path}: [notify] format = "${format}" is not one of ${FORMATS.join(", ")}`);
+  if (urlFile === undefined) return { urlFile: null, format };
+  if (typeof urlFile !== "string" || !urlFile.trim() || urlFile.startsWith("/") || urlFile.split("/").includes(".."))
+    throw new Error(`${path}: [notify] url_file must be a path inside the repo`);
+  const inKeyDir = keyDirs.some((d) => urlFile.startsWith(d.replace(/\/+$/, "") + "/"));
+  if (!inKeyDir)
+    throw new Error(
+      `${path}: [notify] url_file "${urlFile}" is not inside a key directory, so every role can read ` +
+      `it. Move it under ${keyDirs[0] ?? "a [keys] dir"}.`);
+  // A file key is written bare (`netlify.txt`, meaning the first key directory)
+  // or with its directory (`shared/api.txt`) — the same resolution settingsFor uses.
+  const resolve = (raw) => (raw.includes("/") ? raw : join(keyDirs[0] ?? "", raw));
+  const holders = Object.entries(roles)
+    .filter(([, r]) => r.keyEntries?.some((k) => k.kind === "file" && resolve(k.raw) === urlFile))
+    .map(([n]) => n);
+  if (holders.length)
+    throw new Error(
+      `${path}: [notify] url_file "${urlFile}" is declared as a key by ${holders.join(", ")} — ` +
+      `that role could read it and send the person a fake "approve". No role may hold it.`);
+  return { urlFile, format };
+}

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

@@ -65,6 +65,18 @@ export function renderReport(report) {
     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`);
   }
 
@@ -75,6 +87,23 @@ export function renderReport(report) {
     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()]