seisin 0.6.4 → 0.7.0

package/src/config.js

@@ -1,36 +1,22 @@
 /**
- * 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.
+ * Reads and validates seisin.toml (or a JSON policy): the shape, every role's
+ * fields, the sandbox and key providers. The TOML subset is in toml.js.
  */
 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, unknownMode } from "./keys.js";
-import { readNotify } from "./notify.js";
-import { BROWSERS } from "./browsers.js";
+import { readNotify } from "./notify-config.js";
+import { FORBIDDEN, dict, isTable, own, LINES, parseToml } from "./toml.js";
+
+export { own, parseToml, closesArray, stripComment } from "./toml.js";
+import {
+  closest, readBoolean, ROLE_KEYS, readControlFiles, readProtect, readMcp, readBrowsers, readLocalPorts, readInjectHosts, readNeverWrites, readPrivate, checkPrivateOverlap, assertNotAbsolute, readAddresses, asArray, trimSlashes, beforeGlob,
+} from "./config-fields.js";
+export { closest, ROLE_KEYS, CONTROL_FAMILIES, privateDir } from "./config-fields.js";
 
-/** `a/b//` → `a/b`, in linear time (a `/\/+$/` regex backtracks on a long run of slashes). */
-const trimSlashes = (p) => {
-  let end = p.length;
-  while (end > 0 && p[end - 1] === "/") end--;
-  return p.slice(0, end);
-};
 
-// The directory above a path's first glob character: "src/a*/b" gives "src", "a*" gives "".
-const beforeGlob = (p) => {
-  const g = p.search(/[*?[\]{}]/);
-  if (g < 0) return p;
-  const slash = p.lastIndexOf("/", g);
-  return slash < 0 ? "" : p.slice(0, slash);
-};
 
 export { CONFIG_NAME } from "./layout.js";
 
@@ -46,247 +32,6 @@ export function findConfig(from = process.cwd()) {
   }
 }
 
-const RE_TABLE = /^\[([A-Za-z0-9_.\-]+)\]$/;
-const RE_PAIR = /^([A-Za-z0-9_\-]+)\s*=\s*(.+)$/;
-
-/**
- * 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);
-}
-
-const isTable = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-
-/** 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;
-}
-
-/**
- * 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
-  // 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 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]))
-          throw new Error(
-            `${CONFIG_NAME}:${i + 1}: [${tableName}] — "${parts.slice(0, k + 1).join(".")}" is already ` +
-            `a value, not a table. One name cannot be both.`);
-        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;
-    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. 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 = closesArray(next);
-      }
-      value = parts.join(" ");
-    }
-    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);
-    where.set(tableName ? `${tableName}.${key}` : key, at);
-    /**
-     * A key may not be a table that is declared elsewhere, in either order.
-     *
-     * `[roles.a]` with `network = []`, then `[roles]` and `a = true` forty lines
-     * down, used to replace the whole role with `true`: its `network = []` came
-     * back as "not set", which means the global allow list. `check` said
-     * nothing. It is the "last one wins" this parser refuses everywhere else,
-     * arriving by a different spelling.
-     */
-    if (Object.prototype.hasOwnProperty.call(table, key))
-      throw new Error(
-        `${CONFIG_NAME}:${i + 1}: "${key}" in [${tableName || "the root"}] is already the table ` +
-        `[${tableName ? tableName + "." : ""}${key}]. One name cannot be both — the value would replace ` +
-        `everything that table says.`);
-    table[key] = readValue(value, i + 1);
-  }
-  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. */
-export 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))}`);
-      // Whole numbers, for `local_ports`. Digits only: no sign, no decimal, no
-      // underscore — a port is none of those, and every other key still
-      // refuses a number through asArray.
-      const digits = /^\d+/.exec(body.slice(i));
-      if (digits) {
-        const after = body[i + digits[0].length];
-        if (after !== undefined && after !== "," && after !== " " && after !== "\t")
-          bad(`${JSON.stringify(body.slice(i, i + 12))} is not a whole number`);
-        items.push(Number(digits[0]));
-        i += digits[0].length;
-        expectItem = false;
-        continue;
-      }
-      if (c !== '"') bad(`array items must be double-quoted, found ${JSON.stringify(body.slice(i, i + 12))}`);
-
-      const end = body.indexOf('"', i + 1);
-      if (end === -1) bad("unterminated string inside the array");
-      // A backslash before the closing quote means somebody wrote `\"` and
-      // expected an escape. There are none — the quote just ended the string,
-      // and the error they get otherwise is about a missing comma somewhere in
-      // the middle of a shell pipeline, which names the symptom and hides the
-      // cause. Measured while writing the docs: every attempt at a one-line
-      // provider command landed here.
-      if (body[end - 1] === "\\")
-        bad(`there are no escapes in this format, so the \\" in ` +
-            `${JSON.stringify(body.slice(i, Math.min(end + 2, i + 40)))} ended the string early.\n` +
-            `  A value cannot contain a double quote. If this is a shell command, put it in a ` +
-            `script and name the script instead — which is also how it stops being unreadable.`);
-      items.push(body.slice(i + 1, end));
-      i = end + 1;
-      expectItem = false;                 // a trailing comma is fine; a trailing item is not
-    }
-    return items;
-  }
-
-  if (/^\d+$/.test(v)) return Number(v);
-
-  bad("value must be a string, an array of strings, a whole number, or a boolean");
-}
 
 /**
  * `[runtime] isolate` — one setting, two levels, because they were one and
@@ -476,7 +221,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8"), { root = nul
     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
+    // srt-settings.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
@@ -653,7 +398,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8"), { root = nul
        * every port on localhost (macOS), which includes whatever control API
        * is listening there without a password. This names the ports instead,
        * and the runtime's proxy enforces the list — the same allowlist the
-       * domains go through. See srt.js for what that costs: the client has to
+       * domains go through. See srt-settings.js for what that costs: the client has to
        * go through the proxy, which HTTP clients do and a MySQL driver does not.
        */
       localPorts,
@@ -675,7 +420,7 @@ export function loadConfig(path, text = readFileSync(path, "utf8"), { root = nul
        * Whether this role may reach com.apple.trustd.agent (macOS). Needed by
        * Dart/Flutter and by Go built before 1.27 to verify TLS at all; Go 1.27+
        * does without it through the SSL_CERT_FILE that env.js sets. Off unless
-       * the role says so. See srt.js for what it costs.
+       * the role says so. See srt-settings.js for what it costs.
        */
       trustd: trustd === true,
       /**
@@ -781,7 +526,7 @@ 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
+ * `["tartaros", "srt"]` (DEFAULT_PROVIDERS; `srt` alone before 0.7). 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.
@@ -995,285 +740,3 @@ export function parseJsonPolicy(text, path = "policy.json") {
   if (!isTable(raw)) throw new Error(`${path}: the policy is an object`);
   return walk(raw, "");
 }
-
-/** 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", "private", "keys", "key_mode", "inject_hosts", "env", "network", "never_writes", "local_binding", "local_ports", "browsers", "mcp", "trustd", "control_files", "reads", "toolchain", "verify", "handoff", "handoff_exempt", "requests"];
-
-/**
- * `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,
- * not [], so a policy that never mentions MCP changes nothing for a launcher
- * that reads it; `mcp = []` is the explicit "none".
- */
-function readMcp(value, where) {
-  if (value === undefined) return null;
-  const list = asArray(value, where);
-  const out = [];
-  for (const n of list) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n))
-      throw new Error(`${where}: ${JSON.stringify(n)} is not an MCP server name. ` +
-        `Use the name from the CLI's config, for example mcp = ["playwright"].`);
-    if (!out.includes(n)) out.push(n);
-  }
-  return out;
-}
-
-/**
- * `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.
- *
- * Refused at load for the same reason as `never_writes`: a port list that loads
- * with a typo in it opens a port nobody meant, or silently fails to open the
- * one they did. A string is accepted when it is only digits, because TOML
- * written by hand says `"8001"` as often as `8001`.
- */
-function readLocalPorts(value, where) {
-  if (value === undefined) return [];
-  const list = Array.isArray(value) ? value : [value];
-  const out = [];
-  for (const v of list) {
-    const n = typeof v === "string" && /^\d+$/.test(v) ? Number(v) : v;
-    if (!Number.isInteger(n) || n < 1 || n > 65535)
-      throw new Error(`${where}: ${JSON.stringify(v)} is not a port. Write numbers from 1 to 65535, ` +
-        `for example local_ports = [8001, 8081].`);
-    if (!out.includes(n)) out.push(n);
-  }
-  return out;
-}
-
-/**
- * `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.
- *
- * Refused at load, not warned about: this is a list of things a role must not
- * do, and a malformed entry that loads anyway fails open. An absolute path or a
- * `..` would point outside the repo the rest of the policy is written against,
- * so it cannot be the subtraction the person meant.
- */
-function readNeverWrites(value, where) {
-  const list = asArray(value, where);
-  for (const g of list) {
-    if (typeof g !== "string" || g.trim() === "")
-      throw new Error(`${where}: every entry must be a non-empty string`);
-    if (g.startsWith("/"))
-      throw new Error(`${where}: "${g}" is absolute. never_writes is relative to the repo root, like writes.`);
-    if (g.split("/").includes(".."))
-      throw new Error(`${where}: "${g}" contains "..". never_writes names paths inside the repo.`);
-  }
-  return list;
-}
-
-/**
- * `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 = trimSlashes(p.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 "${beforeGlob(dir) || "dir"}/**".`);
-  }
-  return list;
-}
-
-/** `private` with its `/**` and `./` taken off: the folder itself. */
-export const privateDir = (p) => trimSlashes(p.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 (`../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) {
-    if (typeof g !== "string" || g.trim() === "")
-      throw new Error(`${where}: every entry must be a non-empty string`);
-    if (g.startsWith("/"))
-      throw new Error(`${where}: "${g}" is absolute. Territories are relative to the repo root.`);
-  }
-  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];
-  if (Array.isArray(value) && value.every((v) => typeof v === "string")) return value;
-  throw new Error(`${where}: expected a string or an array of strings`);
-}

package/src/controls.js

@@ -19,7 +19,7 @@
  */
 import { createHash } from "node:crypto";
 import { loadConfig, CONTROL_FAMILIES, stripComment, closesArray } from "./config.js";
-import { settingsFor } from "./srt.js";
+import { settingsFor } from "./srt-settings.js";
 import { denyFor } from "./surface.js";
 import { cleanReason } from "./requests.js";
 

package/src/decide-request.js

@@ -0,0 +1,37 @@
+/** A person's decision, shared by the CLI and the console, never the MCP. */
+import { loadConfig } from "./config.js";
+import { editPolicy, requestsPath, asFileGrant, refuseIfBarred, applyGrant, settle } from "./requests.js";
+
+/**
+ * Looked up, applied and settled under one lock — the policy's, the one
+ * every grant takes (editPolicy). The lookup used to happen before it and
+ * the settle after it, so the console and `seisin grant` could both find the
+ * same request pending and both act on it. A decline takes the lock as well,
+ * though it writes no policy, for the same reason.
+ *
+ * The config is edited as text, so comments and order survive, and it is
+ * written before the queue is settled: if the write throws, the request is
+ * still open rather than marked done against a file that never changed.
+ *
+ * Selection stays with the interface: the CLI accepts positions and decorates
+ * the queue; the console accepts only a stable id and has its own errors.
+ * `reload: false` preserves CLI decline's use of its already loaded config;
+ * the console reloads even for a decline, so malformed policy still refuses it.
+ * `includeOnly: false` keeps CLI declines free of file-grant metadata, even
+ * when a sibling request reopened after an earlier one-file grant.
+ */
+export function decideRequest(config, { decision, reason, only = false, select, reload = true, includeOnly = true }) {
+  let request;
+  const result = editPolicy(config, (before) => {
+    const current = reload ? loadConfig(config.path, before) : config;
+    request = select(current);
+    if (decision !== "granted") return { toml: before, changed: false };
+    if (only) request = asFileGrant(request);
+    refuseIfBarred(current, request);
+    return applyGrant(before, request, reason);
+  }, {
+    // Keep settlement after the policy write, still under its lock.
+    after: () => settle(requestsPath(config.root), request.key, decision, reason, includeOnly ? { only: request.only } : undefined),
+  });
+  return { request, ...result };
+}