seisin 0.5.0 → 0.6.0

package/src/inspect/limits.js

@@ -0,0 +1,98 @@
+/**
+ * What the tool cannot do at all — as opposed to `warnings`, which are things
+ * wrong with *this* config.
+ *
+ * Kept apart on purpose. A limit printed as a warning reads as something a
+ * person could fix, and after the third run it reads as nothing at all.
+ *
+ * They used to close `check --verbose`, six paragraphs under every repo's
+ * findings, identical in each one — so the part of the output about *this*
+ * repo was the part nobody reached. `check` now names how many there are and
+ * where to read them: `seisin help limits` (help.js prints this list).
+ * `inspect()` still returns them, so the MCP hands them out with the map.
+ */
+export const LIMITS = [
+  ...(process.platform !== "darwin" ? [] : [{
+    kind: "kernel-denials-can-drop",
+    headline: "a flooded system log loses kernel denials before seisin reads them",
+    detail:
+      "the kernel's denials reach `seisin run` through `log stream`, and when something floods " +
+      "the unified log (thousands of lines a second) the stream drops messages before it filters " +
+      "them. The boundary holds; the denial files no request and is not in `seisin log`. A run that " +
+      "lost messages says so when it ends and logs `log-dropped`; `seisin check --system-log` " +
+      "measures it now and names who writes the most. The system's own copy (`log show`) does not " +
+      "help: it lacks the tag that ties a denial to its run.",
+  }]),
+  ...(process.platform === "darwin" ? [] : [{
+    kind: "kernel-denials-unreadable",
+    headline: "denials by the kernel are not recorded on this platform",
+    detail:
+      "on macOS `seisin run` reads them out of the system log, so a denial the hook never " +
+      "saw still lands in `seisin log` with its owner and still queues a request. There is no " +
+      "equivalent to read here — bubblewrap does not log denials, and the runtime's substitute " +
+      "is not reachable from outside it. The boundary holds exactly as well; what you lose is " +
+      "seeing it work. Run `seisin wire` so the hook records what it can. The ask is upstream: " +
+      "github.com/carlostapiacl/seisin/blob/main/docs/upstream/cli-violations.md",
+  }]),
+  {
+    kind: "keys-only-what-you-declared",
+    headline: "key isolation covers the directory you declared, and nothing else",
+    detail:
+      "a credential sitting in the repo outside [keys] dir is ordinary readable " +
+      "content to every role. Run `seisin scan` to find them — check does not, " +
+      "because reading the whole tree on every invocation is how a command stops " +
+      "being run.",
+  },
+  {
+    kind: "observe-cannot-see-the-network",
+    headline: "`--observe` opens the filesystem, never the network",
+    detail:
+      "so it cannot tell you which domains an agent needs. The runtime does record every " +
+      "denial the proxy makes — host, port and reason — but only a caller that embeds the " +
+      "library can read them; nothing reaches a caller that runs the binary, which is what " +
+      "seisin does. So for an agent whose endpoints are not published, the options are to " +
+      "find them another way or drop the network restriction for it. The ask is upstream: " +
+      "github.com/carlostapiacl/seisin/blob/main/docs/upstream/cli-violations.md",
+  },
+  ...(process.platform === "linux" ? [{
+    kind: "control-files-linux",
+    headline: "a project's hooks and settings are protected only where they already exist",
+    detail:
+      "bubblewrap denies a path by mounting over it, and for a path that is not there it would " +
+      "create it on your disk. So on Linux a role can still create a .git/hooks entry or a " +
+      ".claude/settings.json in a project of its territory that had none. On macOS the kernel " +
+      "denies creating them too.",
+  }] : []),
+  {
+    kind: "shared-scratch",
+    headline: "roles share ~/.cache, ~/.local/share and the temp dir unless isolate = \"home\"",
+    detail:
+      "programs installed there that are on your PATH are protected, and so are Claude Code's " +
+      "settings and plugins. Anything else a program outside the sandbox reads from those places — a " +
+      "cache it executes, a tool not on PATH — is writable by every role. isolate = \"home\" " +
+      "gives each role its own.",
+  },
+  {
+    kind: "agent-sign-in",
+    headline: "~/.claude goes only to runs of claude, ~/.codex only to runs of codex",
+    detail:
+      "seisin reads the agent off the command after `--`, and a run is denied the other " +
+      "agents' sign-in files (~/.codex/auth.json, ~/.claude/.credentials.json). What a run " +
+      "of an agent can still read is its own: Codex and every command Codex runs share one " +
+      "sandbox, so with a ChatGPT sign-in kept in ~/.codex/auth.json they can read those tokens. " +
+      "Codex keeps them in the keychain instead with cli_auth_credentials_store = \"keyring\" " +
+      "in its config. A wrapper script is not followed: `seisin run <role> --agent codex -- ./script` " +
+      "names it. The protected paths `seisin check --verbose` lists are for every agent at once, " +
+      "because a role can be run as any of them.",
+  },
+  {
+    kind: "unlink-uncovered",
+    headline: "a role can delete inside its own territory",
+    detail:
+      // The path that used to be here ships with the repo and not with the npm
+      // package, so for most readers it named a file they do not have.
+      "writes and deletes are one permission to the kernel, so `rm` inside a " +
+      "role's own folders succeeds. Closing it needs denyUnlink in the sandbox " +
+      "runtime: github.com/carlostapiacl/seisin#how-it-holds",
+  },
+];

package/src/inspect/machine.js

@@ -0,0 +1,107 @@
+import { resolve, delimiter, join } from "node:path";
+import { realOrSelf, runtimeWritesFor, toWritePath } from "../grants.js";
+import { realAncestor } from "../paths.js";
+import { wired, broadlyWired } from "../commands/wire.js";
+
+export function relativePathWarnings() {
+  const warnings = [];
+  // PATH entries that are not absolute resolve against wherever the parent is
+  // standing, which is the repo. They are ignored for every lookup seisin makes
+  // outside the sandbox; said here because a lookup that skips them can find a
+  // different program than your shell does.
+  const unanchored = (process.env.PATH ?? "").split(delimiter).filter((d) => !d || !d.startsWith("/"));
+  if (unanchored.length)
+    warnings.push({
+      kind: "relative-path",
+      headline: `PATH has ${unanchored.length} relative entr${unanchored.length === 1 ? "y" : "ies"} (${unanchored.map((d) => JSON.stringify(d)).join(", ")})`,
+      detail: "They resolve inside the repo, where roles write, so seisin skips them when it looks for a program to run outside the sandbox.",
+    });
+  return warnings;
+}
+
+export function scratchWarnings(config) {
+  const warnings = [];
+  // Scratch is granted to every role, so a repo sitting inside it is writable
+  // by all of them no matter what the territory says. Saying so is the
+  // difference between a limitation and a trap — and it is not hypothetical:
+  // the test fixture lived in the temp dir and made a boundary test pass for
+  // the wrong reason, and a role in a toy repo under /tmp wrote outside its
+  // `writes` with nothing on screen to say why.
+  // Both sides resolved, or the comparison is a coin flip. `expand()` follows
+  // symlinks — it has to, because on macOS /tmp is a link to /private/tmp and a
+  // grant written as /tmp grants nothing — so the root has to be followed too.
+  // Without this a repo at /tmp/x is never reported as sitting in scratch,
+  // which is the one case where the warning matters most.
+  //
+  // The scratch a role is really given, not the default list: `[runtime]
+  // writes` when the policy sets it, and none of it under `isolate = "home"`,
+  // where each role gets a home of its own instead (grants.js, writePathsOf).
+  const level = config.isolate === true ? "home" : config.isolate;
+  const scratch = level === "home" ? [] : runtimeWritesFor(config, undefined);
+  const under = (p) => scratch.find((s) => p === s || p.startsWith(s + "/"));
+  const fix = (s) => `Move it out of ${s}, or set [runtime] writes to a list that leaves ${s} out ` +
+    `(\`[runtime] writes = []\` gives no role any shared scratch).`;
+  const root = realOrSelf(resolve(config.root));
+  const around = under(root);
+  if (around) {
+    warnings.push({
+      kind: "scratch",
+      headline: `every role can write the whole repo: it lives inside ${around}, which every role gets as scratch`,
+      detail: "Territory does not hold here — a role's writes is no limit when the directory around the repo " +
+        `is granted to all of them. ${fix(around)}`,
+    });
+    return warnings;
+  }
+  /**
+   * The repo is outside scratch, and part of a territory still is: a `writes`
+   * entry that goes through a symlink (`out -> /tmp/out`) or up and out with
+   * `..`. The kernel enforces on the real path, so that part of the role's
+   * territory is every role's. Said per resolved path, once.
+   */
+  const seen = new Set();
+  for (const r of Object.values(config.roles)) {
+    for (const g of r.writes ?? []) {
+      let real;
+      try { real = realAncestor(join(config.root, toWritePath(g))); } catch { continue; }
+      const s = under(real);
+      if (!s || seen.has(real)) continue;
+      seen.add(real);
+      warnings.push({
+        kind: "territory-in-scratch",
+        headline: `every role can write ${r.name}'s ${g}: it resolves to ${real}, inside ${s}, which every role gets as scratch`,
+        detail: `That part of ${r.name}'s territory does not hold — the kernel enforces on the real path. ${fix(s)}`,
+      });
+    }
+  }
+  return warnings;
+}
+
+export function hookWarnings(config) {
+  const warnings = [];
+  if (!wired(config.root))
+    warnings.push({
+      kind: "hook-not-wired",
+      headline: "only denials are being recorded: the agent has not been told to run the hook",
+      detail:
+        process.platform === "darwin"
+          ? "the boundary holds either way, and denials are still logged and still queue a " +
+            "request — `seisin run` reads them from the kernel. What is missing is every " +
+            "action that was allowed, so `review` cannot tell you which grants are unused and " +
+            "`init --from-observations` has nothing to build from. Run `seisin wire` once in " +
+            "this repo."
+          : "the boundary holds either way — but on this platform the kernel's denials are " +
+            "not readable either, so log, watch, requests, grant and review all read a record " +
+            "that nobody is writing. Run `seisin wire` once in this repo.",
+    });
+
+  else if (broadlyWired(config.root))
+    warnings.push({
+      kind: "hook-matcher-broad",
+      headline: "the hook runs on every tool call: it was wired before 0.5.0 with the matcher \"*\"",
+      detail:
+        "nothing is lost — every tool the hook reads is still covered — but each Read, Glob " +
+        "and TodoWrite starts a process that has nothing to say. Run `seisin wire` again: it " +
+        "narrows seisin's own entry in place and leaves everyone else's hooks alone.",
+    });
+  return warnings;
+}

package/src/inspect/network.js

@@ -0,0 +1,37 @@
+export function modelEndpointWarnings(config, roles) {
+  const warnings = [];
+  /**
+   * A role that can write code and cannot reach any inference API.
+   *
+   * Reported three separate times, by three different people, with the same
+   * shape each time: a list of what agents need, written somewhere that does
+   * not know which agent will run. The last instance cost six bench runs that
+   * finished in eight seconds with `403 Connection blocked by network
+   * allowlist` — which in a results table reads as "this model cannot do the
+   * task", not as a policy error.
+   *
+   * What is deliberately NOT here: a registry of agents and their endpoints.
+   * That is the same defect in a new place, and the reporter said so before I
+   * could. The list below is only ever consulted to decide whether to print a
+   * sentence, so being wrong about it costs a false warning — never a broken
+   * run. That asymmetry is the whole reason it is allowed to exist, and the
+   * warning says out loud that the list is ours and may not know your agent.
+   */
+  const INFERENCE = /(anthropic|openai|googleapis|generativelanguage|bedrock|azure|openrouter|mistral|groq|together|deepseek|x\.ai|cohere|ollama|localhost|127\.0\.0\.1)/i;
+  for (const r of roles) {
+    const domains = r.network ?? config.allowedDomains ?? [];
+    if (domains.some((d) => INFERENCE.test(d))) continue;
+    warnings.push({
+      kind: "no-model-endpoint",
+      headline: domains.length
+        ? `${r.name} has ${domains.length} allowed domain(s) and none looks like a model API`
+        : `${r.name} may reach no network at all`,
+      detail:
+        "an agent that cannot reach its own model fails at startup with a 403 from the " +
+        "egress proxy, which reads as a broken install or a bad model rather than a policy. " +
+        "This check knows a handful of providers and will not know yours — it is a question, " +
+        "not a verdict.",
+    });
+  }
+  return warnings;
+}

package/src/inspect/providers.js

@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import { entriesOf } from "../keys.js";
+import { resolveExecutable } from "../surface.js";
+
+/**
+ * Would the parent find this command? The same lookup `run` makes
+ * (resolveExecutable), so check does not call "missing" a program that is
+ * only in a directory a role writes — that has its own warning, above.
+ */
+function onPath(cmd, config) {
+  try {
+    // A path is resolved against the policy and not looked up, so it is there
+    // only if it exists.
+    return existsSync(resolveExecutable(cmd, config));
+  } catch (e) {
+    return /a role can write/.test(e.message);
+  }
+}
+
+export function providerInTerritoryWarnings(config) {
+  const warnings = [];
+  // A provider the parent could not find where no role writes. `run` refuses
+  // it with the same sentence; here it is found before anybody runs anything.
+  for (const [scheme, p] of Object.entries(config.keyProviders ?? {})) {
+    const cmd = p.command?.[0];
+    if (!cmd || cmd.includes("/")) continue;
+    try { resolveExecutable(cmd, config); } catch (e) {
+      if (!/a role can write/.test(e.message)) continue;
+      warnings.push({
+        kind: "provider-in-territory",
+        headline: `the ${scheme}:// provider "${cmd}" is only found where a role can write`,
+        detail: e.message.split("\n").slice(1).map((l) => l.trim()).join(" "),
+      });
+    }
+  }
+  return warnings;
+}
+
+export function providerMissingWarnings(config) {
+  const warnings = [];
+  /**
+   * A provider whose command is not on PATH.
+   *
+   * This is the half of validating references that can be done without
+   * resolving one — which is the whole requirement: a broken policy has to be
+   * visible in `check`, not on the first run, and certainly not by asking
+   * somebody's keychain for a password to find out. The scheme and the
+   * provider are checked when the config loads, so by the time we are here
+   * they exist; what is left is whether the command does.
+   *
+   * A warning and not an error: the binary can legitimately be missing on the
+   * machine reading the policy and present on the one that runs it, which is
+   * every CI checkout.
+   */
+  const used = new Set();
+  for (const r of Object.values(config.roles))
+    for (const k of entriesOf(r)) if (k.kind === "ref") used.add(k.scheme);
+  for (const scheme of [...used].sort()) {
+    const provider = config.keyProviders?.[scheme];
+    if (!provider || onPath(provider.command[0], config)) continue;
+    warnings.push({
+      kind: "provider-missing",
+      headline: `the ${scheme} provider runs "${provider.command[0]}", which is not on PATH`,
+      detail:
+        "every key of that scheme will stop the run rather than resolve. Nothing is " +
+        "substituted for a key that did not resolve, so this fails closed — but it fails " +
+        "at the start of a run, not here.",
+    });
+  }
+  return warnings;
+}

package/src/inspect/read-territory.js

@@ -0,0 +1,105 @@
+import { delimiter } from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { keptFor, shutByTerritory, readPath, dataRoots } from "../territory.js";
+import { realAncestor } from "../paths.js";
+
+/**
+ * What `read = "territory"` takes away from a role that it may need, said
+ * before the run rather than discovered inside it.
+ *
+ * This is the answer to the objection decisions.md wrote against a read
+ * allowlist: the toolchain gets one entry wrong and the agent crashes without
+ * a reason. The mode leaves the system readable, so interpreters and libraries
+ * are not the risk; what breaks is a toolchain kept under the home — a venv,
+ * `~/.nvm`, `~/.pyenv` — and that is exactly what these name.
+ */
+export function territoryWarnings(config, r) {
+  const out = [];
+  const declared = [...(r.reads ?? []), ...(r.toolchain ?? [])];
+  if (config.read !== "territory") {
+    if (declared.length)
+      out.push({
+        kind: "reads-without-territory",
+        headline: `${r.name}: reads / toolchain are set, but [runtime] read is "all" — they change nothing`,
+        detail: 'Under read = "all" every file outside the denied ones is readable already. They take effect ' +
+          'with [runtime] read = "territory".',
+      });
+    return out;
+  }
+  for (const p of r.toolchain ?? []) {
+    const abs = readPath(config.root, p);
+    if (!existsSync(abs))
+      out.push({
+        kind: "toolchain-missing",
+        headline: `${r.name}: toolchain ${p} does not exist`,
+        detail: `Looked for ${abs}. A role told to verify its work with a toolchain it does not have retries, ` +
+          "installs and works around instead — measured at +80% cost per task, and no verification.",
+      });
+  }
+  for (const p of r.reads ?? []) {
+    const abs = readPath(config.root, p);
+    if (!existsSync(abs))
+      out.push({
+        kind: "reads-missing",
+        headline: `${r.name}: reads ${p} does not exist`,
+        detail: `Looked for ${abs}. Remove a stale entry or create the path before relying on it.`,
+      });
+  }
+  // A read grant that covers a whole home or data root turns the mode off for
+  // this role without anything saying so: `reads = ["~"]` reads like a
+  // detail and is every file the mode exists to shut.
+  const roots = dataRoots();
+  for (const p of declared) {
+    const abs = realAncestor(readPath(config.root, p));
+    const covered = roots.filter((root) => abs === "/" || root === abs || root.startsWith(abs + "/"));
+    if (covered.length)
+      out.push({
+        kind: "territory-reopened",
+        headline: `${r.name}: ${p} re-opens ${covered[0].replace(homedir(), "~") || "/"} whole — read = "territory" protects nothing there for this role`,
+        detail: `${covered.join(", ")} ${covered.length === 1 ? "is a place" : "are places"} the mode denies because people keep their data there. ` +
+          "Name the directory the role needs inside it instead.",
+      });
+  }
+  const keep = keptFor(config, r);
+  const path = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  const shut = [...new Set(path.filter((d) => existsSync(d) && shutByTerritory(d, keep)))];
+  if (shut.length)
+    out.push({
+      kind: "path-shut-by-territory",
+      headline: `${r.name}: ${shut.length} PATH entr${shut.length === 1 ? "y is" : "ies are"} unreadable under read = "territory"`,
+      detail: "A program found in one of these today falls through to another one inside the sandbox, " +
+        "or is not found. If the role needs one, name it " +
+        `in toolchain: toolchain = ["${shut[0].replace(homedir(), "~").replace(/\/bin$/, "")}"].`,
+      // One per line when printed: on a real PATH this was a dozen entries in
+      // one sentence, and the one a reader was looking for was in the middle.
+      items: shut.map((d) => d.replace(homedir(), "~")),
+    });
+  /**
+   * Claude Code keeps its sign-in in the macOS login keychain, which lives
+   * under the home and is shut here. Measured 2026-10-09: the run starts and
+   * says "Not logged in"; with ~/Library/Keychains in `reads` it signs in —
+   * and the role can then read every item in the keychain (decisions.md,
+   * the rejected keychain link), which is not offered. A token handed over as
+   * a key keeps the keychain shut.
+   */
+  const tokenNames = ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"];
+  const hasToken = (r.keyEntries ?? []).some((k) => tokenNames.includes(k.name)) ||
+    (r.env ?? []).some((e) => tokenNames.includes(e));
+  if (process.platform === "darwin" && !hasToken)
+    out.push({
+      kind: "territory-keychain",
+      headline: `${r.name}: under read = "territory" Claude Code cannot reach its sign-in in the login keychain`,
+      detail: 'It starts and says "Not logged in". Hand it a token as a key instead — ' +
+        'keys = ["CLAUDE_CODE_OAUTH_TOKEN=<provider>://…"] (from `claude setup-token`) or ANTHROPIC_API_KEY. ' +
+        "Opening ~/Library/Keychains in reads signs it in and hands the role every password in the keychain.",
+    });
+  if (!r.verify)
+    out.push({
+      kind: "no-verify",
+      headline: `${r.name}: no verify command — check --verify cannot prove this role can run its own checks`,
+      detail: 'Name the command the role checks its work with: verify = ["python", "-m", "pytest", "--version"]. ' +
+        "`seisin check --verify` then runs it inside the role's sandbox before any agent does.",
+    });
+  return out;
+}

package/src/inspect/role-keys.js

@@ -0,0 +1,136 @@
+import { covers, enforcedNeverWrites } from "../owners.js";
+import { ROLE_KEYS, closest } from "../config.js";
+import { territoryWarnings } from "./read-territory.js";
+
+/**
+ * What is wrong with a role table's keys, as opposed to its paths.
+ *
+ * Two things, both about `never_writes` and both ways a subtraction can look
+ * written and not be:
+ *
+ *   - a setting seisin does not know. It used to be dropped without a word, which
+ *     for `writes` is a role with less than it thinks, and for a misspelt
+ *     `never_writes` is a role with MORE than its owner thinks — the one
+ *     direction a policy must not fail in. Named with the nearest
+ *     known setting when there is one close enough to be the intended spelling.
+ *   - a `never_writes` entry that no `writes` of the same role covers. It
+ *     subtracts from nothing, so it is either a typo in the path or a rule
+ *     that stopped applying when the territory moved. Either way it reads as
+ *     protection and is not.
+ *
+ * Silent when `never_writes` is absent. Absent is valid; a check that asks for
+ * the setting would turn an optional subtraction into a required migration.
+ */
+const onlyTartaros = (config) => {
+  const names = config?.sandbox?.provider ?? [];
+  return names.length > 0 && names.every((n) => n === "tartaros");
+};
+
+export function roleKeyWarnings(roles, config = null) {
+  const warnings = [];
+  for (const r of roles) {
+    const enforced = new Set(enforcedNeverWrites(config, r));
+    const skipped = (r.neverWritesDeclared ?? r.neverWrites ?? []).filter((g) => !enforced.has(g));
+    if (skipped.length)
+      warnings.push({
+        kind: "never-writes-not-enforced-here",
+        headline: `${r.name}: never_writes ${skipped.join(" ")} — not enforced on Linux until it exists`,
+        detail: "bubblewrap denies a path by mounting over it, and would create a missing one on the host " +
+          "for the whole run — for a lock file, locking everyone else out, and for good if the role is " +
+          "killed. seisin skips those, and explain says allowed for them, so the sentence matches the kernel.",
+      });
+    for (const k of r.unknownKeys ?? []) {
+      const near = nearest(k, ROLE_KEYS);
+      warnings.push({
+        kind: "unknown-role-key",
+        headline: `${r.name}: unknown setting "${k}" in [roles.${r.name}] — ignored` +
+          (near ? `. Did you mean "${near}"?` : ""),
+        detail: `Known settings: ${ROLE_KEYS.join(", ")}. ` +
+          (near === "never_writes"
+            ? "As written this subtracts nothing: the role can still write every path it lists."
+            : "Nothing in it takes effect."),
+      });
+    }
+    warnings.push(...territoryWarnings(config, r));
+    // A family handed to a role is a hole in the protection on purpose, and
+    // said on every check so it stays a decision somebody can see.
+    for (const f of r.controlFiles ?? [])
+      warnings.push({
+        kind: "control-files-handed",
+        headline: f === "ide"
+          ? `${r.name}: control_files = ["ide"] — may edit .vscode/, .cursor/ and .windsurf/ in its territory`
+          : `${r.name}: control_files = ["instructions"] — may edit CLAUDE.md, AGENTS.md and their kin in its territory`,
+        detail: f === "ide"
+          ? "Your editor applies what it writes there — tasks, settings, auto-approval, MCP servers — outside the sandbox. " +
+            "Hand it only to a role that maintains those files, and review its changes to them."
+          : "The next agent session reads what it writes there as its instructions, whichever role that session is.",
+      });
+    // macOS only, and not by omission: on Linux the runtime removes the network
+    // namespace, so every role already has a loopback of its own — it can serve
+    // and reach its own server with or without the key, and reaches nothing on
+    // the host either way (measured in Docker, Debian 12, bwrap 0.8.0).
+    if (r.localBinding && process.platform === "darwin")
+      warnings.push({
+        kind: "local-binding-reaches-localhost",
+        headline: `${r.name}: local_binding lets it connect to every port on localhost, not only listen`,
+        detail: "The runtime grants bind on any interface, inbound, and outbound to localhost:*. " +
+          "Anything listening on this machine without authentication — a local control API, a " +
+          "database, a dev server — is within this role's reach, outside its territory.",
+      });
+    // Both at once is a config that says "these ports" and grants "every port".
+    // macOS only: on Linux local_binding reaches nothing on the host, so there
+    // local_ports is the only one of the two that does anything.
+    if (r.localBinding && r.localPorts?.length && process.platform === "darwin")
+      warnings.push({
+        kind: "local-ports-moot",
+        headline: `${r.name}: local_ports names ${r.localPorts.join(", ")}, but local_binding already opens every localhost port`,
+        detail: "local_binding grants outbound to localhost:* in the kernel profile, so the port list " +
+          "restricts nothing for this role. Drop local_binding if the role only needs to reach " +
+          "those ports; keep it only if the role has to listen.",
+      });
+    // The port list lives in the runtime's proxy, not in the kernel: a client
+    // that dials 127.0.0.1:N itself is refused even on a listed port. Said on
+    // every check, because the clients people list ports for — databases,
+    // caches — are mostly that kind. See docs/decisions.md. Not under tartaros
+    // alone: its profile holds the port list, and a direct dial reaches a listed port.
+    else if (r.localPorts?.length && !onlyTartaros(config))
+      warnings.push({
+        kind: "local-ports-proxy-only",
+        headline: `${r.name}: local_ports ${r.localPorts.join(", ")} reaches only clients that use HTTP_PROXY`,
+        detail: "The port list is enforced by the sandbox's proxy; the kernel has no rule for one localhost port. " +
+          "curl, Python's urllib and requests, and Node's fetch (22+) go through it. Database drivers, " +
+          "psql, mysql and redis-cli dial directly and are denied. To tell, run it with " +
+          `\`seisin run ${r.name} -- <client>\`: on macOS a \`connect tcp:<port>\` in \`seisin log\` means it ` +
+          "skipped the proxy; on Linux it fails with ECONNREFUSED.",
+      });
+    // trustd is a macOS service; on Linux the key changes nothing.
+    if (r.trustd && process.platform === "darwin")
+      warnings.push({
+        kind: "trustd-open",
+        headline: `${r.name}: trustd = true opens com.apple.trustd.agent, a path out that the domain list does not see`,
+        detail: "trustd verifies certificates for Go (before 1.27) and Dart on macOS, and to do it fetches, " +
+          "outside the sandbox, the URLs a certificate carries. The runtime calls it an exfiltration vector; " +
+          "no public demonstration exists. Go 1.27+ does not need it: seisin sets SSL_CERT_FILE.",
+      });
+    for (const g of r.neverWrites ?? []) {
+      if (r.writes.some((w) => covers(w, g) || covers(w, g.replace(/\/\*\*$/, ""))))
+        continue;
+      warnings.push({
+        kind: "never-writes-subtracts-nothing",
+        headline: `${r.name}: never_writes "${g}" is not inside any of its writes`,
+        detail: "It denies something that was already denied, so it protects nothing. " +
+          "Check the path, or drop the entry if the territory moved.",
+      });
+    }
+  }
+  return warnings;
+}
+
+/** The candidate within edit distance 3 of `word`, or null. */
+function nearest(word, candidates) {
+  // Spellings of the same idea in another vocabulary, checked first because
+  // letters mislead here: `no_writes` is three edits from `writes`, and
+  // suggesting the grant for a misspelt subtraction is the worst answer.
+  if (/deny|never|no_?write/i.test(word)) return "never_writes";
+  return closest(word, candidates);
+}

package/src/inspect/shared.js

@@ -0,0 +1,37 @@
+import { ownersOf } from "../owners.js";
+
+/**
+ * Paths more than one role claims.
+ *
+ * Overlap is allowed and sometimes right — a hotfix role deliberately reaches
+ * into the territory of the role that normally owns a repo. It is reported so
+ * that it stays a decision somebody made rather than a thing that drifted.
+ */
+export function sharedPaths(config, roles = Object.values(config.roles)) {
+  // Asked once per distinct glob: a real policy repeats them (1,332 writes,
+  // 303 distinct in a multi-repo workspace), and each question is every glob of every
+  // role again.
+  const seen = new Set();
+  const asked = new Map();
+  for (const r of roles)
+    for (const glob of r.writes) {
+      let many = asked.get(glob);
+      if (many === undefined) asked.set(glob, (many = ownersOf(config, glob.replace(/\/\*\*$/, "")).length > 1));
+      if (many) seen.add(glob);
+    }
+  /**
+   * A shared database counts once, not four times.
+   *
+   * `writes` carries the sidecar expansion so that the grant and the sentence
+   * agree (see config.js), and this list read straight off it turned nine
+   * shared things into thirty-three — the same name with three suffixes,
+   * announced as if it were three more decisions to make. The expansion exists
+   * to stop a policy saying one thing four times; a warning that undoes that
+   * is the feature leaking into the place it was meant to clean up.
+   *
+   * A sidecar shared WITHOUT its database still counts on its own, because
+   * that is a real and odd thing to have.
+   */
+  const todas = new Set(seen);
+  return [...seen].filter((p) => !(/-(wal|shm|journal)$/.test(p) && todas.has(p.replace(/-(wal|shm|journal)$/, ""))));
+}

package/src/inspect/warnings.js

@@ -0,0 +1,58 @@
+import { sharedPaths } from "./shared.js";
+import { homeReachWarning } from "./home.js";
+import { codexSignInWarnings } from "./codex.js";
+import { roleKeyWarnings } from "./role-keys.js";
+import { enforceWarnings } from "./enforce.js";
+import { providerInTerritoryWarnings, providerMissingWarnings } from "./providers.js";
+import { relativePathWarnings, scratchWarnings, hookWarnings } from "./machine.js";
+import { modelEndpointWarnings } from "./network.js";
+import { layoutWarnings } from "./layout.js";
+import { envWarnings, keyFloorWarnings } from "./keys.js";
+import { injectWarnings } from "./inject.js";
+
+/** Every way this policy does not hold, each with what to do about it. */
+export function warningsFor(config, roles, shared = sharedPaths(config, roles), { scoped = false } = {}) {
+  const warnings = [];
+
+  warnings.push(...enforceWarnings(config, roles));
+  warnings.push(...roleKeyWarnings(roles, config));
+
+  warnings.push(...providerInTerritoryWarnings(config));
+
+  warnings.push(...relativePathWarnings());
+  if (shared.length)
+    warnings.push({
+      kind: "shared",
+      headline: `${shared.length} path(s) claimed by more than one role: ${shared.join(" ")}`,
+      detail: "Overlap is allowed — seisin will name every owner. It is listed so it stays a decision.",
+    });
+
+  warnings.push(...scratchWarnings(config));
+
+  warnings.push(...modelEndpointWarnings(config, roles));
+
+  warnings.push(...codexSignInWarnings(config, roles));
+
+  // Without the hook, half the record is missing rather than all of it: on macOS
+  // `seisin run` reads the kernel's own denials, so they still land and
+  // still queue a request. What goes unrecorded is everything the kernel
+  // allowed — which is the half `init --from-observations` is built out of, and
+  // the half that tells "nothing was denied" apart from "nobody was watching".
+  // The one limit that is about YOUR machine rather than about the repo.
+  const reach = homeReachWarning(config);
+  if (reach) warnings.push(reach);
+
+  warnings.push(...hookWarnings(config));
+
+  warnings.push(...layoutWarnings(config, roles, scoped));
+
+  warnings.push(...envWarnings(roles));
+
+  warnings.push(...injectWarnings(config, roles));
+
+  warnings.push(...keyFloorWarnings(config));
+
+  warnings.push(...providerMissingWarnings(config));
+
+  return warnings;
+}