seisin 0.5.0 → 0.6.0

package/src/commands/walls.js

@@ -3,30 +3,56 @@ import { unknownRole } from "../suggest.js";
 import { walls, wasted } from "../walls.js";
 import { STALE_RUNS } from "../requests.js";
 import { logPath } from "../log.js";
+import { standingOf } from "../owners.js";
+import { kindsOf } from "../kinds.js";
+import { parseSince } from "../views.js";
 import { C, out, safe } from "../render.js";
 
 export function wallsCommand(config, argv = []) {
   const role = argv[0];
-  if (!role) throw new Error("usage: seisin walls <role> [--since <iso>] [--min <n>] [--all]");
+  if (!role) throw new Error("usage: seisin walls <role> [--since <date|duration>] [--min <n>] [--all]");
   if (!config.roles[role]) throw unknownRole(config, role);
   const at = (flag, fallback) => {
     const i = argv.indexOf(flag);
     return i === -1 ? fallback : argv[i + 1];
   };
+  // The same reading of `--since` as review and the MCP: a date or `7d`.
+  const since = argv.includes("--since") ? parseSince(at("--since", null)) : null;
+  if (argv.includes("--since") && !since)
+    throw new Error(`--since takes a date (2026-10-01) or a duration back from now (7d, 12h, 2w), not "${safe(at("--since", "") ?? "")}"`);
   const every = walls(config, role, {
     file: logPath(config.root),
     min: Number(at("--min", 2)),
-    since: at("--since", null),
+    since,
     limit: 0,
   });
   const all = argv.includes("--all");
   const list = (all ? every : every.filter((w) => !w.stale)).slice(0, 6);
   const old = every.filter((w) => w.stale).length;
-  // Nothing to say prints nothing, the way `scan` does when a repo is clean.
-  // A command that always speaks is one whose output stops being read.
-  if (list.length) out(renderForPerson(role, list));
+  const shown = withKinds(config, list);
+  if (shown.length) out(renderForPerson(role, shown));
+  else if (!every.length)
+    out(`\n  ${C.dim}${safe(role)} has no repeated denials in the recorded runs. A path becomes a wall after ${at("--min", 2)} denials.${C.off}\n\n`);
+  else if (!all)
+    out(`\n  ${C.dim}${safe(role)} has no recent walls; older ones are hidden. Use seisin walls ${safe(role)} --all.${C.off}\n\n`);
   if (old && !all) out(`  (${old} older wall(s) not hit in the last ${STALE_RUNS}+ runs: seisin walls ${role} --all)\n`);
-  return list;
+  return shown;
+}
+
+/**
+ * An unowned path gets the kind and hint the console gives it (kinds.js).
+ *
+ * The bare reason said "has no owner — no role can write it until one claims
+ * it" about `dist/` and `.env` alike: an invitation to give a build folder or a
+ * credential an owner, while the console said what kind of thing each was and
+ * what to do instead. Same classifier, same sentence, on both screens.
+ */
+function withKinds(config, list) {
+  const stand = standingOf(config);
+  const unowned = list.filter((w) => w.action === "write" && !w.owners?.length &&
+    stand({ kind: "file", target: w.target }).kind === "unowned");
+  const natures = kindsOf(unowned.map((w) => w.target), { keyDirs: config.keyDirs ?? [] });
+  return list.map((w) => (unowned.includes(w) ? { ...w, ...natures.get(w.target) } : w));
 }
 
 /**
@@ -39,7 +65,13 @@ export function wallsCommand(config, argv = []) {
 export function renderForPerson(role, list) {
   const lines = [`\n  ${C.b}${safe(role)}${C.off} keeps hitting:\n\n`];
   for (const w of list) {
-    const why = w.owners?.length ? `belongs to ${w.owners.map(safe).join(", ")}` : safe(w.reason);
+    if (w.expected) {
+      lines.push(`    ${C.dim}${String(w.times).padStart(3)}×  ${w.action} ${safe(w.target)}  expected · ${safe(w.expected.hint)}${C.off}\n`);
+      continue;
+    }
+    const why = w.owners?.length ? `belongs to ${w.owners.map(safe).join(", ")}`
+      : w.kind ? `unowned · ${w.kind === "territory" ? "ownable" : w.kind}: ${safe(w.hint)}`
+      : safe(w.reason);
     lines.push(`    ${C.yellow}${String(w.times).padStart(3)}×${C.off}  ${w.action} ${safe(w.target)}  ${C.dim}${why}${C.off}\n`);
   }
   const n = wasted(list);

package/src/commands/whose.js

@@ -18,6 +18,7 @@
  */
 import { toRepoRelative, fromCwd } from "../paths.js";
 import { ownersOf, keyHolders } from "../owners.js";
+import { decideHandoff, nextStep, chainFromEnv } from "../handoff.js";
 import { twinsOf, whereIs } from "../worktree.js";
 import { C, out } from "../render.js";
 
@@ -54,7 +55,7 @@ export function whose(config, argv = []) {
     (mine
       ? `  ${C.green}that is you${C.off}${C.dim} — if it was denied, 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`
+        ? `  ${C.dim}you are ${asking}. ${nextStep(decideHandoff({ request: { role: asking, action: isKey ? "read" : "write", target: rel }, config, chain: chainFromEnv() }), asking)}${C.off}\n\n`
         : "\n")
   );
   for (const w of worktree) out(renderElsewhere(w, asking));

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";
 
@@ -302,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";
@@ -311,6 +344,19 @@ export function readIsolate(v) {
     `An unknown value cannot silently turn credential isolation off.`);
 }
 
+/**
+ * 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.
@@ -352,13 +398,14 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
    * 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 ` +
@@ -402,11 +449,22 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
     // 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")),
+    // `[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),
@@ -459,9 +517,8 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
     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");
@@ -469,9 +526,20 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
       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,
       /**
@@ -485,11 +553,21 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
        * 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`),
       /**
@@ -530,6 +608,12 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
        * 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
@@ -552,6 +636,35 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
        * 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
@@ -559,6 +672,8 @@ export function loadConfig(path, text = readFileSync(path, "utf8")) {
       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;
 }
@@ -600,14 +715,81 @@ 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.
  *
@@ -664,11 +846,12 @@ export function withSidecars(paths) {
 const SHAPE = {
   roles: null,                            // validated where roles are read
   keys: { dir: true, providers: { "*": { command: true, mode: true } } },
-  network: { allow: true },
-  runtime: { writes: true, isolate: true, redact: 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) {
@@ -727,7 +910,7 @@ function readBoolean(value, where) {
 }
 
 /** 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", "control_files"];
+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
@@ -786,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.
  *
@@ -808,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.
  *
@@ -829,6 +1068,56 @@ 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
@@ -848,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];

package/src/controls.js

@@ -80,8 +80,8 @@ function tableOf(lines, name) {
   return { header, end, keys };
 }
 
-function stamp(note) {
-  return `# set in the console ${new Date().toISOString().slice(0, 10)}` +
+function stamp(note, source = "in the console") {
+  return `# set ${source} ${new Date().toISOString().slice(0, 10)}` +
     (note ? ` · «${cleanReason(note)}»` : "");
 }
 
@@ -92,7 +92,7 @@ function stamp(note) {
  * value being replaced, and the stamp now describes the new one. Every other
  * line, comments included, stays byte for byte.
  */
-function setKey(text, table, key, value, note) {
+export function setKey(text, table, key, value, note, source) {
   const eol = text.includes("\r\n") ? "\r\n" : "\n";
   const lines = text.split("\n");
   const cr = eol === "\r\n" ? "\r" : "";
@@ -105,14 +105,14 @@ function setKey(text, table, key, value, note) {
     const was = lines.slice(at.from, at.to + 1).map((l) => stripComment(l).trim()).join(" ");
     if (was.slice(was.indexOf("=") + 1).replace(/\s+/g, "").replace(/,\]$/, "]") === value.replace(/\s+/g, "")) return text;
     const indent = /^\s*/.exec(lines[at.from])[0];
-    const line = `${indent}${key} = ${value}   ${stamp(note)}${cr}`;
+    const line = `${indent}${key} = ${value}   ${stamp(note, source)}${cr}`;
     lines.splice(at.from, at.to - at.from + 1, line);
   } else {
     // After the last key, not the last line: a comment above the next table
     // belongs to that table, and a line inserted under it would read as the
     // next role's.
     const after = t.keys.length ? t.keys[t.keys.length - 1].to : t.header;
-    lines.splice(after + 1, 0, `${key} = ${value}   ${stamp(note)}${cr}`);
+    lines.splice(after + 1, 0, `${key} = ${value}   ${stamp(note, source)}${cr}`);
   }
   return lines.join("\n");
 }