seisin 0.1.1 → 0.3.0

package/src/config.js

@@ -11,6 +11,8 @@
 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";
 
@@ -170,10 +172,34 @@ 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);
       if (end === -1) bad("unterminated string inside the array");
+      // A backslash before the closing quote means somebody wrote `\"` and
+      // expected an escape. There are none — the quote just ended the string,
+      // and the error they get otherwise is about a missing comma somewhere in
+      // the middle of a shell pipeline, which names the symptom and hides the
+      // cause. Measured while writing the docs: every attempt at a one-line
+      // provider command landed here.
+      if (body[end - 1] === "\\")
+        bad(`there are no escapes in this format, so the \\" in ` +
+            `${JSON.stringify(body.slice(i, Math.min(end + 2, i + 40)))} ended the string early.\n` +
+            `  A value cannot contain a double quote. If this is a shell command, put it in a ` +
+            `script and name the script instead — which is also how it stops being unreadable.`);
       items.push(body.slice(i + 1, end));
       i = end + 1;
       expectItem = false;                 // a trailing comma is fine; a trailing item is not
@@ -181,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");
 }
 
 /**
@@ -273,6 +301,7 @@ export function loadConfig(path) {
   // is how a tool gets kept out.
   const keyDir = own(own(parsed, "keys"), "dir");
   const keyDirs = keyDir === undefined ? [] : asArray(keyDir, "keys.dir");
+  const keyProviders = readProviders(own(own(parsed, "keys"), "providers"), path);
   // `undefined` means "use the defaults"; an explicit empty array means "none".
   // The difference matters: one is a user who has not thought about it, the
   // other is a user who has.
@@ -280,7 +309,7 @@ export function loadConfig(path) {
   const runtimeWrites = own(runtime, "writes");
 
   const out = {
-    root: dirname(path), path, keyDirs,
+    root: dirname(path), path, keyDirs, keyProviders,
     allowedDomains: own(own(parsed, "network"), "allow") ?? [],
     runtimeWrites: runtimeWrites === undefined ? undefined : asArray(runtimeWrites, "runtime.writes"),
     // `[runtime] isolate` — how much of your home a role stops reaching. See
@@ -296,22 +325,298 @@ export function loadConfig(path) {
     const r = own(roles, name);
     const writes = asArray(own(r, "writes"), `roles.${name}.writes`);
     const keys = asArray(own(r, "keys"), `roles.${name}.keys`);
-    if (keys.length && keyDirs.length === 0)
+    // Read once, here, so every consumer sees the same answer about what an
+    // entry is. `keys` itself stays the array of strings that was written: it
+    // is what `render`, `serve` and `init` print, and the whole point of a
+    // reference is that the written form is the reviewable one.
+    const keyEntries = keys.map((k) => {
+      try {
+        return parseKey(k);
+      } catch (e) {
+        throw new Error(`${path}: roles.${name}: ${e.message}`);
+      }
+    });
+    // Only a path needs somewhere to live. A reference does not, and demanding
+    // `[keys] dir` from a config whose secrets are all in a vault would be the
+    // tool insisting on the arrangement it was built for.
+    if (keyEntries.some((k) => k.kind === "file") && keyDirs.length === 0)
       throw new Error(`${path}: roles.${name} lists keys, but [keys] dir is not set`);
+    /**
+     * An unknown scheme is refused, not ignored.
+     *
+     * Same rule as everywhere else here: a `keys = ["vault://x"]` with no
+     * `[keys.providers.vault]` is a configuration error, and the alternative —
+     * treating it as a filename, or as a key that quietly never arrives — is a
+     * policy that reads as protecting something it is not.
+     */
+    for (const k of keyEntries) {
+      // `file://` ships with seisin, so it needs no declaration. It is the one
+      // builtin, and the reason is in keys.js: a secret in a plain file is the
+      // case this exists for, and making that case declare a provider that
+      // runs `cat` is a papercut on the only path most people take.
+      if (k.kind !== "ref" || BUILTIN.has(k.scheme) || own(keyProviders, k.scheme)) continue;
+      const known = Object.keys(keyProviders);
+      throw new Error(
+        `${path}: roles.${name}: key "${k.raw}" uses the "${k.scheme}" scheme, and no ` +
+        `[keys.providers.${k.scheme}] is declared.\n` +
+        `  ${known.length ? `Declared providers: ${known.join(", ")}.` : "No providers are declared."}\n` +
+        `  A provider is a command with a placeholder:\n` +
+        `    [keys.providers.${k.scheme}]\n` +
+        `    command = ["your-cli", "read", "{ref}"]`);
+    }
+    checkNames({ name, keyEntries });
+    const keyMode = own(r, "key_mode");
+    if (keyMode !== undefined && !MODES.includes(keyMode))
+      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,
-      writes,
+      /**
+       * `writes` is what is GRANTED; `writesDeclared` is what was written.
+       *
+       * Expanded here and not at emit time, because two answers is how the
+       * document ends up looser or tighter than the boundary. Everything
+       * downstream — `ownersOf`, `explain`, `whose`, the settings, the console
+       * — reads `writes`, so the owner of a database is the owner of its `-wal`
+       * everywhere, and the kernel and the sentence agree. The declared form is
+       * kept so that regenerating a config writes back what a person typed
+       * rather than the expansion.
+       */
+      writes: withSidecars(writes),
+      writesDeclared: writes,
       keys,
+      keyEntries,
+      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;
 }
 
+/**
+ * `[keys.providers.<name>]` — the commands that turn a reference into a value.
+ *
+ * Validated here and not at resolution time, because the whole argument for
+ * references is that a broken policy should be visible in `seisin check`,
+ * without asking anybody's keychain for a password to find out.
+ *
+ * `{ref}` is required. A command without it resolves every reference to the
+ * same thing, which is the kind of mistake that looks like it works: the first
+ * key comes back, so does the second, and they are both the first one.
+ */
+function readProviders(table, path) {
+  const out = Object.create(null);
+  if (table === undefined) return out;
+  for (const name of Object.keys(table)) {
+    const p = own(table, name);
+    // Redefining `file://` is refused rather than honoured. Two configs where
+    // the same scheme means different things is the failure this whole feature
+    // is supposed to remove — and it would be invisible, because the policy
+    // reads identically in both.
+    if (BUILTIN.has(name))
+      throw new Error(
+        `${path}: [keys.providers.${name}] — "${name}://" is built in and cannot be redefined.\n` +
+        `  It reads a file, optionally one KEY out of it: "file://.secrets/all.env#TOKEN".\n` +
+        `  For different behaviour, give your provider another name.`);
+    const command = own(p, "command");
+    if (!Array.isArray(command) || command.length === 0 || command.some((c) => typeof c !== "string"))
+      throw new Error(
+        `${path}: [keys.providers.${name}] needs a command, as an array of strings.\n` +
+        `  e.g. command = ["security", "find-generic-password", "-w", "-s", "{ref}"]`);
+    if (!command.some((c) => c.includes("{ref}")))
+      throw new Error(
+        `${path}: [keys.providers.${name}] has no {ref} in its command, so every key of this ` +
+        `provider would resolve to the same value.\n` +
+        `  Put {ref} where the reference goes: command = [${command.map((c) => `"${c}"`).join(", ")}, "{ref}"]`);
+    const mode = own(p, "mode");
+    if (mode !== undefined && !MODES.includes(mode))
+      throw new Error(
+        `${path}: [keys.providers.${name}] mode = "${mode}" is not a delivery mode. ` +
+        `Known: ${MODES.join(", ")}.`);
+    out[name] = { name, command, mode: mode ?? null };
+  }
+  return out;
+}
+
+/**
+ * A SQLite database is four files, and a policy should say it once.
+ *
+ * `bitacora/x/equipo.sqlite` is not the database — it is one of the files the
+ * database is made of. Writing to it in WAL mode also writes `-wal` and
+ * `-shm`; in rollback mode, `-journal`. So "this role writes this database"
+ * takes four lines, and a policy with eight databases and thirty-one roles
+ * takes nine hundred and ninety-two of them. Measured on a real one: 744 of
+ * 1,248 write lines — 60% — were sidecars, and every single one had its
+ * `.sqlite` declared beside it. Not one case wanted the `-wal` without the
+ * database.
+ *
+ * **This grants no authority that was not already there**, which is the whole
+ * reason it is safe to do implicitly. The `-wal` holds that database's pending
+ * transactions: whoever can write the database can already empty it, replace
+ * it, or corrupt it. The sidecar is not a second resource — it is the same one.
+ *
+ * It is also not a glob. The kernel grants a path and everything under it, so
+ * `equipo.sqlite*` is unenforceable and `seisin check` refuses it; these are
+ * emitted as literal paths, exactly as if they had been typed.
+ *
+ * **The suffix list is closed on purpose** and this is the line that keeps the
+ * idea from becoming the exception list it could be: three suffixes, and only
+ * after a name that says SQLite. `.db` is deliberately not in it — plenty of
+ * things are called `.db` and a grant to create `whatever.db-wal` inside a
+ * directory somebody else owns would be new authority, arriving quietly. A
+ * database with another name declares its sidecars by hand, as before.
+ */
+const SIDECARS = ["-wal", "-shm", "-journal"];
+const IS_SQLITE = /\.sqlite3?$/;
+
+export function withSidecars(paths) {
+  const out = [];
+  for (const p of paths) {
+    out.push(p);
+    if (IS_SQLITE.test(p)) for (const s of SIDECARS) out.push(p + s);
+  }
+  // A policy written before this existed already lists them. Keeping the first
+  // occurrence keeps the order somebody chose.
+  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() };