seisin 0.2.0 → 0.3.0

package/src/config.js

@@ -12,6 +12,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { CONFIG_NAME } from "./layout.js";
 import { parseKey, MODES, checkNames, BUILTIN } from "./keys.js";
+import { readNotify } from "./notify.js";
 
 export { CONFIG_NAME } from "./layout.js";
 
@@ -171,6 +172,19 @@ function readValue(value, lineNo) {
         expectItem = true; i++; continue;
       }
       if (!expectItem) bad(`missing comma before ${JSON.stringify(body.slice(i, i + 12))}`);
+      // Whole numbers, for `local_ports`. Digits only: no sign, no decimal, no
+      // underscore — a port is none of those, and every other key still
+      // refuses a number through asArray.
+      const digits = /^\d+/.exec(body.slice(i));
+      if (digits) {
+        const after = body[i + digits[0].length];
+        if (after !== undefined && after !== "," && after !== " " && after !== "\t")
+          bad(`${JSON.stringify(body.slice(i, i + 12))} is not a whole number`);
+        items.push(Number(digits[0]));
+        i += digits[0].length;
+        expectItem = false;
+        continue;
+      }
       if (c !== '"') bad(`array items must be double-quoted, found ${JSON.stringify(body.slice(i, i + 12))}`);
 
       const end = body.indexOf('"', i + 1);
@@ -193,7 +207,9 @@ function readValue(value, lineNo) {
     return items;
   }
 
-  bad("value must be a string, an array of strings, or a boolean");
+  if (/^\d+$/.test(v)) return Number(v);
+
+  bad("value must be a string, an array of strings, a whole number, or a boolean");
 }
 
 /**
@@ -354,6 +370,15 @@ export function loadConfig(path) {
       throw new Error(
         `${path}: roles.${name}: key_mode = "${keyMode}" is not a delivery mode. ` +
         `Known: ${MODES.join(", ")}.`);
+    const neverWrites = readNeverWrites(own(r, "never_writes"), `${path}: roles.${name}.never_writes`);
+    const localBinding = own(r, "local_binding");
+    const trustd = own(r, "trustd");
+    if (trustd !== undefined && typeof trustd !== "boolean")
+      throw new Error(`${path}: roles.${name}.trustd must be true or false, not ${JSON.stringify(trustd)}`);
+    if (localBinding !== undefined && typeof localBinding !== "boolean")
+      throw new Error(`${path}: roles.${name}.local_binding must be true or false, not ${JSON.stringify(localBinding)}`);
+    const localPorts = readLocalPorts(own(r, "local_ports"), `${path}: roles.${name}.local_ports`);
+    const mcp = readMcp(own(r, "mcp"), `${path}: roles.${name}.mcp`);
     out.roles[name] = {
       name,
       /**
@@ -374,8 +399,67 @@ export function loadConfig(path) {
       keyMode: keyMode ?? null,
       env: asArray(own(r, "env"), `roles.${name}.env`),
       network: own(r, "network") === undefined ? null : asArray(own(r, "network"), `roles.${name}.network`),
+      /**
+       * What this role may never write, even inside its own `writes`.
+       *
+       * A subtraction, and the only one the format has. It exists for the case
+       * a territory glob cannot say: `repo/**` minus `repo/.git/index.lock`, for
+       * a role that works in a worktree and has its own index. Without it the
+       * alternative is enumerating every top-level entry of the repo but `.git`
+       * — a list that goes stale the day somebody adds a directory.
+       *
+       * Per role and never global: a global deny on `.git/index.lock` breaks
+       * every role that legitimately commits in the shared checkout. Absent
+       * means exactly what it meant before the key existed.
+       */
+      // Sidecars too: `data/app.sqlite` minus its `-wal` is not a subtraction.
+      // A fabricated -wal is applied to the database the next time it opens.
+      neverWrites: withSidecars(neverWrites),
+      neverWritesDeclared: neverWrites,
+      /**
+       * Whether this role may listen on a local port — a dev server, the
+       * backend an end-to-end test drives, a test database.
+       *
+       * Off unless the role says so, and per role because most roles never
+       * start a server: an agent that edits docs has no business accepting
+       * connections. Wider than the name: the runtime also lets the role listen
+       * on every interface and connect to every localhost port. See `check`.
+       */
+      localBinding: localBinding === true,
+      /**
+       * The ports on this machine the role may connect to, and no others.
+       *
+       * The narrow form of reaching a local service. `local_binding` opens
+       * every port on localhost (macOS), which includes whatever control API
+       * is listening there without a password. This names the ports instead,
+       * and the runtime's proxy enforces the list — the same allowlist the
+       * domains go through. See srt.js for what that costs: the client has to
+       * go through the proxy, which HTTP clients do and a MySQL driver does not.
+       */
+      localPorts,
+      /**
+       * The MCP servers this role may load, by name, or null when the policy
+       * does not say. `[]` is "none". seisin declares this and does not
+       * enforce it: MCP servers are started by the agent's CLI, so the launcher
+       * builds the CLI's MCP config from this list (Claude Code:
+       * `--mcp-config` with only these + `--strict-mcp-config`).
+       */
+      mcp,
+      /**
+       * Whether this role may reach com.apple.trustd.agent (macOS). Needed by
+       * Dart/Flutter and by Go built before 1.27 to verify TLS at all; Go 1.27+
+       * does without it through the SSL_CERT_FILE that env.js sets. Off unless
+       * the role says so. See srt.js for what it costs.
+       */
+      trustd: trustd === true,
+      // Kept so `check` can name a misspelt key instead of ignoring it. An
+      // unknown key in a role table used to be dropped silently, and for a
+      // subtraction that is failing open: `never_write` would read as a rule
+      // and subtract nothing.
+      unknownKeys: Object.keys(r).filter((k) => !ROLE_KEYS.includes(k)),
     };
   }
+  out.notify = readNotify(own(parsed, "notify"), { path, root: out.root, keyDirs, roles: out.roles, own });
   return out;
 }
 
@@ -466,9 +550,73 @@ export function withSidecars(paths) {
   return [...new Set(out)];
 }
 
+/** The keys a `[roles.<name>]` table can hold. Anything else is reported by `check`. */
+export const ROLE_KEYS = ["writes", "keys", "key_mode", "env", "network", "never_writes", "local_binding", "local_ports", "mcp", "trustd"];
+
+/**
+ * `mcp`: names of MCP servers, as the CLI's config calls them. Absent is null,
+ * not [], so a policy that never mentions MCP changes nothing for a launcher
+ * that reads it; `mcp = []` is the explicit "none".
+ */
+function readMcp(value, where) {
+  if (value === undefined) return null;
+  const list = asArray(value, where);
+  const out = [];
+  for (const n of list) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n))
+      throw new Error(`${where}: ${JSON.stringify(n)} is not an MCP server name. ` +
+        `Use the name from the CLI's config, for example mcp = ["playwright"].`);
+    if (!out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+/**
+ * `local_ports`, refused rather than guessed when it is not a list of ports.
+ *
+ * Refused at load for the same reason as `never_writes`: a port list that loads
+ * with a typo in it opens a port nobody meant, or silently fails to open the
+ * one they did. A string is accepted when it is only digits, because TOML
+ * written by hand says `"8001"` as often as `8001`.
+ */
+function readLocalPorts(value, where) {
+  if (value === undefined) return [];
+  const list = Array.isArray(value) ? value : [value];
+  const out = [];
+  for (const v of list) {
+    const n = typeof v === "string" && /^\d+$/.test(v) ? Number(v) : v;
+    if (!Number.isInteger(n) || n < 1 || n > 65535)
+      throw new Error(`${where}: ${JSON.stringify(v)} is not a port. Write numbers from 1 to 65535, ` +
+        `for example local_ports = [8001, 8081].`);
+    if (!out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+/**
+ * `never_writes`, refused rather than guessed when it cannot mean what it says.
+ *
+ * Refused at load, not warned about: this is a list of things a role must not
+ * do, and a malformed entry that loads anyway fails open. An absolute path or a
+ * `..` would point outside the repo the rest of the policy is written against,
+ * so it cannot be the subtraction the person meant.
+ */
+function readNeverWrites(value, where) {
+  const list = asArray(value, 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. never_writes is relative to the repo root, like writes.`);
+    if (g.split("/").includes(".."))
+      throw new Error(`${where}: "${g}" contains "..". never_writes names paths inside the repo.`);
+  }
+  return list;
+}
+
 function asArray(value, where) {
   if (value === undefined) return [];
   if (typeof value === "string") return [value];
-  if (Array.isArray(value)) return value;
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value;
   throw new Error(`${where}: expected a string or an array of strings`);
 }

package/src/diagnose.js

@@ -0,0 +1,172 @@
+/**
+ * The refusal the agent never heard, said after the fact.
+ *
+ * PreToolUse sees the path a tool call names, and that is all it sees. What the
+ * kernel refuses on its own — a child process, `/bin/rm` inside a script, a
+ * path the regex did not catch — reaches the agent as `Operation not permitted`
+ * with no path and no reason, and it retries. Measured on a real portfolio from
+ * 2026-09-14 to 2026-09-22: 5,617 refusals, all of them from the kernel, 72%
+ * the same role hitting the same path again.
+ *
+ * Two hooks close that, the shape nono uses for its sandbox diagnostics:
+ *
+ *   - after a tool call fails (PostToolUseFailure, and PostToolUse for Bash,
+ *     which reports a failed command as a result): read this role's kernel
+ *     refusals from the last moments and hand the agent the same sentence the
+ *     PreToolUse hook would have — whose it is, how many times, and that it
+ *     should hand it over rather than retry. The kernel's line reaches the log
+ *     about 30 ms after the refusal (measured inside the box), so this reads it.
+ *   - when a session starts, resumes or is compacted (SessionStart): the role's
+ *     territory and what it keeps being refused, before the first refusal —
+ *     and right after compaction, which is when an agent forgets what it was
+ *     already told.
+ *
+ * What it does not do, on purpose: suggest widening. nono's message offers
+ * `--allow /path`; that assumes the profile was too narrow. seisin assumes the
+ * file is somebody else's, and the way out is handing it to them.
+ *
+ * On Linux the runtime's refusals cannot be read from outside (violations.js),
+ * so the after-the-fact half finds nothing there and stays quiet.
+ */
+import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { explain } from "./owners.js";
+import { timesHit, walls } from "./walls.js";
+import { collapseSidecars } from "./render.js";
+
+/** What a refused write or read looks like in a tool's output. A trigger to look, not a verdict. */
+export const DENIAL_SIGNS = /Operation not permitted|EPERM|EACCES|Permission denied|Read-only file system/i;
+
+/**
+ * Refusals the runtime's profile makes that never reach the log, recognised by
+ * what the failing program printed.
+ *
+ * The log holds what the kernel refused on a path or a port. A Mach service
+ * registration is neither: the profile refuses it, the program dies with its
+ * own words, and nothing in `.seisin/` says why. Each entry here is one of those
+ * signatures, measured, with the sentence that sends the agent to the fix
+ * instead of to a retry. Kept to exact signatures — a guess here would be an
+ * explanation for a failure seisin did not cause.
+ */
+export const KNOWN_REFUSALS = [
+  {
+    // Measured 2026-09-23 with Playwright's Chromium under seisin on macOS. It
+    // cost a team an afternoon: the error names a Mach port, not a file.
+    sign: /bootstrap_check_in\s+org\.chromium\.Chromium\.MachPortRendezvousServer\S*:\s*Permission denied \(1100\)/,
+    say: "Chromium could not register its Mach port: the sandbox does not allow it, and no grant " +
+      "changes that. Launch it with --single-process (Playwright: launchOptions.args) and one worker.",
+  },
+];
+
+/** The known refusals whose signature is in this output. */
+export function knownRefusals(evidence) {
+  return KNOWN_REFUSALS.filter((k) => k.sign.test(evidence)).map((k) => k.say);
+}
+
+/** How far back a refusal still belongs to the call that just failed. */
+const WINDOW_MS = 120_000;
+/** Read only the end of the log: this runs on every failed command. */
+const TAIL_BYTES = 512 * 1024;
+/** How many paths to name. More than this is a wall of text nobody acts on. */
+const MAX_NAMED = 3;
+
+function tail(file) {
+  if (!existsSync(file)) return [];
+  const { size } = statSync(file);
+  const from = Math.max(0, size - TAIL_BYTES);
+  const fd = openSync(file, "r");
+  try {
+    const buf = Buffer.alloc(size - from);
+    readSync(fd, buf, 0, buf.length, from);
+    const lines = buf.toString("utf8").split("\n");
+    if (from > 0) lines.shift();          // the first line is cut in half
+    const out = [];
+    for (const l of lines) {
+      if (!l.trim()) continue;
+      try { out.push(JSON.parse(l)); } catch { /* a line being written */ }
+    }
+    return out;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** This role's refusals by the kernel since `sinceMs`, one per path, newest first. */
+export function recentKernelDenials(file, role, sinceMs) {
+  const since = new Date(sinceMs).toISOString();
+  const seen = new Map();
+  for (const e of tail(file).reverse()) {
+    if (e.role !== role || e.verdict !== "denied" || e.source !== "kernel") continue;
+    if (!e.at || e.at < since || !e.target) continue;
+    const k = `${e.action}\u0000${e.target}`;
+    if (!seen.has(k)) seen.set(k, e);
+  }
+  return [...seen.values()];
+}
+
+/** The sentence for one refusal, in the words the PreToolUse hook uses. */
+function sentence(config, role, file, e) {
+  const action = e.kind === "key" ? "read" : e.action === "read" || e.action === "connect" ? e.action : "write";
+  const v = explain(config, role, action, e.target);
+  if (v.allowed) return null;             // the policy moved since: nothing to say
+  const times = timesHit(file, role, action, e.target);
+  const again = times > 1 ? ` Refused ${times} times now; the next try ends the same way.` : "";
+  if (v.neverWrites) return `${v.reason}. Do not ask for it.${again}`;
+  if (v.owners?.length)
+    return `${e.target} belongs to ${v.owners.join(", ")}. It is not ${role}'s to change — ` +
+      `hand it over rather than working around it.${again}`;
+  return `${e.target}: ${v.reason}.${again}`;
+}
+
+const PREFACE =
+  "seisin — the sandbox this agent runs in — refused part of that. This is not a Unix permission " +
+  "or a macOS privacy prompt: chmod, sudo or a different path to the same file will not change it.";
+
+/**
+ * After a tool call failed. Returns the hook output, or null to say nothing.
+ *
+ * `wait` retries the read a few times: the kernel's line lands ~30 ms after the
+ * refusal, and a loaded machine can be slower than the hook.
+ */
+export async function afterTool(config, role, event, { file, now = Date.now, wait = [0, 100, 300] } = {}) {
+  const evidence = JSON.stringify({ r: event.tool_response, e: event.error, o: event.tool_output });
+  if (!DENIAL_SIGNS.test(evidence)) return null;
+  // JSON escapes what the program printed; the signatures are written against the text.
+  const known = knownRefusals(evidence.replace(/\\n/g, "\n").replace(/\\"/g, '"'));
+  let found = [];
+  for (const ms of wait) {
+    if (ms) await new Promise((ok) => setTimeout(ok, ms));
+    found = recentKernelDenials(file, role, now() - WINDOW_MS);
+    if (found.length) break;
+  }
+  const lines = [...known, ...found.map((e) => sentence(config, role, file, e)).filter(Boolean)].slice(0, MAX_NAMED);
+  if (!lines.length) return null;
+  const total = known.length + found.length;
+  const more = total > MAX_NAMED ? ` (and ${total - MAX_NAMED} more — \`seisin walls ${role}\`)` : "";
+  return {
+    hookSpecificOutput: {
+      hookEventName: event.hook_event_name,
+      additionalContext: [PREFACE, ...lines.map((l) => `- ${l}`)].join("\n") + more,
+    },
+  };
+}
+
+/** When a session starts, resumes or is compacted: the map, before the first wall. */
+export function atSessionStart(config, role, event, { file } = {}) {
+  const r = config.roles[role];
+  const writes = collapseSidecars(r.writesDeclared ?? r.writes);
+  const lines = [
+    `seisin: this session runs as the role "${role}". The kernel enforces it; nothing inside can widen it.`,
+    `You may write: ${writes.length ? writes.join(", ") : "nothing"}. Reading the rest of the repo is fine.`,
+  ];
+  if ((r.neverWritesDeclared ?? r.neverWrites ?? []).length)
+    lines.push(`Never, even inside that: ${(r.neverWritesDeclared ?? r.neverWrites).join(", ")}.`);
+  if (r.keys.length) lines.push(`Keys you hold: ${r.keys.join(", ")}.`);
+  const w = file ? walls(config, role, { file, limit: 5, fresh: true }) : [];
+  if (w.length) {
+    lines.push("Already refused more than once, and still refused — do not try again, hand it over:");
+    for (const x of w)
+      lines.push(`- ${x.action} ${x.target} (${x.times}×) — ${x.owners?.length ? `belongs to ${x.owners.join(", ")}` : x.reason}`);
+  }
+  lines.push("A file outside that is somebody else's: say whose it is and hand it over, rather than working around it.");
+  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } };
+}

package/src/env.js

@@ -10,6 +10,9 @@
  * unless it is named. The base list below is what a command needs to be a
  * command at all, and it deliberately contains no credential-shaped names.
  */
+import { existsSync } from "node:fs";
+
+const SYSTEM_BUNDLE = "/etc/ssl/cert.pem";
 
 /**
  * What survives with no policy at all.
@@ -57,7 +60,34 @@ export const BASE = [
  * A role that wants the old behaviour names `GIT_OPTIONAL_LOCKS` in its `env`
  * and sets it in the parent — the loop below then overwrites this.
  */
-export const DEFAULTS = { GIT_OPTIONAL_LOCKS: "0" };
+export const DEFAULTS = {
+  GIT_OPTIONAL_LOCKS: "0",
+  /**
+   * Node's built-in `fetch()` ignores HTTP_PROXY/HTTPS_PROXY unless told
+   * otherwise, so inside the box it tries DNS directly and dies with ENOTFOUND
+   * while `npm`, which reads the proxy itself, works. Measured on Node 24.2:
+   * ENOTFOUND without it, 200 with it. It only makes Node use the proxy the
+   * sandbox already routes everything through — nothing is widened. Older
+   * Nodes ignore the variable.
+   */
+  NODE_USE_ENV_PROXY: "1",
+  /**
+   * The system's CA bundle, when there is one at this path (macOS ships it).
+   *
+   * Go 1.27+ verifies against SSL_CERT_FILE instead of asking the system when
+   * the variable is set ("the native Go verifier is used", go1.27 notes), and
+   * asking the system means com.apple.trustd.agent, which the sandbox closes.
+   * Measured: `go get` fails with `x509: OSStatus -26276` without it and works
+   * with it, with trustd still shut. Binaries built with Go before 1.27 (gh
+   * 2.89 is 1.26) ignore it; for those, and for Dart, see `trustd = true`.
+   *
+   * Only if the file exists: on a system without it, pointing every TLS client
+   * at a missing file would break the ones that work today. And a parent that
+   * sets its own SSL_CERT_FILE or SSL_CERT_DIR — a corporate CA — keeps it;
+   * see buildEnv.
+   */
+  ...(existsSync(SYSTEM_BUNDLE) ? { SSL_CERT_FILE: SYSTEM_BUNDLE } : {}),
+};
 
 /**
  * Names that must never ride along, even if a role asks for them by pattern.
@@ -87,8 +117,31 @@ export function buildEnv(parent, role, extra = []) {
   for (const [name, value] of Object.entries(parent)) {
     if (!wanted.has(name)) { dropped.push(name); continue; }
     if (NEVER.test(name) && !(role.env ?? []).includes(name)) { dropped.push(name); continue; }
+    // Not even when named: whoever can read the notify URL can send the person
+    // a fake "approve #3". Only the parent uses it (notify.js).
+    if (name === "SEISIN_NOTIFY_URL") { dropped.push(name); continue; }
     env[name] = value;
   }
+  // A trust store the parent chose is a decision about who to trust, not an
+  // incidental variable: it crosses whether or not the role named it, and it
+  // replaces the default rather than sitting next to it. They are paths, never
+  // secrets. A role that names SSL_CERT_FILE while the parent has none opts out
+  // of the default.
+  // A parent that already says whether Node should use the proxy is answered
+  // as it asked — `=0` included — rather than overwritten by the default.
+  if (parent.NODE_USE_ENV_PROXY !== undefined) env.NODE_USE_ENV_PROXY = parent.NODE_USE_ENV_PROXY;
+  // A role with `trustd = true` can ask the system verifier, which sees the
+  // Keychain — corporate CAs included — and /etc/ssl/cert.pem does not. Setting
+  // the bundle there would make Go 1.27+ skip the verifier the role was given
+  // trustd for, and fail behind a corporate proxy (review of 2026-09-22, #7).
+  if (role.trustd === true) delete env.SSL_CERT_FILE;
+  if (parent.SSL_CERT_FILE || parent.SSL_CERT_DIR) {
+    delete env.SSL_CERT_FILE;
+    for (const k of ["SSL_CERT_FILE", "SSL_CERT_DIR"])
+      if (parent[k]) { env[k] = parent[k]; const i = dropped.indexOf(k); if (i !== -1) dropped.splice(i, 1); }
+  } else if ((role.env ?? []).includes("SSL_CERT_FILE")) {
+    delete env.SSL_CERT_FILE;
+  }
   // A role may name a variable the parent does not have. That is not an error —
   // it is a policy written ahead of the environment, which is the right order.
   return { env, dropped: dropped.sort() };