seisin 0.1.0

package/src/commands/ui.js

@@ -0,0 +1,31 @@
+/**
+ * `seisin ui` — the console, reading the real config and the real log.
+ *
+ * The only long-lived process in the tool, and scoped hard on purpose: a
+ * foreground command you start and stop, serving one page and one JSON
+ * document, on loopback. Nothing in the enforcement path touches it. If it is
+ * not running you lose a window, not a boundary.
+ */
+import { spawnSync } from "node:child_process";
+import { relative } from "node:path";
+import { serve } from "../serve.js";
+import { C, out } from "../render.js";
+
+export async function ui(config, argv = []) {
+  const i = argv.indexOf("--port");
+  const port = i === -1 ? 4178 : Number(argv[i + 1]);
+
+  const server = await serve(config.path, port);
+  const url = `http://127.0.0.1:${port}`;
+
+  out(
+    `\n  ${C.b}${url}${C.off}\n` +
+    `  ${C.dim}reading ${relative(process.cwd(), config.path)} and the log, live. ctrl-c to stop.${C.off}\n\n`
+  );
+
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawnSync(opener, [url], { stdio: "ignore", shell: process.platform === "win32" });
+
+  process.on("SIGINT", () => { server.close(); process.exit(0); });
+  return server;
+}

package/src/commands/whose.js

@@ -0,0 +1,94 @@
+/**
+ * `seisin whose <path>` — the lookup a confined process is allowed to run.
+ *
+ * The README's opening claim is that a refusal names an owner. That is true
+ * through the hook, and false for anyone who only wraps a process: the kernel
+ * carries no reason, so the child sees `Operation not permitted` and guesses.
+ * Measured in the field twice — an agent diagnosed a territory denial as
+ * "possibly sandbox restrictions on macOS", which is a plausible sentence and
+ * the wrong one.
+ *
+ * This closes it without any integration at all. The instruction becomes "on
+ * EPERM, ask whose it is", which any agent can follow, and the answer comes
+ * from the same config the boundary was built from.
+ *
+ * It reads and prints. There is deliberately nothing here that could make it
+ * worth attacking, because unlike everything else in this tool it is meant to
+ * be called *from inside* the box.
+ */
+import { ownersOf, keyHolders } from "../owners.js";
+import { twinsOf, whereIs } from "../worktree.js";
+import { C, out } from "../render.js";
+
+export function whose(config, argv = []) {
+  const target = argv[0];
+  if (!target) throw new Error("usage: seisin whose <path>");
+
+  const rel = target.startsWith(config.root + "/") ? target.slice(config.root.length + 1) : target;
+  const isKey = (config.keyDirs ?? []).some((d) => rel === d || rel.startsWith(d + "/"));
+  const owners = isKey ? keyHolders(config, rel) : ownersOf(config, rel);
+
+  // Who is asking, when there is one. A confined child has it in its
+  // environment; a person at a prompt does not, and neither case is an error.
+  const asking = process.env.SEISIN_ROLE;
+  const mine = asking && owners.includes(asking);
+
+  // A key is a file in a declared directory, not a place in a checkout, so a
+  // worktree has nothing to say about one.
+  const worktree = isKey ? [] : elsewhere(config, rel, owners);
+
+  if (owners.length === 0) {
+    out(
+      `\n  ${C.yellow}nobody${C.off} owns ${C.b}${rel}${C.off}\n` +
+      `  ${C.dim}No role can ${isKey ? "read" : "write"} it until one claims it in ${config.path}.${C.off}\n\n`
+    );
+    for (const w of worktree) out(renderElsewhere(w, asking));
+    return { target: rel, owners: [], mine: false, worktree };
+  }
+
+  const verb = isKey ? "is declared for" : "belongs to";
+  out(
+    `\n  ${C.b}${rel}${C.off} ${verb} ${C.b}${owners.join(", ")}${C.off}\n` +
+    (mine
+      ? `  ${C.green}that is you${C.off}${C.dim} — if it was refused, the reason is not ownership.${C.off}\n\n`
+      : asking
+        ? `  ${C.dim}you are ${asking}. Hand it over rather than working around it.${C.off}\n\n`
+        : "\n")
+  );
+  for (const w of worktree) out(renderElsewhere(w, asking));
+  return { target: rel, owners, mine, worktree };
+}
+
+/**
+ * The same file in the other checkouts of this repo, when it is owned
+ * differently there.
+ *
+ * This is the line the EPERM was missing. An agent refused inside a worktree
+ * asks whose the file is, hears "nobody", and concludes the map has a hole —
+ * when the map is fine and names the canonical checkout. A twin owned exactly
+ * the same way says nothing new and gets no line.
+ */
+function elsewhere(config, rel, owners) {
+  const { here, twins } = twinsOf(config, rel);
+  const sameOwners = (a, b) => a.length === b.length && a.every((o) => b.includes(o));
+  return twins
+    .map((t) => ({ ...t, owners: ownersOf(config, t.rel) }))
+    .filter((t) => !sameOwners(t.owners, owners))
+    .map((t) => ({ ...t, here, where: whereIs(config, here, t), askedOwners: owners }));
+}
+
+function renderElsewhere(t, asking) {
+  const kind = (c) => (c.worktree ? "the worktree" : "the canonical checkout");
+  const there = t.owners.length
+    ? `belongs to ${t.owners.join(", ")}` + (asking && t.owners.includes(asking) ? ` — that is you` : "")
+    : "has no owner";
+  const named =
+    t.owners.length && t.askedOwners.length
+      ? "The two checkouts are not owned by the same role."
+      : `The policy names ${kind(t.owners.length ? t : t.here)}, not ${kind(t.owners.length ? t.here : t)}.`;
+  return (
+    `  ${C.yellow}worktree${C.off}  ${t.where}\n` +
+    `  ${C.dim}          the same file there is ${C.off}${C.b}${t.rel}${C.off}${C.dim}, and it ${there}.\n` +
+    `            ${named}${C.off}\n\n`
+  );
+}

package/src/commands/wire.js

@@ -0,0 +1,74 @@
+/**
+ * `seisin wire` — put the hook where the agent will find it.
+ *
+ * Nothing wrote the log before this existed. The hook is what records a
+ * decision, and the hook only runs if the agent has been told to run it — which
+ * the README described as a thing that happens and never once said to set up.
+ * So `seisin log` came back empty after a dozen real runs, and with it went
+ * `watch`, `requests`, `grant`, `review` and the denial-becomes-a-handoff story
+ * the README opens with. Enforcement was solid; everything that remembers was
+ * unwired.
+ *
+ * It writes the project's own `.claude/settings.json`, not the user's global
+ * config: a permission tool that edits your machine's settings to install
+ * itself has misread the room.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { C, out } from "../render.js";
+
+const SETTINGS = join(".claude", "settings.json");
+
+/** Where the PreToolUse entry lives, and what it has to say. */
+export function hookEntry() {
+  return {
+    matcher: "*",
+    hooks: [{ type: "command", command: "seisin hook" }],
+  };
+}
+
+/** Is the hook already wired in this repo? */
+export function wired(root) {
+  const file = join(root, SETTINGS);
+  if (!existsSync(file)) return false;
+  try {
+    return JSON.stringify(JSON.parse(readFileSync(file, "utf8"))).includes("seisin hook");
+  } catch {
+    return false;                       // unreadable settings is not "wired"
+  }
+}
+
+export function wire(config) {
+  const file = join(config.root, SETTINGS);
+
+  // Merged, never replaced. Someone's hooks are their own and a tool that
+  // overwrites them to add itself does not get a second chance.
+  let settings = {};
+  if (existsSync(file)) {
+    try {
+      settings = JSON.parse(readFileSync(file, "utf8"));
+    } catch (e) {
+      throw new Error(`${SETTINGS} is not valid JSON (${e.message}). Fix it, or move it aside.`);
+    }
+  }
+
+  if (wired(config.root)) {
+    out(`\n  ${C.dim}already wired — ${SETTINGS} runs "seisin hook"${C.off}\n\n`);
+    return { changed: false, file };
+  }
+
+  settings.hooks ??= {};
+  settings.hooks.PreToolUse ??= [];
+  settings.hooks.PreToolUse.push(hookEntry());
+
+  mkdirSync(join(config.root, ".claude"), { recursive: true });
+  writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+
+  out(
+    `\n  ${C.green}wired${C.off}  ${SETTINGS}\n` +
+    `  ${C.dim}the agent now runs "seisin hook" before each tool call, which is what fills${C.off}\n` +
+    `  ${C.dim}the log. Without it the boundary still holds — you just cannot see it work.${C.off}\n\n` +
+    `  ${C.dim}Commit this file if the rest of your team should get it too.${C.off}\n\n`
+  );
+  return { changed: true, file };
+}

package/src/config.js

@@ -0,0 +1,317 @@
+/**
+ * Reads and validates seisin.toml.
+ *
+ * The parser covers a deliberate subset of TOML: `[table.name]` headers, and
+ * `key = ["a", "b"]` / `key = "a"` values. That is the whole config language,
+ * and keeping it in-house is why installing seisin pulls in exactly one
+ * dependency (the sandbox runtime) instead of a parser too.
+ *
+ * If your config outgrows this subset, the config is doing too much.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { CONFIG_NAME } from "./layout.js";
+
+export { CONFIG_NAME } from "./layout.js";
+
+/** Walk up from `from` until a seisin.toml shows up. Returns its path or null. */
+export function findConfig(from = process.cwd()) {
+  let dir = resolve(from);
+  for (;;) {
+    const candidate = join(dir, CONFIG_NAME);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const RE_TABLE = /^\[([A-Za-z0-9_.\-]+)\]$/;
+const RE_PAIR = /^([A-Za-z0-9_\-]+)\s*=\s*(.+)$/;
+
+/** Minimal TOML subset -> plain object. Throws with a line number on bad input. */
+/**
+ * Names a table or key may not have.
+ *
+ * `[roles.__proto__]` does not show up in `Object.keys(roles)`, so `check`
+ * prints the roles that exist and says nothing — while every other role
+ * inherits whatever it declared. A config reading `[roles.frontend]` with no
+ * `writes` came out of the parser owning the entire repo and holding
+ * GITHUB_TOKEN, and no amount of reading the file would show it.
+ *
+ * The tables below are made with a null prototype, which stops the inheritance
+ * on its own. The names are refused as well, because a config containing them
+ * is not a config with a mistake in it.
+ */
+const FORBIDDEN = new Set(["__proto__", "prototype", "constructor"]);
+
+/** A table with no prototype, so nothing is inherited into it. */
+function dict() {
+  return Object.create(null);
+}
+
+/** Read a property only if the object actually has it. */
+export function own(obj, key) {
+  return obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+}
+
+export function parseToml(text) {
+  const out = dict();
+  let table = out;
+  let tableName = "";
+  // "Last one wins" is TOML-ish and wrong for a permission file. A policy can
+  // look restrictive at the top and be cancelled forty lines down, and the
+  // person reviewing it reads the first block. Both shapes are refused.
+  const seenTables = new Set();
+  const seenKeys = new Set();
+  const lines = text.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = stripComment(raw).trim();
+    if (!line) continue;
+
+    const header = RE_TABLE.exec(line);
+    if (header) {
+      tableName = header[1];
+      for (const part of tableName.split("."))
+        if (FORBIDDEN.has(part))
+          throw new Error(
+            `${CONFIG_NAME}:${i + 1}: "[${tableName}]" uses the reserved name "${part}". ` +
+            `A table named that would not appear as a role and would hand its settings to ` +
+            `every other one.`);
+      if (seenTables.has(tableName))
+        throw new Error(
+          `${CONFIG_NAME}:${i + 1}: [${tableName}] appears twice. ` +
+          `A later block would silently override the earlier one — put every setting for ` +
+          `${tableName} in one place.`);
+      seenTables.add(tableName);
+      table = tableName.split(".").reduce((node, key) => {
+        if (!Object.prototype.hasOwnProperty.call(node, key)) node[key] = dict();
+        return node[key];
+      }, out);
+      continue;
+    }
+
+    const pair = RE_PAIR.exec(line);
+    if (!pair) throw new Error(`${CONFIG_NAME}:${i + 1}: cannot read "${raw.trim()}"`);
+
+    let [, key, value] = pair;
+    // An array may span lines; keep pulling until the brackets balance.
+    if (value.startsWith("[") && !value.includes("]")) {
+      while (!value.includes("]") && i + 1 < lines.length) value += " " + stripComment(lines[++i]).trim();
+    }
+    if (FORBIDDEN.has(key))
+      throw new Error(`${CONFIG_NAME}:${i + 1}: "${key}" is a reserved name and cannot be a setting.`);
+    const seen = `${tableName}.${key}`;
+    if (seenKeys.has(seen))
+      throw new Error(
+        `${CONFIG_NAME}:${i + 1}: "${key}" is set twice in [${tableName || "the root"}]. ` +
+        `The second would win, which is not a thing a permission file should do quietly.`);
+    seenKeys.add(seen);
+    table[key] = readValue(value, i + 1);
+  }
+  return out;
+}
+
+/** Strips a trailing `#` comment, but not one inside a quoted string. */
+function stripComment(line) {
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === '"') quoted = !quoted;
+    else if (c === "#" && !quoted) return line.slice(0, i);
+  }
+  return line;
+}
+
+/**
+ * One value, read strictly.
+ *
+ * Strict is the whole point, and it was not before. The array reader used to
+ * pick quoted runs out of the line with a regex and ignore everything between
+ * them, so `["a" GARBAGE "b"]` parsed as `["a","b"]` and an unterminated string
+ * parsed as `""`. A permission file that is half-understood is worse than one
+ * that is rejected: the half that was dropped is the half you meant.
+ *
+ * So this scans rather than matches, and anything it does not recognise is an
+ * error with a line number. There are no escapes — a `"` ends the string. If a
+ * path of yours needs a quote in it, that is outside this subset and the
+ * message says so instead of guessing.
+ */
+function readValue(value, lineNo) {
+  const v = value.trim();
+  const bad = (msg) => { throw new Error(`${CONFIG_NAME}:${lineNo}: ${msg}`); };
+
+  if (v === "true") return true;
+  if (v === "false") return false;
+
+  if (v.startsWith('"')) {
+    const end = v.indexOf('"', 1);
+    if (end === -1) bad(`unterminated string — no closing quote in ${v}`);
+    const rest = v.slice(end + 1).trim();
+    if (rest) bad(`unexpected ${JSON.stringify(rest)} after the string`);
+    return v.slice(1, end);
+  }
+
+  if (v.startsWith("[")) {
+    if (!v.endsWith("]")) bad("unterminated array — no closing bracket");
+    const items = [];
+    let i = 1;
+    const body = v.slice(0, -1);          // everything up to the closing bracket
+    let expectItem = true;                // a list alternates item, comma, item…
+
+    while (i < body.length) {
+      const c = body[i];
+      if (c === " " || c === "\t") { i++; continue; }
+
+      if (c === ",") {
+        if (expectItem) bad("empty array slot — two commas in a row, or a leading comma");
+        expectItem = true; i++; continue;
+      }
+      if (!expectItem) bad(`missing comma before ${JSON.stringify(body.slice(i, i + 12))}`);
+      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");
+      items.push(body.slice(i + 1, end));
+      i = end + 1;
+      expectItem = false;                 // a trailing comma is fine; a trailing item is not
+    }
+    return items;
+  }
+
+  bad("value must be a string, an array of strings, or a boolean");
+}
+
+/**
+ * Turns the parsed file into the shape the rest of the program uses, and
+ * rejects anything ambiguous.
+ *
+ * Rejecting is the point. The sandbox runtime refuses to start on an invalid
+ * settings file rather than falling back to a permissive default, and seisin
+ * matches that: a permission tool that guesses is worse than no permission tool.
+ */
+/**
+ * `[runtime] isolate` — one setting, two levels, because they were one and
+ * should not have been.
+ *
+ *   false          (default) the role reads your home like any process you run
+ *   "credentials"  the places credentials live go dark. HOME is untouched
+ *   "home" / true  the above, plus a HOME, TMPDIR and XDG set of the role's own
+ *
+ * **Why the middle one exists.** These were a single switch, and the half that
+ * is worth having was welded to the half that breaks things. Measured on macOS:
+ * with a home of its own, `claude -p` answers `Not logged in - please run
+ * /login`, and the cause is not this sandbox at all. Claude Code keeps its
+ * credential in the macOS Keychain, the login keychain lives at
+ * `$HOME/Library/Keychains`, and moving HOME points that at a keychain which
+ * does not exist. `HOME=/empty claude -p` reproduces it with no sandbox in
+ * sight, so the same would happen to any tool that relocates a home.
+ *
+ * Meanwhile the part people actually want - `~/.ssh`, `~/.aws`, `~/.npmrc` and
+ * `~/.config/gh/hosts.yml` closed to every role - never needed a new HOME at
+ * all. Measured, with HOME left alone: all four refused, and the agent starts.
+ *
+ * So the levels split along what each one costs. `"credentials"` is adoptable
+ * on a machine you are already working on; `"home"` is the stronger claim and
+ * keeps its honest price. `true` still means what it meant, so a config written
+ * before this reads the same.
+ *
+ * Rejected: linking the real keychain into the isolated home to get the best of
+ * both. Measured against a throwaway keychain - a confined role reads **every**
+ * item in it, including one added without `-A`, because a macOS ACL is per
+ * application and `security` is the application. That trades one hole for a
+ * larger one: the login keychain is every password you have.
+ */
+export function readIsolate(v) {
+  if (v === true || v === "home") return "home";
+  if (v === "credentials") return "credentials";
+  // Anything else is off, including a misspelling. A permission tool must not
+  // read a word it does not know as a stronger setting than the reader meant.
+  return false;
+}
+
+export function loadConfig(path) {
+  const parsed = parseToml(readFileSync(path, "utf8"));
+  // Read only what the file actually declared. The parser refuses the names
+  // that make inheritance possible, and this is the second half of the same
+  // rule: if one of them ever gets through, a role still cannot pick up a
+  // setting it never wrote down. Two independent stops, because the failure
+  // they prevent is invisible in review — the config reads one way and the
+  // policy is another.
+  const roles = own(parsed, "roles") ?? {};
+
+  /**
+   * A role is a leaf. `[roles.a.b]` is a typo, with certainty.
+   *
+   * In TOML the dot separates keys, so `[roles.mimo-v2.5-free-1]` declares a
+   * role called `mimo-v2` with a nested table inside it. `check` printed a list
+   * of plausible-looking names and said nothing; the failure arrived later as
+   * `unknown role "mimo-v2.5-free-1"`. Fifteen of eighteen runs on somebody's
+   * bench died on it, and the surviving three were the model names with no dots
+   * in them.
+   *
+   * There is no ambiguity to preserve here — a nested table under [roles] has
+   * no meaning in this tool — so it is an error, and it names both what was
+   * written and what it became.
+   */
+  for (const name of Object.keys(roles)) {
+    const r = own(roles, name);
+    const nested = Object.keys(r ?? {}).filter((k) => r[k] && typeof r[k] === "object" && !Array.isArray(r[k]));
+    if (nested.length)
+      throw new Error(
+        `${path}: [roles.${name}.${nested[0]}] — a dot separates keys in TOML, so this ` +
+        `declares a role called "${name}", not "${name}.${nested[0]}".\n` +
+        `  Role names cannot contain dots. Use "${name}-${nested[0]}".`);
+  }
+  const names = Object.keys(roles);
+  if (names.length === 0) throw new Error(`${path}: no [roles.<name>] sections found`);
+
+  // One directory or several. Several is the common case once a repo has more
+  // than one kind of secret, and making people flatten them to satisfy the tool
+  // is how a tool gets kept out.
+  const keyDir = own(own(parsed, "keys"), "dir");
+  const keyDirs = keyDir === undefined ? [] : asArray(keyDir, "keys.dir");
+  // `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.
+  const runtime = own(parsed, "runtime");
+  const runtimeWrites = own(runtime, "writes");
+
+  const out = {
+    root: dirname(path), path, keyDirs,
+    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
+    // srt.js for what each level emits, and readIsolate() below for why there
+    // are two of them.
+    isolate: readIsolate(own(runtime, "isolate")),
+    redact: own(runtime, "redact"),
+    scanIgnore: asArray(own(own(parsed, "scan"), "ignore"), "scan.ignore"),
+    roles: {},
+  };
+
+  for (const name of names) {
+    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)
+      throw new Error(`${path}: roles.${name} lists keys, but [keys] dir is not set`);
+    out.roles[name] = {
+      name,
+      writes,
+      keys,
+      env: asArray(own(r, "env"), `roles.${name}.env`),
+      network: own(r, "network") === undefined ? null : asArray(own(r, "network"), `roles.${name}.network`),
+    };
+  }
+  return out;
+}
+
+function asArray(value, where) {
+  if (value === undefined) return [];
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value;
+  throw new Error(`${where}: expected a string or an array of strings`);
+}

package/src/env.js

@@ -0,0 +1,61 @@
+/**
+ * The child's environment, built rather than inherited.
+ *
+ * Measured before this existed: 93 variables crossed into every sandboxed turn,
+ * a planted secret among them. `denyRead` protects files, and an environment
+ * variable is not a file — so a policy that scoped keys perfectly still handed
+ * over every token the parent shell happened to be carrying.
+ *
+ * So the rule is the same as everywhere else in seisin: nothing is inherited
+ * 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.
+ */
+
+/**
+ * What survives with no policy at all.
+ *
+ * Each of these is here because removing it breaks something ordinary, not
+ * because it looked harmless: PATH finds the binary, HOME finds the toolchain's
+ * config, TMPDIR pairs with the scratch grant, TERM and the locale keep output
+ * readable, and the CI/tty pair keeps tools from guessing wrong about the shell.
+ */
+export const BASE = [
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "PWD", "TMPDIR",
+  // Set explicitly by `run` in isolated mode, and carried here so a tool that
+  // reads them directly lands in the role's own home rather than the real one.
+  "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME",
+  "TERM", "TERM_PROGRAM", "COLORTERM", "LANG", "LC_ALL", "LC_CTYPE", "TZ",
+  "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS",
+];
+
+/**
+ * Names that must never ride along, even if a role asks for them by pattern.
+ *
+ * A role can name a variable explicitly and get it — that is the point of the
+ * `env` list. What this blocks is a wildcard quietly sweeping up a credential,
+ * which is how "pass through what the build needs" becomes "pass through
+ * everything" three commits later.
+ */
+const NEVER = /(^|_)(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|SESSION|COOKIE|PRIVATE)(_|$)/i;
+
+/**
+ * (env, dropped) — the child's environment, and the names left behind.
+ *
+ * The second half is not bookkeeping. A tool that silently drops the one
+ * variable your build needed is worse to debug than one that never touched the
+ * environment, so `seisin run` prints the count and `--debug-env` prints the names.
+ */
+export function buildEnv(parent, role, extra = []) {
+  const wanted = new Set([...BASE, ...extra, ...(role.env ?? [])]);
+  const env = {};
+  const dropped = [];
+
+  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; }
+    env[name] = value;
+  }
+  // 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() };
+}