seisin 0.4.2 → 0.6.0

package/src/config.js

@@ -8,11 +8,14 @@
  *
  * If your config outgrows this subset, the config is doing too much.
  */
+import { createHash } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
+import { isIP } from "node:net";
 import { CONFIG_NAME } from "./layout.js";
-import { parseKey, MODES, checkNames, BUILTIN } from "./keys.js";
+import { parseKey, MODES, checkNames, BUILTIN, unknownMode } from "./keys.js";
 import { readNotify } from "./notify.js";
+import { BROWSERS } from "./browsers.js";
 
 export { CONFIG_NAME } from "./layout.js";
 
@@ -31,7 +34,6 @@ export function findConfig(from = process.cwd()) {
 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.
  *
@@ -59,8 +61,20 @@ export function own(obj, key) {
   return obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
 }
 
+/**
+ * Where each table and key of a parsed file was written, by dotted name.
+ *
+ * Kept beside the result rather than in it, so the object stays exactly the
+ * data that was written; loadConfig reads it to put a line number on a name it
+ * does not know.
+ */
+const LINES = new WeakMap();
+
+/** Minimal TOML subset -> plain object. Throws with a line number on bad input. */
 export function parseToml(text) {
   const out = dict();
+  const where = new Map();
+  LINES.set(out, where);
   let table = out;
   let tableName = "";
   // "Last one wins" is TOML-ish and wrong for a permission file. A policy can
@@ -87,9 +101,13 @@ export function parseToml(text) {
       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 ` +
+          `A later table would silently override the earlier one — put every setting for ` +
           `${tableName} in one place.`);
       seenTables.add(tableName);
+      tableName.split(".").forEach((_, k, parts) => {
+        const name = parts.slice(0, k + 1).join(".");
+        if (!where.has(name)) where.set(name, i + 1);
+      });
       table = tableName.split(".").reduce((node, key, k, parts) => {
         if (!Object.prototype.hasOwnProperty.call(node, key)) node[key] = dict();
         else if (!isTable(node[key]))
@@ -105,16 +123,18 @@ export function parseToml(text) {
     if (!pair) throw new Error(`${CONFIG_NAME}:${i + 1}: cannot read "${raw.trim()}"`);
 
     let [, key, value] = pair;
+    const at = i + 1;
     // An array may span lines; keep pulling until the brackets balance. Only
     // the new line is searched: searching the whole growing value made an
-    // unclosed array of 100k lines take 20 s to be refused.
-    if (value.startsWith("[") && !value.includes("]")) {
+    // unclosed array of 100k lines take 20 s to be refused. A `]` inside a
+    // quoted item does not close it — `["a]b",` used to end the array there.
+    if (value.startsWith("[") && !closesArray(value)) {
       const parts = [value];
       let closed = false;
       while (!closed && i + 1 < lines.length) {
         const next = stripComment(lines[++i]).trim();
         parts.push(next);
-        closed = next.includes("]");
+        closed = closesArray(next);
       }
       value = parts.join(" ");
     }
@@ -126,6 +146,7 @@ export function parseToml(text) {
         `${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);
+    where.set(tableName ? `${tableName}.${key}` : key, at);
     /**
      * A key may not be a table that is declared elsewhere, in either order.
      *
@@ -145,8 +166,19 @@ export function parseToml(text) {
   return out;
 }
 
+/** Is there a `]` on this line outside a quoted string? Strings do not span lines. */
+export function closesArray(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 true;
+  }
+  return false;
+}
+
 /** Strips a trailing `#` comment, but not one inside a quoted string. */
-function stripComment(line) {
+export function stripComment(line) {
   let quoted = false;
   for (let i = 0; i < line.length; i++) {
     const c = line[i];
@@ -241,14 +273,6 @@ function readValue(value, lineNo) {
   bad("value must be a string, an array of strings, a whole number, 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.
@@ -281,6 +305,36 @@ function readValue(value, lineNo) {
  * application and `security` is the application. That trades one hole for a
  * larger one: the login keychain is every password you have.
  */
+/** `[runtime] read`: "all" (default) or "territory". An unknown value is refused, never read as "all". */
+export function readReadMode(v, path = "seisin.toml") {
+  if (v === undefined || v === "all") return "all";
+  if (v === "territory") return "territory";
+  throw new Error(
+    `${path}: runtime.read must be "all" or "territory", not ${JSON.stringify(v)}. ` +
+    `An unknown value cannot silently leave every file readable.`);
+}
+
+/**
+ * `reads` and `toolchain`: paths, absolute, `~/…`, or relative to the repo.
+ *
+ * Same rule as `writes`, for the same reason: the sandbox opens a path and
+ * everything under it, so a literal path or a `dir/**` subtree is all that can
+ * be said. `docs/*.md` would have to be widened to `docs` or frozen to today's
+ * files; either way the policy would say something the kernel does not.
+ */
+function readReadList(v, at) {
+  const list = v === undefined ? [] : asArray(v, at);
+  for (const p of list) {
+    const above = p.endsWith("/**") ? p.slice(0, -3) : p;
+    if (/[*?[\]{}]/.test(above) || p === "**")
+      throw new Error(
+        `${at} = "${p}" cannot be enforced as written.\n` +
+        `  A read grant is a path and everything under it. Write "${above.replace(/\/?[^/]*[*?[\]{}].*$/, "") || "."}/**" ` +
+        `for the subtree, or name the paths.`);
+  }
+  return list;
+}
+
 export function readIsolate(v) {
   if (v === true || v === "home") return "home";
   if (v === "credentials") return "credentials";
@@ -290,8 +344,32 @@ export function readIsolate(v) {
     `An unknown value cannot silently turn credential isolation off.`);
 }
 
-export function loadConfig(path) {
-  const parsed = parseToml(readFileSync(path, "utf8"));
+/**
+ * A hash of the policy file as it is now, short: it names a version, it proves
+ * nothing. Every log line carries the one its run started with (intake.js), and
+ * every handoff decision the one it was made against (requests.js, queueOf).
+ */
+export function policyId(config) {
+  try {
+    return createHash("sha256").update(readFileSync(config.path)).digest("hex").slice(0, 12);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+export function loadConfig(path, text = readFileSync(path, "utf8")) {
+  // `text` lets a caller validate an edit before writing it — the console
+  // previews a policy that does not exist on disk yet, against the real root.
+  const parsed = parseToml(text);
+  checkShape(parsed, SHAPE, "", path, LINES.get(parsed));
   // 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
@@ -320,13 +398,14 @@ export function loadConfig(path) {
    * 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.
+   * There is almost no ambiguity to preserve here — a nested table under
+   * [roles] has one meaning in this tool, `inject_hosts`, and any other is an
+   * error that 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]));
+    const nested = Object.keys(r ?? {})
+      .filter((k) => k !== "inject_hosts" && 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 ` +
@@ -353,7 +432,11 @@ export function loadConfig(path) {
   // 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");
+  // `.secrets/` and `.secrets` are one directory, and every consumer compares
+  // them as prefixes: with the slash kept, `scan` walked into the protected
+  // directory and a bare key resolved to `.secrets//x`, which matched nothing.
+  const keyDirs = (keyDir === undefined ? [] : asArray(keyDir, "keys.dir"))
+    .map((d) => d.replace(/\/+$/, "") || d);
   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
@@ -363,14 +446,28 @@ export function loadConfig(path) {
 
   const out = {
     root: dirname(path), path, keyDirs, keyProviders,
-    allowedDomains: own(own(parsed, "network"), "allow") ?? [],
+    // Through asArray like every other list: `allow = "github.com"` was kept as
+    // a string, and a string iterated is its characters.
+    allowedDomains: asArray(own(own(parsed, "network"), "allow"), "network.allow"),
+    // `[network] deny_addresses` — where an allowed name may not lead. An allowed
+    // domain whose DNS somebody else controls can be pointed at a host on your
+    // LAN; the runtime denies loopback, link-local and metadata addresses by
+    // itself and leaves private ranges to the policy, because an intranet name
+    // is a legitimate thing to allow. Checked here, with the line, rather than
+    // by the sandbox at start.
+    deniedAddresses: readAddresses(own(own(parsed, "network"), "deny_addresses"), `${path}: network.deny_addresses`),
     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"),
+    // `[runtime] read` — what a role may read. "all" is every file but the ones
+    // denied by name; "territory" denies the places data lives and re-opens
+    // only what the role needs. See territory.js.
+    read: readReadMode(own(runtime, "read"), path),
+    redact: readBoolean(own(runtime, "redact"), `${path}: runtime.redact`),
     scanIgnore: asArray(own(own(parsed, "scan"), "ignore"), "scan.ignore"),
+    protect: readProtect(own(parsed, "protect"), path),
     roles: {},
   };
 
@@ -420,9 +517,8 @@ export function loadConfig(path) {
     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(", ")}.`);
+      throw unknownMode(`${path}: roles.${name}:`, "key_mode", keyMode);
+    const injectHosts = readInjectHosts(own(r, "inject_hosts"), `${path}: roles.${name}.inject_hosts`);
     const neverWrites = readNeverWrites(own(r, "never_writes"), `${path}: roles.${name}.never_writes`);
     const localBinding = own(r, "local_binding");
     const trustd = own(r, "trustd");
@@ -430,8 +526,20 @@ export function loadConfig(path) {
       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 handoff = own(r, "handoff");
+    if (handoff !== undefined && typeof handoff !== "boolean")
+      throw new Error(`${path}: roles.${name}.handoff must be true or false, not ${JSON.stringify(handoff)}`);
     const localPorts = readLocalPorts(own(r, "local_ports"), `${path}: roles.${name}.local_ports`);
+    const browsers = readBrowsers(own(r, "browsers"), `${path}: roles.${name}.browsers`);
     const mcp = readMcp(own(r, "mcp"), `${path}: roles.${name}.mcp`);
+    const controlFiles = readControlFiles(own(r, "control_files"), `${path}: roles.${name}.control_files`);
+    const reads = readReadList(own(r, "reads"), `${path}: roles.${name}.reads`);
+    const toolchain = readReadList(own(r, "toolchain"), `${path}: roles.${name}.toolchain`);
+    const priv = readPrivate(own(r, "private"), `${path}: roles.${name}.private`);
+    const verify = own(r, "verify") === undefined ? null : asArray(own(r, "verify"), `roles.${name}.verify`);
+    if (verify && verify.length === 0)
+      throw new Error(`${path}: roles.${name}.verify is empty. It is the command that proves the role can check ` +
+        `its own work — ["python", "-m", "pytest", "--version"] — or leave it out.`);
     out.roles[name] = {
       name,
       /**
@@ -445,11 +553,21 @@ export function loadConfig(path) {
        * kept so that regenerating a config writes back what a person typed
        * rather than the expansion.
        */
-      writes: withSidecars(writes),
+      writes: withSidecars([...new Set([...writes, ...priv])]),
       writesDeclared: writes,
+      /**
+       * Folders only this role reads and writes. Each is also part of its
+       * territory (added to `writes` above, so `explain`, `whose` and the
+       * settings agree it is this role's), and every OTHER role is given a
+       * denyRead and a denyWrite on it — in either read mode, isolated or not.
+       * Deny-only: an allow nested in a deny breaks on one platform or the
+       * other unless it is handled the way territory.js handles its own.
+       */
+      private: priv,
       keys,
       keyEntries,
       keyMode: keyMode ?? null,
+      injectHosts,
       env: asArray(own(r, "env"), `roles.${name}.env`),
       network: own(r, "network") === undefined ? null : asArray(own(r, "network"), `roles.${name}.network`),
       /**
@@ -490,6 +608,12 @@ export function loadConfig(path) {
        * go through the proxy, which HTTP clients do and a MySQL driver does not.
        */
       localPorts,
+      /**
+       * The headless browsers this role may start (browsers.js): the Mach
+       * services each needs, by name, and nothing else. `[]` unless the role
+       * says so — every other role keeps the profile as it was.
+       */
+      browsers,
       /**
        * 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
@@ -505,6 +629,42 @@ export function loadConfig(path) {
        * the role says so. See srt.js for what it costs.
        */
       trustd: trustd === true,
+      /**
+       * The families of control files this role may edit inside its own
+       * territory: "ide" (`.vscode/`, `.cursor/`, `.windsurf/`) and
+       * "instructions" (`CLAUDE.md`, `AGENTS.md`…). surface.js says what each
+       * is and why only these two can be handed out. Absent is none.
+       */
+      controlFiles,
+      /**
+       * Whether this role takes work handed to it (handoff.js). True unless the
+       * role says `handoff = false`: a role that is a pipeline phase rather
+       * than a worker — it prepares the tree, it is not someone to pass a
+       * file to — still owns its territory, and a write denied there goes to
+       * another owner or to a person instead of starting it.
+       */
+      handoff: handoff !== false,
+      /**
+       * What this role reads beyond its repo, under `read = "territory"`.
+       *
+       * `reads` is data — a sibling checkout, a shared docs folder. `toolchain`
+       * is what runs — a venv, `~/.nvm`, `~/.cargo` — kept apart because `check`
+       * treats the two differently: a toolchain that does not exist is the
+       * reason a role cannot verify itself, and that is worth a finding. Both
+       * are read grants and nothing else; neither is ever writable. Ignored
+       * (and said so by `check`) under `read = "all"`, where everything is
+       * readable already.
+       */
+      reads,
+      toolchain,
+      /**
+       * The command that proves this role can check its own work, run by
+       * `seisin check --verify` inside the role's sandbox. Measured in
+       * an agent orchestrator (2026-10-09): an agent asked to verify with nothing to verify
+       * with cost 80% more per task and verified nothing; the same agent with
+       * its toolchain ran the suite every time at the original cost.
+       */
+      verify,
       // 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
@@ -512,6 +672,8 @@ export function loadConfig(path) {
       unknownKeys: Object.keys(r).filter((k) => !ROLE_KEYS.includes(k)),
     };
   }
+  checkPrivateOverlap(out.roles, path);
+  out.sandbox = readSandbox(own(parsed, "sandbox"), path);
   out.notify = readNotify(own(parsed, "notify"), { path, root: out.root, keyDirs, roles: out.roles, own });
   return out;
 }
@@ -553,18 +715,85 @@ function readProviders(table, path) {
         `  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(", ")}.`);
+      throw unknownMode(`${path}: [keys.providers.${name}]`, "mode", mode);
     out[name] = { name, command, mode: mode ?? null };
   }
   return out;
 }
 
+/** The sandboxes seisin ships (sandboxes/index.js). Named here too, so config.js imports no runtime code. */
+const BUILTIN_SANDBOXES = ["srt", "tartaros"];
+
+/**
+ * `[sandbox]`: which sandbox enforces the roles, and any declared by command.
+ *
+ * `provider` is one name or a list in order of preference; absent, it is
+ * `srt`, as it always was. A name is one seisin ships or one declared under
+ * `[sandbox.providers.<name>]` — an unknown one is refused here, never read as
+ * the default, because "the config asks for tartaros and the run used srt"
+ * without a word is the silent substitution sandboxes/index.js exists to stop.
+ */
+function readSandbox(table, path) {
+  if (table === undefined) return null;
+  const providers = Object.create(null);
+  const declared = own(table, "providers");
+  for (const name of declared === undefined ? [] : Object.keys(declared)) {
+    if (BUILTIN_SANDBOXES.includes(name))
+      throw new Error(`${path}: [sandbox.providers.${name}] — "${name}" is built in and cannot be redefined. ` +
+        `Give your provider another name.`);
+    const command = own(own(declared, name), "command");
+    if (!Array.isArray(command) || command.length === 0 || command.some((c) => typeof c !== "string" || c === ""))
+      throw new Error(`${path}: [sandbox.providers.${name}] needs a command, as an array of strings:\n` +
+        `  command = ["mybox", "run", "--policy", "{policy}", "--"]`);
+    if (!command.slice(1).some((c) => c.includes("{policy}")))
+      throw new Error(`${path}: [sandbox.providers.${name}] has no {policy} in its command, so the sandbox would never ` +
+        `see the policy it is meant to enforce.\n  Put {policy} where the settings file goes: ` +
+        `command = [${[...command, "{policy}"].map((c) => `"${c}"`).join(", ")}]`);
+    // Optional: asks the sandbox, before anything runs, whether it can hold a
+    // policy. Exit 0 is yes; anything else is no, and the last line it prints says why.
+    // Without it a declared sandbox is only ever found out by the canary, so a
+    // list like ["mybox", "srt"] would stop at exit 86 instead of moving on.
+    const check = own(own(declared, name), "check");
+    if (check !== undefined) {
+      if (!Array.isArray(check) || check.length === 0 || check.some((c) => typeof c !== "string" || c === ""))
+        throw new Error(`${path}: [sandbox.providers.${name}] check must be a command, as an array of strings:\n` +
+          `  check = ["mybox", "check", "--policy", "{policy}"]`);
+      if (!check.slice(1).some((c) => c.includes("{policy}")))
+        throw new Error(`${path}: [sandbox.providers.${name}] has no {policy} in its check, so it would answer ` +
+          `without seeing the policy it is asked about.\n  Put {policy} where the settings file goes: ` +
+          `check = [${[...check, "{policy}"].map((c) => `"${c}"`).join(", ")}]`);
+    }
+    // Declared, because it cannot be detected: its Seatbelt denials carry
+    // sandbox-runtime's tag, so the kernel's refusals under it can be recorded.
+    const tags = own(own(declared, name), "tags_denials");
+    if (tags !== undefined && typeof tags !== "boolean")
+      throw new Error(`${path}: [sandbox.providers.${name}] tags_denials is true or false, not ${JSON.stringify(tags)}.`);
+    providers[name] = { name, command, check: check ?? null, tagsDenials: tags ?? false };
+  }
+  const raw = own(table, "provider");
+  if (raw === undefined)
+    return { provider: null, providers };
+  const names = typeof raw === "string" ? [raw] : raw;
+  if (!Array.isArray(names) || names.length === 0 || names.some((n) => typeof n !== "string"))
+    throw new Error(`${path}: sandbox.provider = ${JSON.stringify(raw)} — a name, or a list of names in order of preference: ` +
+      `provider = ["tartaros", "srt"]`);
+  for (const n of names) {
+    if (BUILTIN_SANDBOXES.includes(n) || providers[n]) continue;
+    const known = [...BUILTIN_SANDBOXES, ...Object.keys(providers)];
+    const near = closest(n, known);
+    throw new Error(`${path}: sandbox.provider names "${n}", which is not a sandbox seisin knows` +
+      `${near ? ` — did you mean "${near}"?` : "."}\n  Built in: ${BUILTIN_SANDBOXES.join(", ")}. ` +
+      `Any other is declared with a command: [sandbox.providers.${n}] command = ["…", "{policy}"].`);
+  }
+  if (new Set(names).size !== names.length)
+    throw new Error(`${path}: sandbox.provider lists a sandbox twice (${JSON.stringify(names)}).`);
+  return { provider: names, providers };
+}
+
 /**
  * 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
+ * `data/x/app.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
@@ -579,7 +808,7 @@ function readProviders(table, path) {
  * 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
+ * `app.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
@@ -603,8 +832,124 @@ export function withSidecars(paths) {
   return [...new Set(out)];
 }
 
+/**
+ * Every table and key a policy may have outside `[roles.*]`. `true` is a value,
+ * an object is a table, and `*` stands for any name (a provider's).
+ *
+ * Anything else is refused at load, with its line. The roles table reports an
+ * unknown key through `check` because a role's typo is usually one extra
+ * grant; here the settings are global, and the one that made this necessary
+ * was `isolaet = true` under [runtime] — read as nothing, so isolation stayed
+ * off for every role and nothing on screen said so. The same "fail open by
+ * typo" that was closed for roles, closed harder because it covers them all.
+ */
+const SHAPE = {
+  roles: null,                            // validated where roles are read
+  keys: { dir: true, providers: { "*": { command: true, mode: true } } },
+  network: { allow: true, deny_addresses: true },
+  runtime: { writes: true, isolate: true, redact: true, read: true },
+  scan: { ignore: true },
+  protect: { instructions: true },
+  notify: { url: true, url_file: true, format: true },
+  sandbox: { provider: true, providers: { "*": { command: true, check: true, tags_denials: true } } },
+};
+
+function checkShape(table, shape, prefix, path, lines) {
+  const known = Object.keys(shape).filter((k) => k !== "*");
+  for (const key of Object.keys(table)) {
+    const name = prefix ? `${prefix}.${key}` : key;
+    const at = `${path}:${lines?.get(name) ?? "?"}`;
+    const rule = Object.prototype.hasOwnProperty.call(shape, key) ? shape[key] : shape["*"];
+    if (rule === undefined) {
+      const near = closest(key, known);
+      throw new Error(
+        `${at}: ${prefix ? `[${prefix}] ` : ""}"${key}" is not a setting` +
+        `${prefix ? "" : " or a table"} seisin knows${near ? ` — did you mean "${near}"?` : "."}\n` +
+        `  Known${prefix ? ` in [${prefix}]` : " at the top level"}: ${known.join(", ")}. ` +
+        `An unknown name is refused rather than ignored: ignored, a misspelt setting ` +
+        `reads as a rule and does nothing.`);
+    }
+    if (rule === null) continue;
+    const value = table[key];
+    if (rule === true && isTable(value))
+      throw new Error(`${at}: [${name}] is a table, but ${name} is a setting — write ${key} = … under [${prefix}].`);
+    if (typeof rule === "object" && !isTable(value))
+      throw new Error(`${at}: ${name} = ${JSON.stringify(value)} — ${name} is a table, [${name}], with its settings under it.`);
+    if (typeof rule === "object") checkShape(value, rule, name, path, lines);
+  }
+}
+
+/** The candidate within edit distance 3 of `word`, or null. Shared with `check`. */
+export function closest(word, candidates) {
+  let best = null, bestD = 4;
+  for (const c of candidates) {
+    const d = distance(word.toLowerCase(), c);
+    if (d < bestD) { best = c; bestD = d; }
+  }
+  return best;
+}
+
+/** Levenshtein distance. */
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]; row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cur = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return row[b.length];
+}
+
+/** true, false, or absent (undefined). Anything else is a mistake, said as one. */
+function readBoolean(value, where) {
+  if (value === undefined || typeof value === "boolean") return value;
+  throw new Error(`${where} must be true or false, not ${JSON.stringify(value)}`);
+}
+
 /** 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"];
+export const ROLE_KEYS = ["writes", "private", "keys", "key_mode", "inject_hosts", "env", "network", "never_writes", "local_binding", "local_ports", "browsers", "mcp", "trustd", "control_files", "reads", "toolchain", "verify", "handoff"];
+
+/**
+ * `control_files`: which families of control files a role may edit. Refused at
+ * load when it names anything else — `.claude`, git hooks and the rest are not
+ * on the list on purpose, and a word the reader does not know must not load as
+ * a permission it thinks it wrote.
+ */
+export const CONTROL_FAMILIES = ["ide", "instructions"];
+
+function readControlFiles(value, where) {
+  if (value === undefined) return [];
+  const out = [];
+  for (const f of asArray(value, where)) {
+    if (!CONTROL_FAMILIES.includes(f))
+      throw new Error(`${where}: ${JSON.stringify(f)} is not a family of control files. ` +
+        `Known: ${CONTROL_FAMILIES.map((x) => JSON.stringify(x)).join(", ")}. ` +
+        `The others (.claude, git hooks, .mcp.json, .envrc) are never handed to a role.`);
+    if (!out.includes(f)) out.push(f);
+  }
+  return out;
+}
+
+/**
+ * `[protect]` — what is protected beyond the defaults. One key today:
+ * `instructions = true` protects `CLAUDE.md`, `AGENTS.md` and their kin from
+ * every role that is not handed them. Anything else in the table is refused.
+ */
+function readProtect(value, path) {
+  if (value === undefined) return { instructions: false };
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${path}: [protect] must be a table`);
+  for (const k of Object.keys(value))
+    if (k !== "instructions")
+      throw new Error(`${path}: [protect] ${k} is not a setting. Known: instructions.`);
+  const v = own(value, "instructions");
+  if (v !== undefined && typeof v !== "boolean")
+    throw new Error(`${path}: [protect] instructions must be true or false, not ${JSON.stringify(v)}`);
+  return { instructions: v === true };
+}
 
 /**
  * `mcp`: names of MCP servers, as the CLI's config calls them. Absent is null,
@@ -624,6 +969,23 @@ function readMcp(value, where) {
   return out;
 }
 
+/**
+ * `browsers`, refused rather than guessed: a name seisin has no preset for
+ * would read as a grant that was made, and grant nothing.
+ */
+function readBrowsers(value, where) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string"))
+    throw new Error(`${where} is a list of browser names, for example browsers = ["chromium"].`);
+  for (const b of value)
+    if (!Object.hasOwn(BROWSERS, b)) {
+      const near = closest(b, Object.keys(BROWSERS));
+      throw new Error(`${where}: "${b}" is not a browser seisin has a preset for${near ? ` — did you mean "${near}"?` : ""} ` +
+        `Known: ${Object.keys(BROWSERS).join(", ")}.`);
+    }
+  return [...new Set(value)];
+}
+
 /**
  * `local_ports`, refused rather than guessed when it is not a list of ports.
  *
@@ -646,6 +1008,45 @@ function readLocalPorts(value, where) {
   return out;
 }
 
+/**
+ * `inject_hosts`: for `key_mode = "inject"`, the hosts each masked credential
+ * is substituted into, keyed by the delivered variable name.
+ *
+ *   [roles.frontend.inject_hosts]
+ *   GH_TOKEN = ["api.github.com"]
+ *
+ * One list per credential and not one for the role, because the runtime gates
+ * substitution per credential: credential A's real value reaches only A's
+ * hosts, never B's. A host is an exact name — no wildcard — so `check` can say
+ * precisely which traffic is intercepted; the match against a wider wildcard in
+ * `allowedDomains` is computed later (srt.js), where the terminated set is.
+ */
+function readInjectHosts(value, where) {
+  if (value === undefined) return null;
+  if (typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${where}: inject_hosts is a table of VAR = ["host", …], ` +
+      `for example [roles.x.inject_hosts] GH_TOKEN = ["api.github.com"].`);
+  const out = {};
+  for (const [name, hosts] of Object.entries(value)) {
+    const list = asArray(hosts, `${where}.${name}`);
+    if (list.length === 0)
+      throw new Error(`${where}.${name}: a masked credential with no host injects nowhere. ` +
+        `List the host its token authenticates to, like ["api.github.com"].`);
+    for (const h of list) {
+      if (typeof h !== "string" || h.trim() === "")
+        throw new Error(`${where}.${name}: every host is a non-empty string`);
+      if (h.includes("*"))
+        throw new Error(`${where}.${name}: "${h}" is a wildcard. An inject host is an exact name, ` +
+          `so check can say which traffic is intercepted. A wildcard in allowedDomains still ` +
+          `covers it; that is reported, not declared here.`);
+      if (/^https?:\/\//.test(h) || h.includes("/"))
+        throw new Error(`${where}.${name}: "${h}" is not a host. Write the bare domain, like "api.github.com".`);
+    }
+    out[name] = [...new Set(list)];
+  }
+  return out;
+}
+
 /**
  * `never_writes`, refused rather than guessed when it cannot mean what it says.
  *
@@ -667,14 +1068,64 @@ function readNeverWrites(value, where) {
   return list;
 }
 
+/**
+ * `private`: folders inside the repo, written `dir` or `dir/**`.
+ *
+ * A folder and not a glob, because what is enforced is a deny on one path for
+ * every other role: `notes/*.md` would have to be widened to `notes` or frozen
+ * to today's files. Not absolute and no `..`, because the denies are given
+ * against the repo the policy describes and `explain` answers in it. Not the
+ * repo itself: private to one role, the whole repo is shut to all the others,
+ * which is a policy of one role written in the long way.
+ */
+function readPrivate(value, where) {
+  const list = value === undefined ? [] : asArray(value, where);
+  for (const p of list) {
+    const dir = p.replace(/\/\*\*$/, "").replace(/\/+$/, "").replace(/^\.\//, "");
+    if (p.startsWith("/"))
+      throw new Error(`${where}: "${p}" is absolute. A private folder is relative to the repo root, like writes.`);
+    if (dir.split("/").includes(".."))
+      throw new Error(`${where}: "${p}" contains "..". A private folder is inside the repo.`);
+    if (dir === "" || dir === "." || dir === "**")
+      throw new Error(`${where}: "${p}" is the whole repo. A private folder is a folder inside it — ` +
+        `"notes/**" — and every other role is denied it.`);
+    if (/[*?[\]{}]/.test(dir))
+      throw new Error(`${where}: "${p}" is a pattern. A private folder is one path and everything under it: ` +
+        `write "${dir.replace(/\/?[^/]*[*?[\]{}].*$/, "") || "dir"}/**".`);
+  }
+  return list;
+}
+
+/** `private` with its `/**` and `./` taken off: the folder itself. */
+export const privateDir = (p) => p.replace(/\/\*\*$/, "").replace(/\/+$/, "").replace(/^\.\//, "");
+
+/**
+ * One owner per private folder. Two roles naming the same folder, or one
+ * inside the other, would each be denied the other's — so neither could read
+ * its own. Refused at load, with both names.
+ */
+function checkPrivateOverlap(roles, path) {
+  const all = Object.values(roles).flatMap((r) => (r.private ?? []).map((p) => ({ role: r.name, p, dir: privateDir(p) })));
+  const inside = (a, b) => a === b || a.startsWith(b + "/");
+  for (let i = 0; i < all.length; i++)
+    for (let j = i + 1; j < all.length; j++) {
+      const a = all[i], b = all[j];
+      if (a.role === b.role || !(inside(a.dir, b.dir) || inside(b.dir, a.dir))) continue;
+      throw new Error(
+        `${path}: roles.${a.role}.private "${a.p}" and roles.${b.role}.private "${b.p}" ` +
+        `${a.dir === b.dir ? "are the same folder" : "overlap"}. A private folder has one owner: every ` +
+        `other role is denied it, so each of these two would be denied its own. Give it to one of them.`);
+    }
+}
+
 /**
  * A territory is relative to the repo root. An absolute one would ask the kernel
  * for a path on the machine and make `explain` (which reads absolute as outside
  * the repo) disagree with what the profile grants — see the CODEOWNERS `/apps/`
  * case. `..` is allowed on purpose: a role legitimately writes a sibling
- * directory (`../bitacora/...`), and it is resolved relative to the root, so a
- * territory that climbs above it grants what it resolves to, by the operator's
- * choice.
+ * directory (`../shared/...`), and it is resolved relative to the root, so a
+ * territory that climbs above it grants what it resolves to, by the choice of
+ * whoever wrote the policy.
  */
 function assertNotAbsolute(list, where) {
   for (const g of list) {
@@ -686,6 +1137,23 @@ function assertNotAbsolute(list, where) {
   return list;
 }
 
+/**
+ * An IP address or a CIDR range: `10.0.0.0/8`, `192.168.1.10`, `fc00::/7`
+ * (IPv6 without brackets). Anything else is refused with what was written.
+ */
+function readAddresses(value, where) {
+  const list = asArray(value, where);
+  for (const v of list) {
+    const [addr, prefix, extra] = v.split("/");
+    const family = isIP(addr);
+    const max = family === 6 ? 128 : 32;
+    const okPrefix = prefix === undefined || (/^\d+$/.test(prefix) && Number(prefix) <= max);
+    if (!family || !okPrefix || extra !== undefined)
+      throw new Error(`${where}: "${v}" is not an IP address or a CIDR range (e.g. "10.0.0.0/8", "fc00::/7")`);
+  }
+  return list;
+}
+
 function asArray(value, where) {
   if (value === undefined) return [];
   if (typeof value === "string") return [value];