seisin 0.4.2 → 0.6.0

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;
+}