seisin 0.3.0 → 0.4.2

package/README.md

@@ -38,7 +38,7 @@ says why, and a test holds one half of it.
 
 **The honest parts** · [How it holds](#how-it-holds) · [What it is not](#what-it-is-not) · [Why not a container](#why-not-a-container) · [Prior art](#prior-art) · [Status](#status)
 
-**Deeper** · [Keys](docs/keys.md) · [Agents](docs/agents.md) · [Day one](docs/first-day.md) · [Scratch](docs/scratch.md) · [Glossary](docs/glossary.md) · [What it has been put through](docs/what-it-has-been-put-through.md) · [Field notes](docs/field-notes.md) · [Decisions](docs/decisions.md) · [Permission requests](docs/permission-requests.md) · [Contributing](CONTRIBUTING.md)
+**Deeper** · [Keys](docs/keys.md) · [Agents](docs/agents.md) · [Day one](docs/first-day.md) · [Scratch](docs/scratch.md) · [Glossary](docs/glossary.md) · [What it has been put through](docs/what-it-has-been-put-through.md) · [Field notes](docs/field-notes.md) · [OpenShell compatibility](docs/openshell.md) · [Decisions](docs/decisions.md) · [nono backend contract](docs/nono-backend.md) · [Permission requests](docs/permission-requests.md) · [Contributing](CONTRIBUTING.md)
 
 </details>
 
@@ -161,8 +161,8 @@ fixtures:
 
 And three things that outweigh all of the above:
 
-1. **It is days old and has one author.** Around three thousand lines that nobody has
-   audited except its writer and one field report. "Secure" is not a word earned that fast.
+1. **It is young and has one author.** The first public release was September 2026, and the
+   implementation is still moving quickly. "Secure" is not a word earned by size or test count.
 2. **The enforcement is someone else's beta.** `sandbox-runtime` describes itself as a
    research preview with an evolving API. A hole there is a hole here.
 3. **Two platforms tested, by one person, on one machine each.**
@@ -672,7 +672,7 @@ This space already has good work, and seisin is not the first thing here:
 - [`anthropics/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime) — the enforcement. seisin is a thin thing on top of a serious one.
 - [`kornysietsma/claude-code-permissions-hook`](https://github.com/kornysietsma/claude-code-permissions-hook) — granular `PreToolUse` rules, one global policy.
 - [`XuebinMa/agent-guard`](https://github.com/XuebinMa/agent-guard) — a permission-enforcement SDK, also one global policy.
-- [`NVIDIA/OpenShell`](https://github.com/NVIDIA/openshell) — a runtime that sandboxes an agent with Landlock and seccomp, under a declarative policy. Serious, and the closest thing here by weight.
+- [`NVIDIA/OpenShell`](https://github.com/NVIDIA/openshell) — a runtime that sandboxes an agent with Landlock and seccomp, under a declarative policy. Serious, and the closest thing here by weight. It was evaluated as a possible backend; [the measured compatibility decision](docs/openshell.md) explains why it is currently an execution target candidate rather than a drop-in replacement.
 - [`dredozubov/hazmat`](https://github.com/dredozubov/hazmat) — runs the agent as a different system user, with `pf` rules and snapshots.
 - [`nolabs-ai/nono`](https://github.com/nolabs-ai/nono) — a kernel sandbox for agents on the host (Seatbelt, Landlock), with per-tool child sandboxes, a credential proxy with endpoint filtering, approval webhooks and a tamper-evident audit log. The most complete sandbox here, and on a Mac the one that enforces through the same kernel seisin does. `nono why` explains *which rule* denied something and how to allow it; it has no notion of *whose* it was.
 - *Directory ownership* is recommended in half the multi-agent write-ups. As far as I could find, nobody enforces it, and nobody names the owner in the refusal. That gap is the reason for this repo.
@@ -692,25 +692,21 @@ They compose rather than compete: the agent seisin confines could be running ins
 them.
 
 *One detail worth knowing before you compare, and it is about placement rather than quality.
-Read from [OpenShell's support matrix][osm] on 2026-09-21, not measured here: macOS is a
-supported platform, and on it "these kernel modules run inside the Docker Desktop Linux VM,
-not on the host kernel". So on a Mac, OpenShell confines an agent inside a Linux VM, and
-seisin confines a process on the host through Seatbelt. Both are kernel enforcement; they are
-not the same kernel, and which one you want depends on whether the thing you are protecting is
-on the host. seisin [says where each of its own claims was
-measured](docs/what-it-has-been-put-through.md#where-each-claim-was-actually-run).*
-
-[osm]: https://docs.nvidia.com/openshell/reference/support-matrix
+OpenShell was [evaluated here on 2026-09-27](docs/openshell.md), through its Docker driver on
+an Intel Mac. That confines an agent inside Docker Desktop's Linux VM; seisin confines a
+process on the host through Seatbelt. OpenShell also offers other drivers, including a local
+microVM path on supported Apple Silicon Macs. These are kernel-enforced boundaries, but not
+the same kernel or workspace, and which one you want depends on what you are protecting.*
 
 ## Status
 
-`0.3.0`, 452 tests, of which **26 need `@anthropic-ai/sandbox-runtime` installed**
+`0.4.2`, 500 tests, of which **26 need `@anthropic-ai/sandbox-runtime` installed**
 and run real commands through the real kernel — and CI fails if the sandbox half *skips*, because
 a green run that quietly tested nothing looks exactly like a real one. That is not hypothetical:
 those eighteen skipped on Linux for a day, behind a runtime check that looked for the global
 install and missed the bundled one, and hid a defect that broke `seisin run` on that platform
-entirely. **326/326 on macOS 15 and on `ubuntu-latest` under bubblewrap**, nothing skipped on
-either, Node 18/20/22 in CI at every push — and 225/225 the same way on Debian 12.15
+entirely. **500 tests on macOS 15, 499 passing and 1 skipped** (it is Linux-only) — 2026-09-29;
+`ubuntu-latest` under bubblewrap runs the same suite, Node 18/20/22/24 in CI at every push — and 225/225 the same way on Debian 12.15
 with bubblewrap 0.8.0, the last time the suite was run in Docker.
 [Which claim was measured where](docs/what-it-has-been-put-through.md#where-each-claim-was-actually-run),
 and [what running agents behind it cost the people using it](docs/field-notes.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it blocks it tells you whose file it was.",
   "keywords": [
     "ai-agents",

package/src/cli.js

@@ -57,7 +57,7 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
   seisin log verify                     does the log's hash chain hold
   seisin watch                          follow the log live
   seisin init [--from-observations]     propose a ${CONFIG_NAME} for this repo
-  seisin ui [--port n]                  open the console, live
+  seisin ui [--port n] [--link]         open the console, live (--link reopens a running one)
   seisin mcp                            an MCP server on stdio — read-only
 
 Enforcement comes from @anthropic-ai/sandbox-runtime, which asks the OS.

package/src/commands/init.js

@@ -42,11 +42,19 @@ export function discover(root) {
     if (paths.length)
       return {
         source: p,
-        roles: [...new Set(paths)].slice(0, 8).map((g, i) => ({
-          name: g.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "") || `role-${i + 1}`,
-          writes: [g.endsWith("/") ? g + "**" : g],
-          keys: [],
-        })),
+        roles: [...new Set(paths)].slice(0, 8).map((g, i) => {
+          // CODEOWNERS anchors a leading "/" at the repo root; seisin's writes
+          // are already repo-relative, so a literal "/apps/**" would ask the
+          // kernel for the machine's /apps and make `explain` (which reads it as
+          // outside the repo) disagree with what the profile grants. Strip the
+          // anchor. A trailing "/" means a directory, so it becomes "/**".
+          const rel = g.replace(/^\/+/, "");
+          return {
+            name: rel.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "") || `role-${i + 1}`,
+            writes: [rel.endsWith("/") ? rel + "**" : rel],
+            keys: [],
+          };
+        }),
       };
   }
 

package/src/commands/log.js

@@ -10,7 +10,7 @@
  */
 import { createReadStream, watch as watchDir } from "node:fs";
 import { dirname, relative } from "node:path";
-import { read, logPath, size, verifyChain } from "../log.js";
+import { read, logPath, size, verifyLog, LOG_NAME } from "../log.js";
 import { renderEntry, C, out } from "../render.js";
 
 const flag = (argv, name) => {
@@ -43,20 +43,27 @@ export function log(config, argv = []) {
  * before the chain existed are reported as such, not as tampering.
  */
 function verify(config) {
-  const r = verifyChain(logPath(config.root));
+  const r = verifyLog(logPath(config.root));
   if (r.lines === 0) {
     out(`\n  ${C.dim}nothing recorded yet${C.off}\n\n`);
     return r;
   }
   const head = r.unchained ? `${r.unchained} line(s) from before the chain, then ` : "";
+  const segs = r.segments > 1 ? ` across ${r.segments} segments` : "";
+  // A dropped entry leaves no hole in the chain, so it is reported on its own
+  // line rather than as a break: nothing was tampered with, but something is
+  // missing, and an intact chain must not read as a complete record.
+  const dropped = r.dropped
+    ? `  ${C.yellow}${r.dropped} entr${r.dropped === 1 ? "y was" : "ies were"} never written${C.off}  another writer held the lock too long; see ${LOG_NAME}.dropped\n`
+    : "";
   if (!r.breaks.length) {
-    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)\n\n`);
+    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)${segs}\n${dropped}\n`);
     return r;
   }
   out(`\n  ${C.red}broken${C.off}  ${head}${r.chained} chained line(s), ${r.breaks.length} break(s):\n`);
   for (const b of r.breaks.slice(0, 10))
     out(`    line ${b.line}: expected prev ${b.expected}, found ${b.found ?? "none"}\n`);
-  out(`  ${C.dim}a line was edited, removed or reordered just before each of these${C.off}\n\n`);
+  out(`  ${C.dim}a line was edited, removed or reordered just before each of these${C.off}\n${dropped}\n`);
   process.exitCode = 1;
   return r;
 }

package/src/commands/requests.js

@@ -6,10 +6,9 @@
  * person acting in a channel the agent does not have. That is the invariant the
  * whole feature rests on — see docs/permission-requests.md.
  */
-import { readFileSync, writeFileSync } from "node:fs";
-import { pending, settle, applyGrant, refuseIfBarred, requestsPath, markStale } from "../requests.js";
+import { pending, settle, applyGrant, refuseIfBarred, requestsPath, markStale, editPolicy } from "../requests.js";
 import { read, logPath } from "../log.js";
-import { C, out } from "../render.js";
+import { C, out, safe } from "../render.js";
 
 /**
  * Which request you meant — by position, or by the identity it carries.
@@ -40,16 +39,18 @@ function pick(config, n) {
     return req;
   }
 
-  const hits = queue.filter((r) => r.key === arg || r.key.startsWith(arg));
-  if (hits.length === 1) return hits[0];
-  if (!hits.length)
-    throw new Error(
-      `no pending request matches "${arg}".\n` +
-      "  Use its number, or the id printed under it by `seisin requests`.");
+  // Exactly, never by prefix. A prefix let an id that had just been settled
+  // select a newer request whose id merely starts the same (`lib` → `lib-x`),
+  // and an agent chooses the paths ids are made of.
+  const hit = queue.find((r) => r.key === arg);
+  if (hit) return hit;
+  const near = queue.filter((r) => r.key.startsWith(arg));
   throw new Error(
-    `"${arg}" matches ${hits.length} pending requests:\n` +
-    hits.slice(0, 5).map((r) => `    ${r.key}`).join("\n") +
-    "\n  Name one exactly. Choosing for you is the mistake this avoids.");
+    `no pending request has the id "${arg}".\n` +
+    (near.length
+      ? `  ${near.length} start with it:\n` + near.slice(0, 5).map((r) => `    ${r.key}`).join("\n") +
+        "\n  Name one exactly. Choosing for you is the mistake this avoids."
+      : "  Use its number, or the id printed under it by `seisin requests`."));
 }
 
 export function requests(config) {
@@ -66,11 +67,11 @@ export function renderQueue(queue) {
   queue.forEach((r, i) => {
     const owners = r.owners.length ? ` ${C.dim}(owned by ${r.owners.join(", ")})${C.off}` : ` ${C.dim}(unowned)${C.off}`;
     const times = r.times > 1 ? ` ${C.dim}· asked ${r.times}×${C.off}` : "";
-    lines.push(`    ${C.b}#${i + 1}${C.off}  ${r.role} wants ${r.action} on ${C.b}${r.grant}${C.off}${owners}${times}\n`);
-    lines.push(`        ${C.dim}first asked over ${r.target}${C.off}\n`);
+    lines.push(`    ${C.b}#${i + 1}${C.off}  ${safe(r.role)} wants ${r.action} on ${C.b}${safe(r.grant)}${C.off}${owners}${times}\n`);
+    lines.push(`        ${C.dim}first asked over ${safe(r.target)}${C.off}\n`);
       // The stable way to name it: a number is a position in a queue that agents
       // are still writing to, and this does not move when the queue does.
-      lines.push(`        ${C.dim}id ${r.key}${C.off}\n`);
+      lines.push(`        ${C.dim}id ${safe(r.key)}${C.off}\n`);
     // Marked, not moved: the number above is what `grant <n>` is typed against.
     if (r.stale)
       lines.push(`        ${C.dim}not asked again in ${r.stale.runs} runs of ${r.role} since — likely no longer needed${C.off}\n`);
@@ -123,11 +124,18 @@ export function grant(config, argv = []) {
   const reason = i === -1 ? "" : argv[i + 1] ?? "";
 
   refuseIfBarred(config, req);
-  const before = readFileSync(config.path, "utf8");
-  const { toml, changed } = applyGrant(before, req, reason);
+  // Under a lock, and written atomically: a concurrent grant (another terminal
+  // or the console) must not clobber this one. See editPolicy.
+  let changed;
+  try {
+    ({ changed } = editPolicy(config, (before) => applyGrant(before, req, reason)));
+  } catch (e) {
+    if (e.code === "ELOCKED")
+      throw new Error("another grant is in progress — run this again in a moment");
+    throw e;
+  }
   if (!changed) throw new Error(`${req.role} already has ${req.grant} — nothing to add`);
 
-  writeFileSync(config.path, toml);
   settle(requestsPath(config.root), req.key, "granted", reason);
   out(
     `\n  ${C.green}granted${C.off}  ${req.role} → ${C.b}${req.grant}${C.off}\n` +

package/src/commands/run.js

@@ -75,8 +75,21 @@ export async function run(config, argv) {
    */
   const split = argv.indexOf("--");
   const role = argv[0];
-  const mine = split === -1 ? argv.slice(1) : argv.slice(1, split);
-  const cmd = split === -1 ? argv.slice(1) : argv.slice(split + 1);
+  let mine, cmd;
+  if (split !== -1) {
+    mine = argv.slice(1, split);
+    cmd = argv.slice(split + 1);
+  } else {
+    // No `--`: seisin's own flags are the leading `-options` only. From the
+    // first token that is not an option, everything is the command — its own
+    // flags are its business. `seisin run x echo hi --observe` used to read
+    // `--observe` as seisin's and put the run in observe mode; now that flag
+    // belongs to `echo`, and observe needs `seisin run x --observe -- echo hi`.
+    let i = 1;
+    while (i < argv.length && argv[i].startsWith("-")) i++;
+    mine = argv.slice(1, i);
+    cmd = argv.slice(i);
+  }
   if (!role || cmd.length === 0) throw new Error("usage: seisin run <role> -- <command...>");
   if (!config.roles[role])
     throw new Error(`unknown role "${role}". Known: ${Object.keys(config.roles).join(", ")}`);

package/src/commands/ui.js

@@ -5,22 +5,72 @@
  * foreground command you start and stop, serving one page and one JSON
  * document, on loopback. Nothing in the enforcement path touches it. If it is
  * not running you lose a window, not a boundary.
+ *
+ * The token that authorizes the page travels only in the link's fragment and is
+ * never in an HTTP response (see serve.js). So a lost link cannot be recovered
+ * over the wire — only from the terminal that printed it. `writeUiLink` keeps a
+ * user-only copy on disk so it can be recovered without reopening that leak:
+ * `--link` prints it, and starting over a busy port reopens it instead of just
+ * failing. See uilink.js.
  */
 import { spawnSync } from "node:child_process";
 import { relative } from "node:path";
 import { serve } from "../serve.js";
+import { writeUiLink, readUiLink, clearUiLink } from "../uilink.js";
 import { C, out } from "../render.js";
 
+function open(url) {
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawnSync(opener, [url], { stdio: "ignore", shell: process.platform === "win32" });
+}
+
 export async function ui(config, argv = []) {
   const i = argv.indexOf("--port");
   const port = i === -1 ? 4178 : Number(argv[i + 1]);
 
-  const server = await serve(config.path, port);
+  // `seisin ui --link`: print the live link a running console left, and open
+  // it, without starting anything. For when the terminal that had it is gone.
+  if (argv.includes("--link")) {
+    const found = readUiLink(port);
+    if (found && found.alive !== false) {
+      out(`\n  ${C.b}${found.url}${C.off}\n  ${C.dim}the link a seisin ui on ${port} is serving. open it here, do not paste it anywhere.${C.off}\n\n`);
+      open(found.url);
+      return;
+    }
+    if (found && found.alive === false) clearUiLink(port);
+    out(`\n  ${C.dim}no seisin ui running on ${port} — start one with: seisin ui${port === 4178 ? "" : ` --port ${port}`}${C.off}\n\n`);
+    return;
+  }
+
+  let server;
+  try {
+    server = await serve(config.path, port);
+  } catch (e) {
+    // A console is already on this port: hand back its live link rather than
+    // erroring, which is the case that sends people digging in the terminal.
+    if (e.code === "EADDRINUSE") {
+      const found = readUiLink(port);
+      if (found && found.alive !== false) {
+        out(
+          `\n  ${C.b}${found.url}${C.off}\n` +
+          `  ${C.dim}a seisin ui is already running on ${port}; reopening its link. ctrl-c that terminal to stop it.${C.off}\n\n`
+        );
+        open(found.url);
+        return;
+      }
+      // The port is busy but no live console left a link — a stale record, or
+      // something else is on the port. Drop the stale one and let the original
+      // "port is busy" message stand.
+      if (found && found.alive === false) clearUiLink(port);
+    }
+    throw e;
+  }
+
   const bound = server.address().port;
-  // The token rides in the fragment, which the browser keeps to itself: no
-  // request to this server, or to anything else, ever carries it. The page
-  // moves it into the tab's storage and strips it from the address bar.
   const url = `http://127.0.0.1:${bound}/#t=${server.seisinToken}`;
+  // Recorded before we print, so `--link` and a second `seisin ui` can find it.
+  writeUiLink(bound, url);
+
   // local_binding opens every port (macOS); local_ports opens the ones it
   // names, on every platform — so only a role that names THIS port counts.
   const reach = Object.values(config.roles)
@@ -31,15 +81,17 @@ export async function ui(config, argv = []) {
     `\n  ${C.b}${url}${C.off}\n` +
     `  ${C.dim}reading ${relative(process.cwd(), config.path)} and the log, live. ctrl-c to stop.${C.off}\n` +
     `  ${C.dim}the link carries this run's token: open it here, do not paste it anywhere.${C.off}\n` +
+    `  ${C.dim}lost it? this terminal has it above, or run: seisin ui --link${bound === 4178 ? "" : ` --port ${bound}`}${C.off}\n` +
     (reach.length
       ? `  ${C.yellow}${reach.join(", ")} can reach this port on localhost: they can load this page, ` +
         `but not the token, which only travels in the link above.${C.off}\n`
       : "") + "\n"
   );
 
-  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  spawnSync(opener, [url], { stdio: "ignore", shell: process.platform === "win32" });
+  open(url);
 
-  process.on("SIGINT", () => { server.close(); process.exit(0); });
+  const stop = () => { clearUiLink(bound); server.close(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
   return server;
 }

package/src/config.js

@@ -52,6 +52,8 @@ function dict() {
   return Object.create(null);
 }
 
+const isTable = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
 /** Read a property only if the object actually has it. */
 export function own(obj, key) {
   return obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
@@ -88,8 +90,12 @@ export function parseToml(text) {
           `A later block would silently override the earlier one — put every setting for ` +
           `${tableName} in one place.`);
       seenTables.add(tableName);
-      table = tableName.split(".").reduce((node, key) => {
+      table = tableName.split(".").reduce((node, key, k, parts) => {
         if (!Object.prototype.hasOwnProperty.call(node, key)) node[key] = dict();
+        else if (!isTable(node[key]))
+          throw new Error(
+            `${CONFIG_NAME}:${i + 1}: [${tableName}] — "${parts.slice(0, k + 1).join(".")}" is already ` +
+            `a value, not a table. One name cannot be both.`);
         return node[key];
       }, out);
       continue;
@@ -99,9 +105,18 @@ export function parseToml(text) {
     if (!pair) throw new Error(`${CONFIG_NAME}:${i + 1}: cannot read "${raw.trim()}"`);
 
     let [, key, value] = pair;
-    // An array may span lines; keep pulling until the brackets balance.
+    // An array may span lines; keep pulling until the brackets balance. Only
+    // the new line is searched: searching the whole growing value made an
+    // unclosed array of 100k lines take 20 s to be refused.
     if (value.startsWith("[") && !value.includes("]")) {
-      while (!value.includes("]") && i + 1 < lines.length) value += " " + stripComment(lines[++i]).trim();
+      const parts = [value];
+      let closed = false;
+      while (!closed && i + 1 < lines.length) {
+        const next = stripComment(lines[++i]).trim();
+        parts.push(next);
+        closed = next.includes("]");
+      }
+      value = parts.join(" ");
     }
     if (FORBIDDEN.has(key))
       throw new Error(`${CONFIG_NAME}:${i + 1}: "${key}" is a reserved name and cannot be a setting.`);
@@ -111,6 +126,20 @@ export function parseToml(text) {
         `${CONFIG_NAME}:${i + 1}: "${key}" is set twice in [${tableName || "the root"}]. ` +
         `The second would win, which is not a thing a permission file should do quietly.`);
     seenKeys.add(seen);
+    /**
+     * A key may not be a table that is declared elsewhere, in either order.
+     *
+     * `[roles.a]` with `network = []`, then `[roles]` and `a = true` forty lines
+     * down, used to replace the whole role with `true`: its `network = []` came
+     * back as "not set", which means the global allow list. `check` said
+     * nothing. It is the "last one wins" this parser refuses everywhere else,
+     * arriving by a different spelling.
+     */
+    if (Object.prototype.hasOwnProperty.call(table, key))
+      throw new Error(
+        `${CONFIG_NAME}:${i + 1}: "${key}" in [${tableName || "the root"}] is already the table ` +
+        `[${tableName ? tableName + "." : ""}${key}]. One name cannot be both — the value would replace ` +
+        `everything that table says.`);
     table[key] = readValue(value, i + 1);
   }
   return out;
@@ -255,9 +284,10 @@ function readValue(value, lineNo) {
 export function readIsolate(v) {
   if (v === true || v === "home") return "home";
   if (v === "credentials") return "credentials";
-  // Anything else is off, including a misspelling. A permission tool must not
-  // read a word it does not know as a stronger setting than the reader meant.
-  return false;
+  if (v === false || v === undefined) return false;
+  throw new Error(
+    `runtime.isolate must be false, true, "credentials", or "home", not ${JSON.stringify(v)}. ` +
+    `An unknown value cannot silently turn credential isolation off.`);
 }
 
 export function loadConfig(path) {
@@ -269,6 +299,16 @@ export function loadConfig(path) {
   // they prevent is invisible in review — the config reads one way and the
   // policy is another.
   const roles = own(parsed, "roles") ?? {};
+  // `roles = "x"` or `roles = [...]` at the root, or `[roles]` with `a = true`,
+  // would read as roles named "0", "1" or "a" with no settings of their own —
+  // and a role with nothing set gets the global defaults.
+  if (!isTable(roles))
+    throw new Error(`${path}: "roles" must be tables — [roles.<name>] — not ${JSON.stringify(roles)}`);
+  for (const [name, r] of Object.entries(roles))
+    if (!isTable(r))
+      throw new Error(
+        `${path}: roles.${name} = ${JSON.stringify(r)} — a role is a table, [roles.${name}], ` +
+        `with its settings under it.`);
 
   /**
    * A role is a leaf. `[roles.a.b]` is a typo, with certainty.
@@ -295,6 +335,19 @@ export function loadConfig(path) {
   }
   const names = Object.keys(roles);
   if (names.length === 0) throw new Error(`${path}: no [roles.<name>] sections found`);
+  // Case-colliding names would share a HOME under `isolate = "home"` on a
+  // case-insensitive disk (APFS), so `dev` and `Dev` would read each other's
+  // secrets while `check` said nothing. Refuse the ambiguity at load.
+  {
+    const byLower = new Map();
+    for (const n of names) {
+      const k = n.toLowerCase();
+      if (byLower.has(k))
+        throw new Error(`${path}: roles "${byLower.get(k)}" and "${n}" differ only in case. ` +
+          `On a case-insensitive disk they would share an isolated HOME. Rename one.`);
+      byLower.set(k, n);
+    }
+  }
 
   // One directory or several. Several is the common case once a repo has more
   // than one kind of secret, and making people flatten them to satisfy the tool
@@ -323,7 +376,7 @@ export function loadConfig(path) {
 
   for (const name of names) {
     const r = own(roles, name);
-    const writes = asArray(own(r, "writes"), `roles.${name}.writes`);
+    const writes = assertNotAbsolute(asArray(own(r, "writes"), `${path}: roles.${name}.writes`), `${path}: roles.${name}.writes`);
     const keys = asArray(own(r, "keys"), `roles.${name}.keys`);
     // Read once, here, so every consumer sees the same answer about what an
     // entry is. `keys` itself stays the array of strings that was written: it
@@ -614,6 +667,25 @@ function readNeverWrites(value, where) {
   return list;
 }
 
+/**
+ * A territory is relative to the repo root. An absolute one would ask the kernel
+ * for a path on the machine and make `explain` (which reads absolute as outside
+ * the repo) disagree with what the profile grants — see the CODEOWNERS `/apps/`
+ * case. `..` is allowed on purpose: a role legitimately writes a sibling
+ * directory (`../bitacora/...`), and it is resolved relative to the root, so a
+ * territory that climbs above it grants what it resolves to, by the operator's
+ * choice.
+ */
+function assertNotAbsolute(list, where) {
+  for (const g of list) {
+    if (typeof g !== "string" || g.trim() === "")
+      throw new Error(`${where}: every entry must be a non-empty string`);
+    if (g.startsWith("/"))
+      throw new Error(`${where}: "${g}" is absolute. Territories are relative to the repo root.`);
+  }
+  return list;
+}
+
 function asArray(value, where) {
   if (value === undefined) return [];
   if (typeof value === "string") return [value];

package/src/hook.js

@@ -38,12 +38,41 @@ const FILE_TOOLS = {
 const REDIRECT = /(?:^|\s|;|&&|\|\|)>{1,2}\s*("[^"]+"|'[^']+'|[^\s;|&<>]+)/g;
 const WRITERS = /(?:^|\s|;|&&|\|\|)(?:cp|mv|install|tee|touch|mkdir|rm|rmdir|truncate|dd)\s+([^\n;|&]+)/g;
 
+/**
+ * The server in an `mcp__<server>__<tool>` name, or null if it does not parse.
+ *
+ * The split is on the double underscore: a server name carries single ones
+ * (`claude_ai_Gmail`) and so does a tool name (`execute_sql`), so the server is
+ * everything between `mcp__` and the next `__`. Shared with the parent's intake,
+ * which recomputes the same verdict rather than trusting the line from the box.
+ */
+export function mcpServer(tool) {
+  const m = typeof tool === "string" && /^mcp__(.+?)__(.+)$/.exec(tool);
+  return m ? m[1] : null;
+}
+
 export function targetsOf(tool, input = {}) {
   const kind = FILE_TOOLS[tool];
   if (kind) {
     const p = input.file_path ?? input.path ?? input.notebook_path;
     return p ? [{ action: kind, path: p }] : [];
   }
+  /**
+   * An MCP tool call names a resource, not a path: `mcp__<server>__<tool>`.
+   *
+   * The kernel never sees it — the MCP server runs outside the box — so a call
+   * that goes unrecorded here goes unrecorded everywhere. Measured 2026-09-24:
+   * the event reaches PreToolUse with the tool's own arguments as `tool_input`,
+   * which is exactly why the file-tool code above returns nothing for it. We
+   * resolve the call to the *server* it belongs to, the unit the policy already
+   * declares in `mcp = [...]`, and leave the finer resource (which table, which
+   * project) for later — deriving it means a per-server adapter, and that is the
+   * line past which this stops being "whose is it" and becomes a tool gateway.
+   * A name that does not parse is returned as an unknown tool, not dropped.
+   */
+  if (typeof tool === "string" && tool.startsWith("mcp__")) {
+    return [{ action: "use", tool, server: mcpServer(tool) }];
+  }
   if (tool !== "Bash" || typeof input.command !== "string") return [];
 
   const out = [];
@@ -140,6 +169,25 @@ export function decide(config, role, event, { observe = false, now = append, ask
   const verdicts = [];
 
   for (const t of targets) {
+    // A tool call, resolved to its MCP server. "Whose is it" is the question
+    // `mcp = [...]` already answers, so it is asked through the same map rather
+    // than a second one. No request is filed on a denial: a server absent from
+    // a role's list is a policy subtraction a person edits — the shape of
+    // never_writes — not a grant a person approves, and filing one would be a
+    // request nobody can grant. An unparsable name is closed, not waved through.
+    if (t.action === "use") {
+      const v = t.server
+        ? explain(config, role, "mcp", t.server)
+        : { allowed: false, owners: [], mcp: true, reason: `${t.tool} is not a recognisable mcp__<server>__<tool> name` };
+      now(file, {
+        role, tool: event.tool_name, action: "use", kind: "tool", target: t.tool,
+        verdict: observe ? "observed" : v.allowed ? "allowed" : "denied",
+        owners: v.owners ?? [], reason: v.reason,
+      });
+      verdicts.push({ ...v, target: t.tool, kind: "tool", action: "use" });
+      continue;
+    }
+
     const rel = toRepoRelative(config, t.path);
     const kind = kindOf(config, rel);
 
@@ -225,6 +273,8 @@ export function decide(config, role, event, { observe = false, now = append, ask
           ? `${denied.reason}. Do not ask for it: nothing was queued, because the answer is already written down.` + again
           : denied.gitMetadata
           ? `${denied.reason}. Nothing was queued.` + again
+          : denied.mcp
+          ? `${denied.reason}. Nothing was queued: which MCP servers a role may load is set in its mcp list, a policy change a person makes, not a grant they approve.` + again
           : (denied.owners?.length
           ? wasRead
             ? `${denied.target} is declared for ${denied.owners.join(", ")}, not ${role}. Ask for what you need from it rather than reading the key.`

package/src/intake.js

@@ -30,6 +30,7 @@ import { explain, ownersOf } from "./owners.js";
 import { append, logPath } from "./log.js";
 import { record, requestsPath } from "./requests.js";
 import { inScope, scopeOf, reachedForContent } from "./violations.js";
+import { mcpServer } from "./hook.js";
 
 /** A hash of the policy file as it is now, short: it names a version, it proves nothing. */
 export function policyId(config) {
@@ -73,6 +74,33 @@ export function intake({ config, role, runId, observe = false, settings, notify
    */
   function fromHook(to, entry) {
     if (!entry || typeof entry !== "object") return;
+
+    /**
+     * An MCP tool call. It names a resource, not a path, so it is recorded and
+     * never queued — which servers a role may load is a change to its `mcp`
+     * list, not a grant a person approves, the same shape as never_writes. The
+     * verdict is recomputed here from the same list rather than believed from
+     * inside the box: the server is parsed from the tool name and asked of the
+     * policy, so a line claiming "allowed" for a server the role may not load
+     * comes back marked `disputed`.
+     */
+    if (to === "log" && entry.action === "use") {
+      if (typeof entry.target !== "string" || !entry.target.trim()) return;
+      if (!["allowed", "denied", "observed"].includes(entry.verdict)) return;
+      const server = mcpServer(entry.target);
+      const v = server ? explain(config, role, "mcp", server) : { allowed: false };
+      const expected = observe ? "observed" : v.allowed ? "allowed" : "denied";
+      return void log({
+        at: entry.at, role,
+        tool: String(entry.tool ?? "").slice(0, 40),
+        action: "use", kind: "tool",
+        target: entry.target.slice(0, 1000),
+        verdict: entry.verdict, owners: [],
+        reason: String(entry.reason ?? "").slice(0, 500),
+        ...(expected !== entry.verdict ? { disputed: expected } : {}),
+      });
+    }
+
     if (entry.action !== "read" && entry.action !== "write") return;
     if (typeof entry.target !== "string" || !entry.target.trim()) return;
 
@@ -133,7 +161,10 @@ export function intake({ config, role, runId, observe = false, settings, notify
     // The owners explain found: for a key that is who declares it, not who
     // writes the directory it sits in — the queue said "owned by dev" about
     // backend's key because dev writes `**`.
-    ask({ role, action: entry.action, target: entry.target, owners: v.owners });
+    // Capped like the log line above: a request's target is a path, and an
+    // uncapped one (5k+ chars were accepted) is a way to bloat the queue a
+    // person reads. 1000 is more than any real path and matches the log.
+    ask({ role, action: entry.action, target: entry.target.slice(0, 1000), owners: v.owners });
   }
 
   function fromKernel(d) {