seisin 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seisin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A permission layer for AI coding agents: role-scoped folders and keys, enforced by the OS, and when it denies something it tells you whose file it was.",
   "keywords": [
     "ai-agents",
@@ -13,7 +13,10 @@
     "codeowners",
     "rbac",
     "agent-permissions",
-    "code-ownership"
+    "code-ownership",
+    "mcp",
+    "security",
+    "developer-tools"
   ],
   "license": "MIT",
   "author": "Carlos Tapia",
@@ -31,7 +34,7 @@
   },
   "files": [
     "src",
-    "ui",
+    "ui/index.html",
     "README.md",
     "LICENSE"
   ],
@@ -39,15 +42,20 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "0.0.78"
+    "@anthropic-ai/sandbox-runtime": "0.0.81"
   },
   "scripts": {
     "test": "node --test test/*.test.js",
+    "build:ui": "node ui/build.js",
     "prepublishOnly": "npm test"
   },
   "main": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
     "./package.json": "./package.json"
   }
 }

package/src/browsers.js

@@ -0,0 +1,52 @@
+/**
+ * `browsers = ["chromium"]`: what a headless browser needs from the sandbox
+ * beyond files and the network, per role and only when the role says so.
+ *
+ * Measured on macOS with Playwright's Chromium headless shell (build 1208), as
+ * the kernel saw it under the default profile:
+ *
+ *   - the browser process starts by registering a Mach service named
+ *     `org.chromium.Chromium.MachPortRendezvousServer.<its pid>`, and dies at
+ *     once when that is refused (`bootstrap_check_in ... Permission denied
+ *     (1100)`, FATAL in base/apple/mach_port_rendezvous_mac.cc);
+ *   - every child it starts (GPU, network, renderer) then looks that same
+ *     service up to receive its ports, and loops forever when the lookup is
+ *     refused: over a thousand refusals in forty seconds, no page.
+ *
+ * Those two, with that one prefix, are all it took: with them the browser
+ * started, rendered and navigated through seisin's proxy, and the other Mach
+ * services it reached for (configd, the window server, analytics) stayed
+ * refused without stopping it. So that is all a preset grants. Never a bare
+ * `mach-register`: a name is registered in the bootstrap namespace other
+ * processes look names up in, and an open grant would let the role stand up a
+ * service under any name.
+ *
+ * The prefix is the browser's bundle id, which is why the preset is named for
+ * the build. Chrome and Chrome for Testing use their own (`com.google.Chrome`,
+ * `com.google.chrome.for.testing`) and also need a unix socket for their
+ * process singleton, measured and not granted here: they are not presets yet.
+ */
+export const BROWSERS = {
+  chromium: {
+    // The browser registers it; its children look it up.
+    register: ["org.chromium.Chromium.MachPortRendezvousServer."],
+    lookup: ["org.chromium.Chromium.MachPortRendezvousServer."],
+  },
+};
+
+/** A Mach name prefix as the profile may carry it: no quotes, no spaces, ends in a dot. */
+export const MACH_PREFIX = /^[A-Za-z0-9][A-Za-z0-9.-]*\.$/;
+
+/** The Mach names a role's browsers need registered and looked up, de-duplicated. */
+export function machOf(role) {
+  const names = (role?.browsers ?? []).map((b) => BROWSERS[b]).filter(Boolean);
+  return {
+    register: [...new Set(names.flatMap((b) => b.register))],
+    lookup: [...new Set(names.flatMap((b) => b.lookup))],
+  };
+}
+
+/** The preset whose register prefix this Mach name falls under, or null. */
+export function browserFor(name) {
+  return Object.keys(BROWSERS).find((b) => BROWSERS[b].register.some((p) => name.startsWith(p))) ?? null;
+}

package/src/canary.js

@@ -0,0 +1,149 @@
+/**
+ * The canary: before the agent starts, the policy is tried from inside.
+ *
+ * The settings are generated by software, and software breaks. A runtime
+ * upgrade, a path that turned out to be a symlink, an `isolate` level combined
+ * with something it was not measured with — any of them can leave a door open,
+ * and without this the first anyone hears of it is after something went
+ * through it. So every run starts with a short process under the SAME runtime,
+ * the SAME settings file and the SAME environment as the agent, and the agent
+ * starts only if every answer is the expected one.
+ *
+ * Judged by effect, never by exit code: a write "denied" is a file that is not
+ * there afterwards; a read "denied" is a nonce that never came out; a
+ * connection "refused" is a nonce the decoy never delivered. And each denial
+ * has a positive control beside it — the sandbox ran at all, and a place the
+ * role may write took the write — because a sandbox that runs nothing denies
+ * everything too.
+ *
+ * **Fails closed, including on a missing tool.** In an orchestrator we compared against, the network
+ * probe passed whenever `nc` was absent: no tool, no connection, "refused".
+ * Here a probe that cannot be made is a failed canary.
+ *
+ * **No flag skips it.** A flag becomes an alias, and the alias becomes the way
+ * every run starts. It costs one extra start of the runtime, a few tenths of a
+ * second, against a run that lasts minutes.
+ */
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { randomBytes } from "node:crypto";
+import { writeFileSync, readFileSync, rmSync, existsSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/** Where sandbox-runtime's shared temp directory is on this host. */
+const SHARED_TMP_DIR = "/tmp/claude";
+
+/** The exit code of a run the canary stopped: not the agent's, and not one a shell uses. */
+export const CANARY_EXIT = 86;
+
+const isDir = (p) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+
+/**
+ * Runs the canary and resolves to `{ ok, failed: [reasons], ms }`.
+ *
+ * `runDir` is this run's directory and `runsRoot` the one above it; the
+ * secret is planted in the second, which the settings deny to every run but
+ * the run's own directory. `role.localBinding` skips the network probe and
+ * says so: that role was granted every localhost port on purpose.
+ */
+export async function runCanary({ srt, wrap = null, settingsFile, settings, env, cwd, runDir, runsRoot, role, granted, timeoutMs = 20_000 }) {
+  // How the probe is started: under the run's sandbox, exactly as the agent
+  // will be (sandboxes/). `srt` alone is the runtime's own command line, kept
+  // for callers from before there was more than one sandbox.
+  const boxed = wrap ?? ((inner) => [srt, "--settings", settingsFile, "--", ...inner]);
+  const t0 = Date.now();
+  const nonce = randomBytes(8).toString("hex");
+  const failed = [];
+
+  const secret = join(runsRoot, `canary-${nonce}.secret`);
+  const outside = join(runDir, `canary-${nonce}.out`);
+  // The first directory the POLICY grants that exists — taken from the
+  // policy and not from the settings, so settings that lost the grant fail
+  // here instead of skipping the check. Absent (a role with nothing to
+  // write), the write control is skipped and "the sandbox ran" stands alone.
+  // Outside the repo first (the runtime's scratch, the role's home): a file
+  // appearing and vanishing in a watched tree restarts a dev server.
+  const candidates = (granted ?? settings.filesystem.allowWrite ?? []).filter((p) => isDir(p));
+  const writable = candidates.find((p) => !(cwd && (p === cwd || p.startsWith(cwd + "/") || cwd.startsWith(p + "/")))) ?? candidates[0];
+  const inside = writable ? join(writable, `.seisin-canary-${nonce}`) : null;
+  // The runtime's shared temp directory (srt.js, SHARED_TMP): granted by the
+  // runtime to every sandbox, taken back by seisin. Probed where it exists;
+  // where it does not, there is nothing beside which to write.
+  const shared = isDir(SHARED_TMP_DIR) ? join(SHARED_TMP_DIR, `.seisin-canary-${nonce}`) : null;
+  const policy = settingsFile;
+
+  writeFileSync(secret, `SECRET-${nonce}\n`, { mode: 0o600 });
+
+  let server = null;
+  let port = null;
+  if (!role.localBinding) {
+    server = createServer((s) => s.end(`HTTP/1.0 200 OK\r\nContent-Type: text/plain\r\n\r\nNET-${nonce}\n`));
+    await new Promise((res, rej) => server.listen(0, "127.0.0.1", res).on("error", rej));
+    port = server.address().port;
+  }
+
+  const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+  const script = [
+    `echo ALIVE-${nonce}`,
+    `(echo x > ${q(outside)}) 2>/dev/null`,
+    `cat ${q(secret)} 2>/dev/null`,
+    `cat ${q(policy)} >/dev/null 2>&1 && echo POLICY-READ-${nonce}`,
+    inside ? `(echo IN-${nonce} > ${q(inside)}) 2>/dev/null` : ":",
+    shared ? `(echo x > ${q(shared)}) 2>/dev/null` : ":",
+    // curl when there is one; otherwise the node seisin itself runs on, which
+    // every machine with seisin has — a slim image without curl would
+    // otherwise never start anything. Neither: a failed canary, not a pass.
+    port ? `if command -v curl >/dev/null 2>&1; then curl -s -m 3 -w PROBED-${nonce} http://127.0.0.1:${port}/ 2>/dev/null; ` +
+      `elif [ -x ${q(process.execPath)} ]; then ${q(process.execPath)} -e ${q(`process.stdout.write("PROBED-${nonce}");const s=require("net").connect(${port},"127.0.0.1");s.on("data",d=>process.stdout.write(d));s.on("error",()=>{});setTimeout(()=>process.exit(0),3000)`)} 2>/dev/null; ` +
+      `else echo NO-PROBE-${nonce}; fi` : ":",
+  ].join("; ");
+
+  let output = "";
+  let stderr = "";
+  let timedOut = false;
+  try {
+    const status = await new Promise((resolve) => {
+      const [file, ...args] = boxed(["/bin/sh", "-c", script]);
+      const child = spawn(file, args, {
+        cwd, env, stdio: ["ignore", "pipe", "pipe"],
+      });
+      const timer = setTimeout(() => { timedOut = true; try { child.kill("SIGKILL"); } catch {} }, timeoutMs);
+      child.stdout.on("data", (d) => { output += d; });
+      child.stderr.on("data", (d) => { stderr = (stderr + d).slice(-2000); });
+      child.on("error", () => { clearTimeout(timer); resolve(null); });
+      child.on("close", (code) => { clearTimeout(timer); resolve(code); });
+    });
+    void status;
+  } finally {
+    server?.close();
+  }
+
+  if (timedOut) failed.push(`the canary did not finish in ${timeoutMs / 1000}s`);
+  if (!output.includes(`ALIVE-${nonce}`)) {
+    // The runtime's own words, when it said any: a sandbox that refuses to
+    // start usually says why (measured: a path the runtime read as a broken
+    // glob), and without this the reason was thrown away with the stream.
+    const said = stderr.trim().split("\n").filter(Boolean).slice(-3).join(" / ");
+    failed.push(`the sandbox did not run the canary at all${said ? ` — the runtime said: ${said}` : ""}`);
+  }
+  if (existsSync(outside)) failed.push(`a write outside the territory went through (${outside})`);
+  if (shared && existsSync(shared)) failed.push(`a write into the runtime's shared temp directory went through (${shared})`);
+  if (output.includes(`SECRET-${nonce}`)) failed.push(`a planted secret was readable (${secret})`);
+  if (output.includes(`POLICY-READ-${nonce}`)) failed.push(`the run's own settings were readable (${policy})`);
+  if (inside) {
+    let wrote = false;
+    try { wrote = readFileSync(inside, "utf8").trim() === `IN-${nonce}`; } catch {}
+    if (!wrote) failed.push(`a write the role is granted did not go through (${dirname(inside)}) — the positive control`);
+  }
+  if (port) {
+    // The probe has to say it ran. Silence is not "unreachable": a node the
+    // sandbox will not execute prints nothing, and nothing would read as a pass.
+    if (!output.includes(`PROBED-${nonce}`) && !output.includes(`NO-PROBE-${nonce}`))
+      failed.push("the network probe did not run — a probe that cannot be made is not a pass");
+    if (output.includes(`NO-PROBE-${nonce}`)) failed.push("neither curl nor node can run inside the sandbox to probe the network with — a probe that cannot be made is not a pass");
+    if (output.includes(`NET-${nonce}`)) failed.push(`a loopback port outside the policy was reachable (127.0.0.1:${port})`);
+  }
+
+  for (const p of [secret, outside, inside, shared]) if (p) try { rmSync(p, { force: true }); } catch {}
+  return { ok: failed.length === 0, failed, ms: Date.now() - t0 };
+}

package/src/cli.js

@@ -19,7 +19,7 @@ import { fileURLToPath } from "node:url";
 import { findConfig, loadConfig } from "./config.js";
 import { CONFIG_NAME } from "./layout.js";
 import { C, out, err } from "./render.js";
-import { COMMAND_HELP, flagsOf, renderHelp } from "./help.js";
+import { COMMAND_HELP, flagsOf, renderHelp, renderLimits } from "./help.js";
 import { nearest, checkFlags } from "./suggest.js";
 
 /**
@@ -41,11 +41,11 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
 
   seisin run <role> -- <command...>     run a command as that role
   seisin run <role> --observe -- <cmd>  open the repo and watch — the network stays shut
-  seisin check [role] [--verbose]       print the map, run nothing
+  seisin check [role] [--verbose] [--verify] [--parallel] [--system-log]  --parallel is experimental; --system-log measures log loss (macOS)
   seisin explain <role> read|write|mcp <path, key or server>
   seisin whose <path>                   who owns it — safe to call from inside the sandbox
   seisin scan [--all]                   find secrets outside the declared key dirs
-  seisin review [--all]                 what the log says about the policy
+  seisin review [--all] [--since 7d]    what the log says about the policy
   seisin walls <role> [--all]           what that role keeps being denied, and what it cost
   seisin wire                           let the agent record what it does
   seisin requests                       what the agents asked for and cannot have
@@ -60,6 +60,7 @@ ${C.b}seisin${C.off} — give each agent its own folders and its own keys
   seisin mcp                            an MCP server on stdio — read-only
 
 seisin <command> --help lists a command's flags, examples and exit codes.
+seisin help limits says what seisin cannot do, in any repo.
 
 Enforcement comes from @anthropic-ai/sandbox-runtime, which asks the OS.
 seisin decides what to ask for, and says whose file it was when the answer is no.
@@ -90,7 +91,10 @@ const COMMANDS = {
   // composes in a pre-commit hook or CI the way `explain` and `scan` already do.
   // Warnings about a config that WILL work still exit 0 — failing on those
   // would make the command unusable within a week.
-  check: async () => ((await import("./commands/check.js")).check(config(), argv).warnings.some((w) => w.kind === "cannot-be-enforced") ? 1 : 0),
+  check: async () => {
+    const report = await (await import("./commands/check.js")).check(config(), argv);
+    return (await import("./commands/check.js")).checkStatus(report);
+  },
   explain: async () => ((await import("./commands/explain.js")).explainCommand(config(), argv).allowed ? 0 : 1),
   scan: async () => ((await import("./commands/scan.js")).scanCommand(config(), argv).certain.length ? 1 : 0),
   log: async () => void (await import("./commands/log.js")).log(config(), argv),
@@ -105,20 +109,16 @@ const COMMANDS = {
   whose: async () => void (await import("./commands/whose.js")).whose(config(), argv),
   wire: async () => void (await import("./commands/wire.js")).wire(config()),
   review: async () => ((await import("./commands/review.js")).reviewCommand(config(), argv).friction.length ? 1 : 0),
-  walls: async () => ((await import("./commands/walls.js")).wallsCommand(config(), argv).length ? 1 : 0),
-  requests: async () => ((await import("./commands/requests.js")).requests(config()).length ? 1 : 0),
+  walls: async () => ((await import("./commands/walls.js")).wallsCommand(config(), argv).some((w) => !w.expected) ? 1 : 0),
+  requests: async () => ((await import("./commands/requests.js")).requests(config(), argv).length ? 1 : 0),
   grant: async () => void (await import("./commands/requests.js")).grant(config(), argv),
   /**
    * A person DECLINES a request; the boundary DENIES a write. One word each,
-   * because they are opposite events and `deny` used to name both — a queue
+   * because they are opposite events and one word used to name both — a queue
    * entry said `first refused on …` (the kernel) and the answer said
-   * `refused frontend ✕ …` (you).
-   *
-   * `deny` stays and is not documented. Renaming a published command over a
-   * word is not worth breaking somebody's script; teaching the new one is.
+   * `refused frontend ✕ …` (you). The old command is gone (see RETIRED).
    */
-  decline: async () => void (await import("./commands/requests.js")).deny(config(), argv),
-  deny: async () => void (await import("./commands/requests.js")).deny(config(), argv),
+  decline: async () => void (await import("./commands/requests.js")).decline(config(), argv),
   mcp: async () => {
     await (await import("./mcp.js")).serveMcp(version());
     return 0;
@@ -129,7 +129,12 @@ const COMMANDS = {
   hook: async () => {
     try {
       const decision = await (await import("./commands/hook.js")).hook();
-      if (decision?.hookSpecificOutput) out(JSON.stringify(decision) + "\n");
+      // Only what the hook protocol defines. `decision` and `logged` are for the
+      // callers inside seisin; Codex validates a hook's output against a schema
+      // that admits no other field (and `decision` only as approve|block), and
+      // drops the whole answer when it does not fit — measured 2026-09-30 with
+      // codex 0.150.1: the deny was ignored and the command ran into the kernel.
+      if (decision?.hookSpecificOutput) out(JSON.stringify({ hookSpecificOutput: decision.hookSpecificOutput }) + "\n");
     } catch (e) {
       err(`seisin hook: ${e?.message ?? e} — no decision, the tool call goes ahead\n`);
     }
@@ -158,18 +163,17 @@ function version() {
  * (`--reason -h`) is a value.
  */
 const HELP = new Set(["--help", "-h"]);
-const TAKES_VALUE = new Set(["--port", "--role", "--verdict", "--limit", "--min", "--since", "--reason"]);
-
 function asksHelp(name, args) {
+  const takesValue = new Set(flagsOf(name)?.values ?? []);
   const split = args.indexOf("--");
   let ours = split === -1 ? args : args.slice(0, split);
   if (name === "run" && split === -1) {
     let i = 1;
-    while (i < args.length && args[i].startsWith("-")) i++;
+    while (i < args.length && args[i].startsWith("-")) i += takesValue.has(args[i]) ? 2 : 1;
     ours = args.slice(0, i);
   }
   for (let i = 0; i < ours.length; i++) {
-    if (TAKES_VALUE.has(ours[i])) i++;
+    if (takesValue.has(ours[i])) i++;
     else if (HELP.has(ours[i])) return true;
   }
   return false;
@@ -178,24 +182,42 @@ function asksHelp(name, args) {
 /** One command's help: its flags, examples and exit codes, or the whole usage. */
 function helpFor(name) {
   if (COMMAND_HELP[name]) return renderHelp(name, C);
-  const alias = name === "deny" ? "decline" : name;
-  const lines = USAGE.split("\n").filter((l) => l.startsWith(`  seisin ${alias} `) || l === `  seisin ${alias}`);
+  const lines = USAGE.split("\n").filter((l) => l.startsWith(`  seisin ${name} `) || l === `  seisin ${name}`);
   if (!lines.length) return USAGE;
   return `\nusage:\n${lines.join("\n")}\n\n  ${C.dim}seisin --help for every command${C.off}\n\n`;
 }
 
+// The standing limits: the same for every repo, so they are help, not `check`.
+if (command === "help" && argv[0] === "limits") {
+  out(renderLimits(C));
+  process.exit(0);
+}
 if (command === undefined || command === "help" || HELP.has(command)) {
   const about = command === "help" && COMMANDS[argv[0]] && !argv[0].startsWith("-") ? argv[0] : null;
   out(about ? helpFor(about) : USAGE);
   process.exit(0);
 }
 
+/**
+ * Commands that were renamed, and what to type now. Not aliases: the old name
+ * runs nothing, so a script that calls it stops and says what changed rather
+ * than doing the right thing under the wrong word for ever.
+ */
+const RETIRED = {
+  deny: `"seisin deny" was removed in 0.6.0: a person declines, the boundary denies.\n` +
+    `  Use seisin decline <n|id> [--reason "…"] — same arguments, same effect.`,
+};
+
 const chosen = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : null;
+if (!chosen && Object.hasOwn(RETIRED, command)) {
+  err(`${C.red}seisin:${C.off} ${RETIRED[command]}\n`);
+  process.exit(2);
+}
 if (!chosen) {
   // One line, and the nearest command. The whole usage, printed for a typo,
   // pushed the one line that mattered off the screen.
   const near = command.startsWith("-") ? nearest(command, ["--help", "--version"])
-    : nearest(command, Object.keys(COMMANDS).filter((c) => !c.startsWith("-") && c !== "deny"));
+    : nearest(command, Object.keys(COMMANDS).filter((c) => !c.startsWith("-")));
   err(`${C.red}seisin:${C.off} unknown ${command.startsWith("-") ? "option" : "command"} "${command}"` +
     `${near ? ` — did you mean "${near}"?` : ""}\n  seisin --help lists every command\n`);
   process.exit(2);
@@ -230,9 +252,11 @@ function refuseUnknownFlags(name, args) {
     if (split !== -1) ours = args.slice(1, split);
     else {
       let i = 1;
-      while (i < args.length && args[i].startsWith("-")) i++;
+      // Every flag that takes a value, from the one table: listing them here by
+      // hand left `--handoff` out, so its id was checked as a flag of its own.
+      while (i < args.length && args[i].startsWith("-")) i += f.values.includes(args[i]) ? 2 : 1;
       ours = args.slice(1, i);
     }
   }
-  checkFlags(name === "deny" ? "decline" : name, ours, f.known, f.values);
+  checkFlags(name, ours, f.known, f.values);
 }

package/src/commands/check.js

@@ -1,10 +1,161 @@
-/** `seisin check` — print the map and every way it does not hold. Runs nothing. */
+/** `seisin check` — print the map and every way it does not hold. Runs nothing, unless `--verify`. */
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { inspect } from "../inspect.js";
-import { renderReport, out } from "../render.js";
+import { renderReport, out, C } from "../render.js";
+import { measureSystemLog } from "../violations.js";
+import { join } from "node:path";
+import { settingsFor } from "../srt.js";
+import { weigh } from "../sandboxes/index.js";
+import { runsRoot } from "../rundir.js";
+import { channelName } from "../spool.js";
 
-export function check(config, argv = []) {
+export async function check(config, argv = []) {
+  if (argv.includes("--parallel") && !argv.includes("--verify"))
+    throw new Error("--parallel is experimental and requires --verify");
   const role = argv.find((a) => !a.startsWith("-")) ?? null;
   const report = inspect(config, role, config.path);
   out(renderReport(report, { verbose: argv.includes("--verbose") }));
+  if (config.sandbox?.provider) report.sandboxes = sandboxes(config, role);
+  if (argv.includes("--verify")) report.verify = await verify(config, role, argv.includes("--parallel"));
+  if (argv.includes("--system-log")) report.systemLog = await systemLog();
   return report;
 }
+
+/**
+ * `--system-log`: is the log a run reads denials from dropping messages now?
+ *
+ * A flooded unified log loses lines before they are filtered, and a kernel
+ * denial lost there files nothing: the run says so afterwards, and this says
+ * it before, with who is writing the most — the only lead to a fix. A flag,
+ * because it takes seconds and `check` otherwise answers at once.
+ */
+async function systemLog() {
+  const m = await measureSystemLog({ seconds: SYSTEM_LOG_SECONDS });
+  if (!m.available) {
+    out(`\n${C.dim}system log: not measured — ${m.reason}${C.off}\n`);
+    return m;
+  }
+  const top = m.top.map((t) => `${t.who} ${t.perSecond}/s`).join(", ");
+  out(m.dropped
+    ? `\n${C.yellow}⚠ system log: ${m.dropped} batch(es) of messages dropped in ${m.seconds} s — kernel denials can go unrecorded now.${C.off}\n` +
+      `  ${m.perSecond} messages/s; most from ${top}. Stop or quiet the busiest writer, then measure again.\n`
+    : `\n${C.green}✓${C.off} system log: nothing dropped in ${m.seconds} s (${m.perSecond} messages/s; most from ${top})\n`);
+  return m;
+}
+
+const SYSTEM_LOG_SECONDS = 3;
+
+/**
+ * `[sandbox] provider`: which sandbox each role would get, and why the others not.
+ *
+ * Said before anything starts, because the alternative is finding out at
+ * `seisin run` that a role cannot be held by the sandbox the config asked for.
+ * The settings are the ones a run would build, down to a channel in the runs
+ * root, so a sandbox that cannot re-open this run's directory is caught here
+ * too. Printed only when `[sandbox] provider` is set: without it every role
+ * runs under srt, as it always has, and there is nothing to choose.
+ */
+export function sandboxes(config, only = null, { platform = process.platform } = {}) {
+  const sock = join(runsRoot(), "check", channelName(platform));
+  const rows = [];
+  out(`\n${C.b}sandboxes${C.off} (${config.sandbox.provider.join(" → ")})\n`);
+  for (const r of Object.values(config.roles)) {
+    if (only && r.name !== only) continue;
+    let settings;
+    try { settings = settingsFor(config, r.name, sock); } catch (e) { rows.push({ role: r.name, chosen: null, error: e.message }); continue; }
+    const { chosen, options } = weigh(config, settings, { platform, role: r.name });
+    rows.push({ role: r.name, chosen: chosen?.sandbox.name ?? null,
+      options: options.map((o) => ({ name: o.sandbox.name, missing: o.missing, unmet: o.unmet, warnings: o.warnings })) });
+    out(chosen ? `  ${C.green}✓${C.off} ${r.name}: ${chosen.sandbox.name}\n` : `  ${C.red}✗${C.off} ${r.name}: no sandbox can hold it\n`);
+    // Held, but not the way the role may expect: the sandbox's own words.
+    for (const w of chosen?.warnings ?? []) out(`      ${C.yellow}⚠ ${chosen.sandbox.name}: ${w}${C.off}\n`);
+    // Recorded nowhere otherwise: a run under it would still be held, and say nothing of what it refused.
+    if (chosen && !chosen.sandbox.tagsDenials && platform === "darwin")
+      out(`      ${C.yellow}⚠ ${chosen.sandbox.name} does not tag its denials, so none of the kernel's denials under it are recorded${C.off}\n`);
+    for (const o of options) {
+      if (o === chosen) break;
+      if (o.missing) out(`      ${o.sandbox.name}: ${o.missing}\n`);
+      else for (const u of o.unmet) out(`      ${o.sandbox.name}: ${u}\n`);
+    }
+  }
+  return rows;
+}
+
+/**
+ * The exit status: 1 when a role cannot be enforced as written, or when what a
+ * flag asked for failed. `--system-log` is asked for like `--verify` and fails
+ * the same way — a log dropping messages now is a run that would lose denials
+ * now, and a CI step has only the status to go on.
+ */
+export function checkStatus(report) {
+  return report.warnings.some((w) => w.kind === "cannot-be-enforced") || report.verify?.some((v) => !v.ok) ||
+    report.sandboxes?.some((s) => !s.chosen) ||
+    report.systemLog?.dropped > 0 ? 1 : 0;
+}
+
+/**
+ * `--verify`: each role's `verify` command, run inside that role's sandbox.
+ *
+ * Through `seisin run` itself and not a copy of its setup, so what passes here
+ * is what the agent will get: the same settings, environment and PATH. With
+ * `--agent none`, because the question is the toolchain, not the agent's home.
+ * In the repo root, where a test command expects to start.
+ *
+ * The one thing `check` executes, which is why it is a flag: without it
+ * `check` still runs nothing.
+ */
+async function verify(config, only, parallel = false) {
+  const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+  const roles = Object.values(config.roles).filter((r) => (only ? r.name === only : true) && r.verify);
+  const results = [];
+  if (!roles.length) out(`\n${C.yellow}verify: no role ${only ? `"${only}" ` : ""}declares a verify command${C.off}\n`);
+  const run = async (r) => {
+    const res = parallel
+      ? await runParallel(process.execPath, [cli, "run", r.name, "--agent", "none", "--", ...r.verify], config.root)
+      : spawnSync(process.execPath, [cli, "run", r.name, "--agent", "none", "--", ...r.verify], {
+        cwd: config.root, encoding: "utf8", timeout: 300_000, env: process.env,
+      });
+    const ok = res.status === 0;
+    const result = { role: r.name, ok, status: res.status };
+    const output = `${res.stderr ?? ""}${res.stdout ?? ""}`.trim().split("\n");
+    const tail = output.slice(-20).join("\n    ");
+    const denied = output.filter((line) => /denied|Operation not permitted|Permission denied|not readable/i.test(line));
+    const suggestion = denied.some((line) => (r.reads ?? []).some((p) => line.includes(p)))
+      ? "The command reached a declared reads path; check that the entry names the needed subtree and exists."
+      : `If the missing path is data, add the narrow path to reads; if it is an interpreter, runtime or library, add its stack to toolchain${r.toolchain?.length ? ` (currently ${r.toolchain.join(", ")})` : ""}.`;
+    out(`\n${ok ? C.green + "✓" : C.red + "✗"} verify ${r.name}${C.off}: ${r.verify.join(" ")}` +
+      (ok ? "\n" : ` — exit ${res.status ?? res.signal}\n    ${tail}\n` +
+        `  This role cannot run its own checks inside its sandbox. ${suggestion}\n`));
+    return result;
+  };
+  if (parallel) {
+    out(`\n${C.yellow}experimental: verify commands are running concurrently; shared builds, caches, ports, or generated files may race. Use plain --verify for serial checks.${C.off}\n`);
+    results.push(...await Promise.all(roles.map(run)));
+  } else {
+    for (const r of roles) results.push(await run(r));
+  }
+  return results;
+}
+
+function runParallel(command, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, env: process.env });
+    let stdout = "", stderr = "", timedOut = false, forceTimer;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      forceTimer = setTimeout(() => child.kill("SIGKILL"), 2_000);
+    }, 300_000);
+    child.stdout.setEncoding("utf8").on("data", (s) => { stdout += s; });
+    child.stderr.setEncoding("utf8").on("data", (s) => { stderr += s; });
+    child.on("error", (error) => {
+      clearTimeout(timer); clearTimeout(forceTimer);
+      resolve({ status: null, signal: null, stdout, stderr: `${stderr}${error.message}\n` });
+    });
+    child.on("close", (status, signal) => {
+      clearTimeout(timer); clearTimeout(forceTimer);
+      resolve({ status: timedOut ? null : status, signal: timedOut ? "SIGTERM (timeout)" : signal, stdout, stderr });
+    });
+  });
+}

package/src/commands/explain.js

@@ -7,8 +7,7 @@
  */
 import { toRepoRelative, fromCwd } from "../paths.js";
 import { isAbsolute } from "node:path";
-import { explain, explainFileRead, readTarget } from "../owners.js";
-import { CREDENTIAL_HOMES, expand } from "../grants.js";
+import { explain, readTarget } from "../owners.js";
 import { unknownRole } from "../suggest.js";
 import { twinsOf, whereIs } from "../worktree.js";
 import { renderVerdict, C, out } from "../render.js";
@@ -33,9 +32,7 @@ export function explainCommand(config, argv = []) {
 
   if (verb === "read") {
     const asked = readTarget(config, target);
-    const verdict = asked.key
-      ? explain(config, role, "read", asked.target)
-      : explainFileRead(config, role, asked.target, CREDENTIAL_HOMES.map(expand));
+    const verdict = explain(config, role, "read", target, process.cwd());
     out(renderVerdict(role, verb, asked.target, verdict));
     return { ...verdict, worktree: [] };
   }

package/src/commands/hook.js

@@ -12,6 +12,7 @@ import { decide } from "../hook.js";
 import { afterTool, atSessionStart } from "../diagnose.js";
 import { logPath } from "../log.js";
 import { flush } from "../spool.js";
+import { chainFromEnv } from "../handoff.js";
 
 export async function hook(stdin = process.stdin, env = process.env) {
   const role = env.SEISIN_ROLE;
@@ -34,15 +35,18 @@ export async function hook(stdin = process.stdin, env = process.env) {
     return null;
   }
   if (!config.roles[role]) return null;
+  // Set by `seisin run --handoff`; it words the denial and decides nothing
+  // (handoff.js, CHAIN_ENV).
+  const chain = chainFromEnv(env);
 
   // One command for every event it is wired to, so `seisin wire` adds one name.
   // The after-the-fact and session-start halves only explain; neither decides.
   const event_ = event.hook_event_name;
   if (event_ === "PostToolUse" || event_ === "PostToolUseFailure") {
-    try { return await afterTool(config, role, event, { file: logPath(config.root) }); } catch { return null; }
+    try { return await afterTool(config, role, event, { file: logPath(config.root), chain }); } catch { return null; }
   }
   if (event_ === "SessionStart") {
-    try { return atSessionStart(config, role, event, { file: logPath(config.root) }); } catch { return null; }
+    try { return atSessionStart(config, role, event, { file: logPath(config.root), chain }); } catch { return null; }
   }
   // Caught like the two halves above, and for a sharper reason: PreToolUse is
   // the one event where a crash is not silent. cli.js turns a throw into exit
@@ -51,7 +55,7 @@ export async function hook(stdin = process.stdin, env = process.env) {
   // never to do. Said on stderr so the bug is still findable.
   let decision = null;
   try {
-    decision = decide(config, role, event, { observe: env.SEISIN_OBSERVE === "1" });
+    decision = decide(config, role, event, { observe: env.SEISIN_OBSERVE === "1", chain });
   } catch (e) {
     process.stderr.write(`seisin hook: ${e?.message ?? e} — no decision, the tool call goes ahead\n`);
   }