seisin 0.4.2 → 0.5.0

package/src/commands/wire.js

@@ -13,18 +13,76 @@
  * config: a permission tool that edits your machine's settings to install
  * itself has misread the room.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from "node:fs";
+import { join, dirname, delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 import { C, out } from "../render.js";
+import { TOOL_MATCHER } from "../hook.js";
 
 const SETTINGS = join(".claude", "settings.json");
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
 
-/** Where the PreToolUse entry lives, and what it has to say. */
-export function hookEntry(command = "seisin hook") {
-  return {
-    matcher: "*",
-    hooks: [{ type: "command", command }],
-  };
+/** A hook command that is seisin's, however it was spelled when it was wired. */
+const isOurs = (c) => typeof c === "string" && /\bhook"?\s*$/.test(c) && (c.includes("seisin") || runsSeisinScript(c));
+
+/**
+ * A hook written by its full path (`"<node>" "<…>/src/cli.js" hook`) names no
+ * `seisin` when the checkout sits in a folder called something else. It is
+ * ours when the script it runs belongs to a package named seisin.
+ */
+function runsSeisinScript(command) {
+  const script = /"([^"]+\.js)"\s+hook\s*$/.exec(command)?.[1];
+  if (!script) return false;
+  try { return JSON.parse(readFileSync(join(dirname(script), "..", "package.json"), "utf8")).name === "seisin"; } catch { return false; }
+}
+
+/**
+ * The command that reaches THIS seisin from a hook, and how it was found.
+ *
+ * `seisin hook` was written for everyone. With seisin installed in a project
+ * rather than globally there is no `seisin` on PATH, the hook exits 127, and
+ * Claude Code carries on without it — nothing on screen, nothing in the log.
+ * So: the one on PATH when it is this version; the project's own
+ * node_modules/.bin when there is one; otherwise this file, by absolute path.
+ */
+export function hookCommand(root, { path = process.env.PATH, cli = CLI, version = ownVersion() } = {}) {
+  const found = (path ?? "").split(delimiter).map((d) => d && join(d, "seisin")).find((p) => p && existsSync(p));
+  let onPath = null;
+  if (found) {
+    const same = realOrSelf(found) === realOrSelf(cli);
+    const v = same ? version : spawnSync(found, ["--version"], { encoding: "utf8", timeout: 5000 }).stdout?.trim();
+    onPath = { at: found, version: v };
+    if (v === version) return { command: "seisin hook", via: "path", onPath };
+  }
+  const local = join(root, "node_modules", ".bin", "seisin");
+  if (existsSync(local)) return { command: '"$CLAUDE_PROJECT_DIR"/node_modules/.bin/seisin hook', via: "local", onPath };
+  return { command: `"${process.execPath}" "${realOrSelf(cli)}" hook`, via: "absolute", onPath };
+}
+
+function ownVersion() {
+  try { return JSON.parse(readFileSync(join(dirname(CLI), "..", "package.json"), "utf8")).version; } catch { return null; }
+}
+
+/** Is `dir` inside a git checkout? Kept here so wire does not load the scanner. */
+function insideRepo(dir) {
+  for (let d = dir; ; d = dirname(d)) {
+    if (existsSync(join(d, ".git"))) return true;
+    if (dirname(d) === d) return false;
+  }
+}
+
+function realOrSelf(p) {
+  try { return realpathSync(p); } catch { return p; }
+}
+
+/** One sentence: which seisin the hook runs, and why that one. */
+function saysWhich(h) {
+  const other = h.onPath && h.onPath.version !== ownVersion()
+    ? ` (the seisin on your PATH is ${h.onPath.version || "another version"}, not ${ownVersion()})` : "";
+  if (h.via === "path") return `the hook runs "seisin hook" — seisin ${ownVersion()} is on your PATH`;
+  if (h.via === "local") return `the hook runs this project's node_modules/.bin/seisin${other || " — seisin is not on your PATH"}`;
+  return `the hook runs this seisin by its full path${other || " — seisin is not on your PATH"}`;
 }
 
 /**
@@ -39,7 +97,7 @@ export function hookEntry(command = "seisin hook") {
 export function hookEntries(command = "seisin hook") {
   const h = [{ type: "command", command }];
   return {
-    PreToolUse: [{ matcher: "*", hooks: h }],
+    PreToolUse: [{ matcher: TOOL_MATCHER, hooks: h }],
     PostToolUse: [{ matcher: "Bash", hooks: h }],
     PostToolUseFailure: [{ matcher: "*", hooks: h }],
     SessionStart: [{ matcher: "startup|resume|compact", hooks: h }],
@@ -55,14 +113,59 @@ export function wired(root) {
     // session-start hooks existed has only PreToolUse, and "already wired" there
     // would keep it from ever getting the rest.
     const hooks = JSON.parse(readFileSync(file, "utf8")).hooks ?? {};
-    return Object.keys(hookEntries()).every((ev) => JSON.stringify(hooks[ev] ?? []).includes("seisin hook"));
+    return Object.keys(hookEntries()).every((ev) =>
+      (hooks[ev] ?? []).some((e) => (e?.hooks ?? []).some((h) => isOurs(h?.command))));
   } catch {
     return false;                       // unreadable settings is not "wired"
   }
 }
 
+/**
+ * Narrows seisin's own `"*"` PreToolUse entry to {@link TOOL_MATCHER}. True if
+ * it changed anything.
+ *
+ * Only an entry that holds nothing but `seisin hook`: a `"*"` entry that also
+ * runs somebody else's command is theirs as much as ours, and narrowing it
+ * would silently stop their hook on every other tool.
+ */
+function narrow(settings) {
+  let changed = false;
+  for (const entry of settings.hooks?.PreToolUse ?? []) {
+    if (broadOurs(entry)) {
+      entry.matcher = TOOL_MATCHER;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/** A PreToolUse entry that runs only `seisin hook`, on every tool. */
+function broadOurs(entry) {
+  const ours = Array.isArray(entry?.hooks) && entry.hooks.length > 0 &&
+    entry.hooks.every((h) => isOurs(h?.command));
+  return ours && (entry.matcher === "*" || entry.matcher === "" || entry.matcher === undefined);
+}
+
+/**
+ * Does this repo still run the hook on every tool call — the `"*"` matcher that
+ * versions before 0.5.0 installed? Correct, just slow: every Read, Glob and
+ * TodoWrite pays for a process start that answers nothing. `seisin wire` narrows
+ * it in place; this is how `check` knows to say so.
+ */
+export function broadlyWired(root) {
+  const file = join(root, SETTINGS);
+  if (!existsSync(file)) return false;
+  try {
+    const pre = JSON.parse(readFileSync(file, "utf8")).hooks?.PreToolUse;
+    return Array.isArray(pre) && pre.some(broadOurs);
+  } catch {
+    return false;                       // unreadable settings is reported elsewhere, if at all
+  }
+}
+
 export function wire(config) {
   const file = join(config.root, SETTINGS);
+  const how = hookCommand(config.root);
 
   // Merged, never replaced. Someone's hooks are their own and a tool that
   // overwrites them to add itself does not get a second chance.
@@ -76,24 +179,60 @@ export function wire(config) {
   }
 
   if (wired(config.root)) {
-    out(`\n  ${C.dim}already wired — ${SETTINGS} runs "seisin hook"${C.off}\n\n`);
+    // A bare `seisin hook` where no seisin is on PATH fails on every call
+    // without a word. Rewritten in place to the command that works here.
+    // Both repairs in one pass: an install from before 0.5.0 on a machine
+    // without seisin on PATH needs the command repointed AND the matcher
+    // narrowed, and returning after the first left it half-fixed.
+    const repointed = how.via !== "path" && repoint(settings, how.command);
+    // Wired before the matcher was narrowed: still correct, just slow, so
+    // `wired()` keeps saying yes and nobody is told to redo anything. Running
+    // `wire` again is the way to pick up the narrower one, in place.
+    const narrowed = narrow(settings);
+    if (repointed || narrowed) {
+      writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+      if (repointed)
+        out(`\n  ${C.green}repointed${C.off}  ${SETTINGS}\n  ${C.dim}"seisin hook" is not on your PATH, so it never ran. ${saysWhich(how)}.${C.off}\n\n`);
+      if (narrowed)
+        out(`\n  ${C.green}narrowed${C.off}  ${SETTINGS}\n` +
+          `  ${C.dim}PreToolUse now runs seisin's hook only for the tools it reads, not for every tool${C.off}\n\n`);
+      return { changed: true, file, ...(repointed && { how }) };
+    }
+    out(`\n  ${C.dim}already wired — ${SETTINGS} runs seisin's hook${C.off}\n\n`);
     return { changed: false, file };
   }
 
   settings.hooks ??= {};
-  for (const [ev, entries] of Object.entries(hookEntries())) {
+  for (const [ev, entries] of Object.entries(hookEntries(how.command))) {
     settings.hooks[ev] ??= [];
-    if (!JSON.stringify(settings.hooks[ev]).includes("seisin hook")) settings.hooks[ev].push(...entries);
+    if (!settings.hooks[ev].some((e) => (e?.hooks ?? []).some((h) => isOurs(h?.command)))) settings.hooks[ev].push(...entries);
   }
+  narrow(settings);                     // an older PreToolUse entry that was kept
 
   mkdirSync(join(config.root, ".claude"), { recursive: true });
   writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
 
   out(
     `\n  ${C.green}wired${C.off}  ${SETTINGS}\n` +
-    `  ${C.dim}the agent now runs "seisin hook" before each tool call, which is what fills${C.off}\n` +
-    `  ${C.dim}the log. Without it the boundary still holds — you just cannot see it work.${C.off}\n\n` +
-    `  ${C.dim}Commit this file if the rest of your team should get it too.${C.off}\n\n`
+    `  ${C.dim}the agent now runs seisin's hook before each tool call, which is what fills${C.off}\n` +
+    `  ${C.dim}the log. Without it the boundary still holds — you just cannot see it work.${C.off}\n` +
+    `  ${C.dim}${saysWhich(how)}.${C.off}\n\n` +
+    // Only in a repository: outside one there is nothing to commit it to.
+    (insideRepo(config.root)
+      ? how.via === "absolute"
+        ? `  ${C.dim}The command names a path on this machine; teammates should run seisin wire themselves.${C.off}\n\n`
+        : `  ${C.dim}Commit this file if the rest of your team should get it too.${C.off}\n\n`
+      : "")
   );
-  return { changed: true, file };
+  return { changed: true, file, how };
+}
+
+/** Replaces a bare `seisin hook` command with `command`. True if it changed anything. */
+function repoint(settings, command) {
+  let changed = false;
+  for (const entries of Object.values(settings.hooks ?? {}))
+    for (const e of Array.isArray(entries) ? entries : [])
+      for (const h of e?.hooks ?? [])
+        if (h?.command === "seisin hook") { h.command = command; changed = true; }
+  return changed;
 }

package/src/config.js

@@ -31,7 +31,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 +58,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 +98,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 +120,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 +143,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 +163,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 +270,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.
@@ -290,8 +311,19 @@ export function readIsolate(v) {
     `An unknown value cannot silently turn credential isolation off.`);
 }
 
-export function loadConfig(path) {
-  const parsed = parseToml(readFileSync(path, "utf8"));
+/**
+ * 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
@@ -353,7 +385,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 +399,17 @@ 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"),
     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"),
+    redact: readBoolean(own(runtime, "redact"), `${path}: runtime.redact`),
     scanIgnore: asArray(own(own(parsed, "scan"), "ignore"), "scan.ignore"),
+    protect: readProtect(own(parsed, "protect"), path),
     roles: {},
   };
 
@@ -432,6 +471,7 @@ export function loadConfig(path) {
       throw new Error(`${path}: roles.${name}.local_binding must be true or false, not ${JSON.stringify(localBinding)}`);
     const localPorts = readLocalPorts(own(r, "local_ports"), `${path}: roles.${name}.local_ports`);
     const mcp = readMcp(own(r, "mcp"), `${path}: roles.${name}.mcp`);
+    const controlFiles = readControlFiles(own(r, "control_files"), `${path}: roles.${name}.control_files`);
     out.roles[name] = {
       name,
       /**
@@ -505,6 +545,13 @@ 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,
       // 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
@@ -564,7 +611,7 @@ function readProviders(table, path) {
 /**
  * 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 +626,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 +650,123 @@ 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 },
+  runtime: { writes: true, isolate: true, redact: true },
+  scan: { ignore: true },
+  protect: { instructions: true },
+  notify: { url: true, url_file: true, format: 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", "keys", "key_mode", "env", "network", "never_writes", "local_binding", "local_ports", "mcp", "trustd", "control_files"];
+
+/**
+ * `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,
@@ -672,9 +834,9 @@ function readNeverWrites(value, where) {
  * 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) {