seisin 0.4.2 → 0.6.0

package/src/requests.js

@@ -1,39 +1,44 @@
 /**
- * The queue of permissions an agent asked for and cannot have yet.
+ * The queue of requests: what an agent asked for and cannot have yet.
  *
  * ── Two words, kept apart on purpose ──
- * **Refused** is what the boundary does. **Declined** is what a person does to
+ * **Denied** is what the boundary does. **Declined** is what a person does to
  * a request. They used to be one word in one command: an entry read `first
- * refused on src/api/x.ts` and `seisin deny` answered `refused frontend ✕
- * src/api/**`. One means the kernel said no, the other means you did, and a
- * reader had nothing to tell them apart by.
+ * refused on src/api/x.ts` and the command that declined it answered `refused
+ * frontend ✕ src/api/**`. One means the kernel said no, the other means you
+ * did, and a reader had nothing to tell them apart by. The file kept the
+ * boundary's word for a decline until 0.6.0; see migrateQueue.
  *
  * The entry says **asked** now, because refused was not always true. Asking for
- * a permission before reaching for it is reasonable, and nothing required a
+ * a path before reaching for it is reasonable, and nothing required a
  * denial to have happened first — so the queue could print a sentence about an
- * event that never occurred, in front of a person about to approve something.
- * `seisin run` drops any request the policy does not actually refuse; what is
+ * event that never occurred, in front of a person about to grant something.
+ * `seisin run` drops any request the policy does not actually deny; what is
  * left is "you cannot have this, and you asked", which holds whether the agent
  * tried or simply asked.
  *
  * A denial already contains everything a request needs — the hook knows the
- * role, the path and the owner — so the refusal leaves something behind that a
+ * role, the path and the owner — so the denial leaves something behind that a
  * person can act on in one command instead of in an editor. See
- * `docs/permission-requests.md` for why approving is deliberately not something
+ * `docs/requests.md` for why granting is deliberately not something
  * an agent can do.
  *
  * Append-only, beside the log, for the same reason: a decision that can be
- * rewritten is not evidence. A request that is granted or refused is not
+ * rewritten is not evidence. A request that is granted or declined is not
  * deleted — it is followed by a line saying what happened to it.
  */
-import { neverWrites, isGitMetadata, covers } from "./owners.js";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { neverWrites, isGitMetadata, covers, privateOwner } from "./owners.js";
+import { decideHandoff, chainOf, isKeyRequest } from "./handoff.js";
+import { protectedBy } from "./surface.js";
+import { appendFileSync, chmodSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
 import { STATE_DIR, tomlString } from "./layout.js";
 import { send } from "./spool.js";
-import { withLock } from "./log.js";
+import { withLock, readEntries } from "./log.js";
+import { loadConfig, policyId } from "./config.js";
 
-export const REQUESTS_NAME = "requests.jsonl";
+const REQUESTS_NAME = "requests.jsonl";
 
 export function requestsPath(root) {
   return join(root, STATE_DIR, REQUESTS_NAME);
@@ -57,7 +62,6 @@ export function keyOf({ role, action, target }) {
   return `${role}:${action}:${dir}`;
 }
 
-/** The glob a grant would add, derived from what was asked. */
 /**
  * A request's id as one shell word, for the commands seisin suggests.
  *
@@ -69,13 +73,23 @@ export function shellId(key) {
   return `'${String(key).replace(/'/g, `'\\''`)}'`;
 }
 
-export function grantFor({ action, target }) {
+/** The glob a grant would add, derived from what was asked. */
+export function grantFor({ action, target }, keyDir = null) {
   const t = typeof target === "string" ? target : "";
   // A key keeps its directory when it has one. Stripping it turned a request
   // for `shared/api.txt` into a grant of `api.txt`, which settingsFor then
-  // resolves against the FIRST key directory — so the person approves one file
+  // resolves against the FIRST key directory — so the person grants one file
   // and another one of the same name is what gets read.
-  if (action === "read") return t.includes("/") ? t : t.replace(/^.*\//, "");
+  //
+  // Except the first key directory itself, which is exactly the one a bare
+  // name resolves against: `.secrets/stripe.txt` is written `stripe.txt`, the
+  // way every hand-written key is. Granting the long form put two spellings of
+  // one key in the same file.
+  if (action === "read") {
+    const first = keyDir ? String(keyDir).replace(/^\.\/+/, "").replace(/\/+$/, "") : null;
+    if (first && t.startsWith(first + "/") && !t.slice(first.length + 1).includes("/")) return t.slice(first.length + 1);
+    return t.includes("/") ? t : t.replace(/^.*\//, "");
+  }
   const dir = t.split("/").slice(0, -1).join("/");
   return dir ? `${dir}/**` : t;
 }
@@ -84,7 +98,11 @@ function write(file, entry) {
   if (send("requests", entry)) return true;
   try {
     mkdirSync(dirname(file), { recursive: true });
-    appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...entry }) + "\n");
+    // The time is this process's, named after the spread so no entry sets it.
+    const now = new Date().toISOString();
+    // Under the queue's lock, as the log's lines are under the log's: the one
+    // rewrite the queue ever gets (migrateQueue) cannot then miss this line.
+    withLock(file, () => appendFileSync(file, JSON.stringify({ at: now, ...entry, at: now }) + "\n"));
     return true;
   } catch {
     // Same rule as the log: never take the agent down over bookkeeping.
@@ -92,15 +110,150 @@ function write(file, entry) {
   }
 }
 
-/** Records that a role asked for something the policy denies it. Safe to call
- *  on every denial; `seisin run` drops anything the policy does not refuse. */
-export function record(file, { role, action, target, owners }) {
-  return write(file, { kind: "asked", key: keyOf({ role, action, target }), role, action, target, owners: owners ?? [] });
+/**
+ * Who each request goes to, decided now (handoff.js), and whose it is.
+ *
+ * Every reader of the queue goes through here — `seisin requests`, the end of
+ * `seisin run`, the notification, the console, the MCP — so they cannot
+ * disagree about where a request goes, and none of them works it out on its
+ * own. `owners` is replaced by the decision's: the owners stored on the line
+ * are who owned the path when it was denied, which is evidence; who owns it
+ * now is the policy's answer, and that is the one shown. For a key it is who
+ * declares it — nobody writes `.secrets/`, and the queue used to say
+ * "(unowned)" about a key another role declares, right before a grant that
+ * would share it.
+ *
+ * `handoff` is the decision as decideHandoff returns it: `type` is route,
+ * human, resolved, cycle or depth, and a route names `role`. It is the field
+ * something outside seisin reads to act on; seisin itself starts nothing.
+ */
+export function withHandoffs(config, queue, revision = policyId(config)) {
+  // Reading the queue must not be the thing that fails: a caller holding only
+  // a root gets every request decided as nobody's, which is what it can know.
+  const policy = config?.roles ? config : { ...config, roles: {} };
+  for (const r of queue) {
+    if (typeof r.role !== "string" || typeof r.target !== "string") continue;
+    r.ownersThen = r.owners;
+    r.handoff = decideHandoff({ request: r, config: policy, chain: chainOf(r), revision });
+    r.owners = r.handoff.owners ?? [];
+    if (isKeyRequest(config, r)) r.declared = true;
+  }
+  // Each request's chain is named by the request it started from. Where a
+  // later request in that chain stopped — a cycle, too deep, a person's call —
+  // the one it started from says so: seisin cannot know whether the role that
+  // took it finished, but it knows the chain did not end in a handoff.
+  const stoppedIn = new Map();
+  for (const q of queue) {
+    const id = q.chain?.id;
+    if (!id || id === q.key || !["cycle", "depth", "human"].includes(q.handoff?.type)) continue;
+    stoppedIn.set(id, [...(stoppedIn.get(id) ?? []), q.key]);
+  }
+  for (const r of queue) if (stoppedIn.has(r.key)) r.chainStopped = stoppedIn.get(r.key);
+  return queue;
+}
+
+/**
+ * The pending queue as a person and an agent read it: keys in the policy's own
+ * form, each request's handoff decided against the policy as it stands, and —
+ * given the log — the ones the role stopped asking for marked. `readOnly` is
+ * pending()'s: the MCP server reads the queue and never migrates it.
+ */
+export function queueOf(config, history = null, { readOnly = false } = {}) {
+  const queue = withHandoffs(config, pending(requestsPath(config.root), { keyDirs: config.keyDirs, readOnly }));
+  return history ? markStale(queue, history) : queue;
+}
+
+/**
+ * The queue as data: what `seisin requests --json` prints and `seisin_requests`
+ * returns, one shape for both.
+ *
+ * `handoff` is the field to act on. It is decided by seisin from the policy as
+ * it stands (handoff.js) and carried whole, so whatever reads it — an agent, a
+ * script that starts roles — is reading a decision and not making one: a route
+ * names the role, and `seisin run <role> --handoff <id>` refuses any other.
+ */
+export function queueData(queue) {
+  return {
+    pending: queue.map((r, i) => ({
+      number: i + 1, id: r.key, role: r.role, action: r.action, target: r.target,
+      wants: r.grant, ownedBy: r.owners, asked: r.times, lastAsked: r.last,
+      handoff: r.handoff ?? null,
+      ...(r.attempt ? { attempt: r.attempt } : {}),
+      ...(r.chainStopped ? { chainStopped: r.chainStopped } : {}),
+      ...(r.stale ? { stale: `not asked again in ${r.stale.runs} runs of ${r.role} since` } : {}),
+    })),
+  };
 }
 
-/** Records a decision. `by` is always a person; there is no other caller. */
-export function settle(file, key, decision, reason = "") {
-  return write(file, { kind: decision, key, reason });
+/**
+ * Records that a role asked for something the policy denies it. Safe to call
+ * on every denial; `seisin run` drops anything the policy does not deny.
+ *
+ * `chain` is set only by a run started for a handoff (`seisin run --handoff`),
+ * from the decision the parent checked before starting it — never from
+ * anything the sandbox sent. A line without one starts a chain of its own.
+ */
+export function record(file, { role, action, target, owners, chain = null }) {
+  return write(file, {
+    kind: "asked", key: keyOf({ role, action, target }), role, action, target, owners: owners ?? [],
+    ...(chain && { chain: { id: chain.id, depth: chain.depth, visited: chain.visited } }),
+  });
+}
+
+/**
+ * Records a decision. `by` is always a person; there is no other caller.
+ *
+ * `only` is the one file a grant covered when the person chose it over the
+ * folder the request is keyed by. The key stays the folder's, so the queue
+ * needs to know: a later ask for a sibling is a new question, not this one
+ * asked again (see reduce).
+ */
+export function settle(file, key, decision, reason = "", { only = null } = {}) {
+  return write(file, { kind: decision, key, reason, ...(only ? { only } : {}) });
+}
+
+/**
+ * The same request, granting the one file it was asked over instead of the
+ * folder it is keyed by.
+ *
+ * Writes only: a key is already one file. The grant is the target exactly as
+ * the request carries it, so it reaches the policy as a literal path and goes
+ * through the same refuseIfBarred and applyGrant as the folder does.
+ */
+export function asFileGrant(request) {
+  if (request.action === "read")
+    throw new Error(`${request.key} is a key, and a key is already one file — grant it without --file`);
+  if (request.action !== "write")
+    throw new Error(`only a write can be granted as one file, and ${request.key} is a ${request.action}`);
+  const t = typeof request.target === "string" ? request.target : "";
+  if (!t || t.endsWith("/") || t.includes("*"))
+    throw new Error(`${JSON.stringify(t)} is not one file — grant the folder instead`);
+  return { ...request, grant: t, only: t };
+}
+
+/**
+ * The agent a role ran last, as its last canary line recorded it, or null.
+ *
+ * Asked for one reason: a literal file in `writes` is useless to Claude Code,
+ * whose Write and Edit save to a temporary beside the file and rename over it
+ * (docs/first-day.md). Null when the role never ran or ran before the canary
+ * line carried the agent — the caller then says it conditionally.
+ */
+export function lastAgentOf(entries, role) {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e?.event === "canary" && e.role === role) return typeof e.agent === "string" ? e.agent : null;
+  }
+  return null;
+}
+
+/** One line on what a file-only grant does to a role that runs Claude Code, or "". */
+export function fileOnlyNote(role, agent) {
+  const why = "Claude Code's Write and Edit save to a temporary beside the file and rename it over, " +
+    "and the temporary is outside a one-file grant (EPERM)";
+  if (agent === "claude") return `${role} runs Claude Code: ${why} — grant the folder if it edits this file.`;
+  if (agent) return "";
+  return `If ${role} runs Claude Code, a one-file grant will not let it edit: ${why}.`;
 }
 
 /**
@@ -115,6 +268,10 @@ export function settle(file, key, decision, reason = "") {
  *
  * It exists so that a refusal to run cannot be invisible. Admission may
  * postpone work; it may not make work disappear from the queue a person reads.
+ *
+ * `seisin run --handoff` writes one when it starts the receiver; whatever
+ * else starts roles writes one when it holds one back. It reaches a request
+ * as `attempt`, beside the decision, and never as `state`.
  */
 export function recordHandoff(file, key, decision = {}) {
   const { type, role, limit, max, reason, depth, chainId, revision } = decision;
@@ -135,30 +292,79 @@ export function recordHandoff(file, key, decision = {}) {
  * it was asked and what was decided.
  *
  * Reduced from the whole file rather than kept as state, so the file stays the
- * only thing that has to be correct.
+ * only thing that has to be correct. The reduction is remembered for as long as
+ * the file is unchanged (same inode, size and mtime): the console asks every
+ * two seconds, and re-parsing a 2 MB queue each time to find it had not moved
+ * was most of the cost of asking. Each call gets its own copies, so a caller
+ * marking entries (markStale) cannot mark the next caller's.
  */
-export function pending(file, { includeSettled = false } = {}) {
-  if (!existsSync(file)) return [];
-  const byKey = new Map();
+let reduced = null;   // { file, ino, size, mtimeMs, all }
 
-  for (const line of readFileSync(file, "utf8").split("\n")) {
-    if (!line.trim()) continue;
-    let e;
-    try {
-      e = JSON.parse(line);
-    } catch {
-      continue; // a half-written line from a killed process is not an error
+/**
+ * `readOnly` is for the MCP server, which opens nothing for writing: a queue
+ * that still needs migrating is an error there, never a rewrite (migrateQueue).
+ */
+export function pending(file, { includeSettled = false, keyDirs = null, readOnly = false } = {}) {
+  let st;
+  try { st = statSync(file); } catch { return []; }
+  let all;
+  if (reduced && reduced.file === file && reduced.ino === st.ino && reduced.size === st.size && reduced.mtimeMs === st.mtimeMs) {
+    all = reduced.all;
+  } else {
+    let entries = readEntries(file);
+    // Twice at most: a line an older seisin appended while the first pass ran
+    // is caught by the second; one still there after that is an error, not a guess.
+    for (let pass = 0; pass < 2 && entries.some(isOldDecline); pass++) {
+      if (readOnly) throw unmigrated(file, entries.filter(isOldDecline).length);
+      migrateQueue(file);
+      st = statSync(file);
+      entries = readEntries(file);
     }
+    if (entries.some(isOldDecline)) throw unmigrated(file, entries.filter(isOldDecline).length);
+    all = reduce(entries);
+    reduced = { file, ino: st.ino, size: st.size, mtimeMs: st.mtimeMs, all };
+  }
+  // The grant is re-derived with the policy's first key directory when the
+  // caller has one, so a key is proposed in the form hand-written keys use.
+  const first = keyDirs?.[0] ?? null;
+  const copies = all.map((r) => (first && r.action === "read" ? { ...r, grant: grantFor(r, first) } : { ...r }));
+  return includeSettled ? copies : copies.filter((r) => r.state === "pending");
+}
+
+function reduce(entries) {
+  const byKey = new Map();
+
+  for (const e of entries) {
     if (!e.key) continue;
 
     if (e.kind === "asked") {
       const seen = byKey.get(e.key);
-      if (seen) { seen.times++; seen.last = e.at; continue; }
-      byKey.set(e.key, {
+      /**
+       * A grant of one file answered that file, not the folder the key names.
+       * A sibling asked after it is a new question: reopened with that target,
+       * so it reaches the queue instead of folding into a settled request that
+       * nobody reads again. The same file asked again folds as before.
+       */
+      if (seen && seen.state === "granted" && seen.only?.length && typeof e.target === "string" &&
+          !seen.only.includes(e.target)) {
+        Object.assign(seen, {
+          target: e.target, owners: e.owners ?? [], grant: grantFor(e),
+          times: 1, first: e.at, last: e.at, state: "pending", reason: "",
+        });
+        delete seen.decided;
+        delete seen.chain;
+        delete seen.attempt;
+        keepChain(seen, e);
+        continue;
+      }
+      if (seen) { seen.times++; seen.last = e.at; keepChain(seen, e); continue; }
+      const fresh = {
         key: e.key, role: e.role, action: e.action, target: e.target,
         owners: e.owners ?? [], grant: grantFor(e),
         times: 1, first: e.at, last: e.at, state: "pending", reason: "",
-      });
+      };
+      keepChain(fresh, e);
+      byKey.set(e.key, fresh);
       continue;
     }
     const seen = byKey.get(e.key);
@@ -169,10 +375,12 @@ export function pending(file, { includeSettled = false } = {}) {
      *
      * Without this branch the catch-all below would set state = "handoff" and a
      * throttled attempt would drop out of the pending queue — the exact silent
-     * disappearance the attempt is recorded to prevent.
+     * disappearance the attempt is recorded to prevent. It is `attempt`, not
+     * `handoff`: the decision is recomputed on every read (withHandoffs), and
+     * what was tried is a different fact from where it goes.
      */
     if (e.kind === "handoff") {
-      seen.handoff = {
+      seen.attempt = {
         outcome: e.outcome, role: e.role, limit: e.limit, max: e.max,
         reason: e.reason, depth: e.depth, chainId: e.chainId, at: e.at,
       };
@@ -180,16 +388,147 @@ export function pending(file, { includeSettled = false } = {}) {
     }
 
     seen.state = e.kind; seen.reason = e.reason ?? ""; seen.decided = e.at;
+    // Kept across reopenings: every file granted one at a time stays answered.
+    if (e.kind === "granted") {
+      if (typeof e.only === "string") seen.only = [...(seen.only ?? []), e.only];
+      else delete seen.only;
+    }
+  }
+
+  return [...byKey.values()];
+}
+
+/**
+ * A decline as seisin wrote it before 0.6.0: `kind: "denied"`.
+ *
+ * A person declines; the boundary denies (docs/glossary.md). The queue stored
+ * the boundary's word for the person's answer, and 0.6.0 stores "declined".
+ * Nothing reads the old value as a decline: a queue that holds one is
+ * rewritten once by migrateQueue, or refused where it cannot be.
+ */
+const OLD_DECLINE = "denied";
+
+function isOldDecline(e) {
+  return e.kind === OLD_DECLINE && typeof e.key === "string" && e.verdict === undefined;
+}
+
+function unmigrated(file, n) {
+  return Object.assign(new Error(
+    `${file} holds ${n} decline${n === 1 ? "" : "s"} written by seisin before 0.6.0 ` +
+    `as "kind":"denied", which this version does not read.\n` +
+    `  Run \`seisin requests\` once from a terminal: it rewrites them as "declined" and ` +
+    `keeps the original beside the queue as requests.jsonl.pre-0.6.0.`), { code: "EQUEUEFORMAT" });
+}
+
+/** One chunk of the queue with every old decline renamed; anything else, byte for byte. */
+function renameDeclines(text) {
+  let n = 0;
+  const lines = text.split("\n");
+  // The last piece has no newline after it: a line still being written, or
+  // nothing. It is copied as it is, and a later open migrates it if it must.
+  for (let i = 0; i < lines.length - 1; i++) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch { continue; }
+    if (!e || typeof e !== "object" || !isOldDecline(e)) continue;
+    lines[i] = JSON.stringify({ ...e, kind: "declined" });
+    n++;
   }
+  return { text: lines.join("\n"), n };
+}
 
-  const all = [...byKey.values()];
-  return includeSettled ? all : all.filter((r) => r.state === "pending");
+/** Bytes of `fd` from `from` to its end, as it is now. */
+function readFrom(fd, from) {
+  const size = fstatSync(fd).size;
+  const buf = Buffer.alloc(Math.max(0, size - from));
+  let got = 0;
+  while (got < buf.length) {
+    const n = readSync(fd, buf, got, buf.length - got, from + got);
+    if (n === 0) break;
+    got += n;
+  }
+  return buf.subarray(0, got);
+}
+
+/**
+ * Rewrite the old declines of a queue as "declined", once. Returns how many.
+ *
+ * The one place the queue is not appended to, and why that is allowed is in
+ * docs/decisions.md: it renames one stored value, keeps every line, its order
+ * and its time, and copies the file as it was to `requests.jsonl.pre-0.6.0`
+ * before touching it, so the evidence is still there, word for word.
+ *
+ * Every line seisin 0.6.0 appends takes the queue's lock (write), and so does
+ * this, so none of those can land between the read and the rename. A run
+ * started by an older seisin and still going appends without it; for that one
+ * the rewrite follows the old file instead of trusting the lock: it works from
+ * one open descriptor, copies what was appended while it worked, renames, and
+ * keeps copying what still lands in the old file until it has been quiet for
+ * FOLLOW_QUIET_MS. Such an append opened the file before the rename and writes
+ * microseconds later; the wait is a hundred times that.
+ */
+const FOLLOW_QUIET_MS = 50;
+
+export function migrateQueue(file) {
+  return withLock(file, () => {
+    let fd;
+    try { fd = openSync(file, "r"); } catch (e) { if (e.code === "ENOENT") return 0; throw e; }
+    try {
+      const before = readFrom(fd, 0);
+      let read = before.length;
+      const first = renameDeclines(before.toString("utf8"));
+      if (!first.n) return 0;
+      let n = first.n;
+      const mode = fstatSync(fd).mode & 0o777;
+      let backup = `${file}.pre-0.6.0`;
+      try { writeFileSync(backup, before, { flag: "wx", mode }); }
+      catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        backup = `${file}.pre-0.6.0.${Date.now()}`;
+        writeFileSync(backup, before, { flag: "wx", mode });
+      }
+      const tmp = join(dirname(file), `.requests.migrate-${randomBytes(8).toString("hex")}`);
+      writeFileSync(tmp, first.text, { flag: "wx", mode });
+      try {
+        const more = readFrom(fd, read);
+        read += more.length;
+        const tail = renameDeclines(more.toString("utf8"));
+        n += tail.n;
+        appendFileSync(tmp, tail.text);
+        renameSync(tmp, file);
+      } catch (e) { try { unlinkSync(tmp); } catch {} throw e; }
+      const until = Date.now() + 2000;
+      for (let quiet = Date.now(); Date.now() - quiet < FOLLOW_QUIET_MS && Date.now() < until;) {
+        const late = readFrom(fd, read);
+        if (!late.length) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5); continue; }
+        read += late.length;
+        quiet = Date.now();
+        const tail = renameDeclines(late.toString("utf8"));
+        n += tail.n;
+        appendFileSync(file, tail.text);
+      }
+      return n;
+    } finally { closeSync(fd); }
+  });
+}
+
+/**
+ * The chain a request was asked in, kept as the deepest one seen.
+ *
+ * One request (same role, action, folder) can be asked by a run that was
+ * handed work and by one that was not. The deeper chain is the one that knows
+ * more of where the work has been, so it is the one kept: dropping it on a
+ * later plain ask would let the work be handed back to a role it came from.
+ */
+function keepChain(seen, e) {
+  const c = e.chain;
+  if (!c || typeof c !== "object" || !Number.isInteger(c.depth)) return;
+  if (!seen.chain || c.depth > seen.chain.depth) seen.chain = c;
 }
 
 /**
  * How many runs of the role, after the last time it asked, make a request old.
  *
- * A request is recorded again on every refusal, so one the role still needs
+ * A request is recorded again on every denial, so one the role still needs
  * keeps a fresh `last`. One whose need went away — the work moved somewhere the
  * role may write, or the task ended — stops being asked while the role keeps
  * running. Three runs is enough to say "not since" and few enough that a queue
@@ -233,7 +572,7 @@ export function runsAfter(entries, since, gapMs = RUN_GAP_MS) {
  * reordering would shift the numbers `grant <n>` is typed against while
  * nobody decided anything. The mark says what is true — the role ran N times
  * since and did not ask again — and leaves the rest to whoever reads it.
- * `entries` are log lines (`read(logPath(root))`); `now` is for the tests.
+ * `entries` are log lines (`read(logPath(root))`).
  */
 export function markStale(queue, entries, { runs = STALE_RUNS, gapMs = RUN_GAP_MS } = {}) {
   const byRole = new Map();             // role -> its log lines
@@ -248,35 +587,13 @@ export function markStale(queue, entries, { runs = STALE_RUNS, gapMs = RUN_GAP_M
   return queue;
 }
 
-/**
- * Adds a granted glob to a role in the config text, with its provenance.
- *
- * Edits the text rather than re-emitting the file, because a config someone
- * wrote has comments and an order that mean something, and a tool that
- * reformats it on every grant is a tool people stop letting near it.
- */
-/**
- * Adds a granted glob to a role in the config text, with its provenance.
- *
- * Edits the text rather than re-emitting the file, because a config someone
- * wrote has comments and an order that mean something, and a tool that
- * reformats it on every grant is a tool people stop letting near it.
- *
- * The edit is bounded to the role's own section, and that is not tidiness. The
- * first version searched from the role header to the next `writes =` anywhere
- * in the file, so approving for a role that had no `writes` line wrote the
- * grant into the NEXT role — with a comment saying who it was for. A human
- * approved one thing and the file recorded another. In a permission tool that
- * is the worst possible bug, and it is not exotic: a role with only `keys`
- * declared is an ordinary config.
- */
 /**
  * Refuses a grant that `never_writes` would cancel, before anything is written.
  *
  * A request filed before the subtraction existed can still be in the queue.
- * Approving it would add the path to `writes` and change nothing — denyWrite
+ * Granting it would add the path to `writes` and change nothing — denyWrite
  * wins — so the person would believe they granted something the kernel still
- * refuses. The two keys contradict each other, and which one should win is the
+ * denies. The two settings contradict each other, and which one should win is the
  * decision; seisin will not make it by writing one of them silently.
  */
 export function refuseIfBarred(config, request) {
@@ -288,11 +605,45 @@ export function refuseIfBarred(config, request) {
       `${request.target} is under never_writes of ${request.role} ("${hit}"), which wins over ` +
       `writes. Granting it would change nothing. If the subtraction is wrong, remove that ` +
       `entry from [roles.${request.role}]; otherwise decline this request.`);
+  // A protected file stays denied whatever `writes` says: the kernel is given
+  // it as a deny, and explain answers the same. Granting `web/.vscode/**`
+  // used to add the line and change nothing — a grant that reads as done.
+  const guard = protectedBy(config, request.target, { role: request.role });
+  if (guard)
+    throw new Error(guard.family
+      ? `${request.target} is protected (${guard.why}). A grant cannot open it: ${request.role} ` +
+        `writes it only if the policy hands it the family, control_files = ["${guard.family}"] ` +
+        `under [roles.${request.role}], inside its own territory. Edit the policy if that is ` +
+        `what you mean; otherwise decline this request.`
+      : `${request.target} is protected (${guard.why}) and no role can ever be granted it. ` +
+        `Decline this request.`);
+  // Another role's private folder: the kernel denies it to every role but its
+  // owner, however wide `writes` gets, so a grant would read as done and open nothing.
+  const mine = privateOwner(config, request.target);
+  if (mine && mine.role !== request.role)
+    throw new Error(
+      `${request.target} is in ${mine.role}'s private folder (private = ["${mine.entry}"]): every other role ` +
+      `is denied it, so a grant to ${request.role} would change nothing. Decline this request, or move the ` +
+      `folder out of ${mine.role}'s private list if it should not be private.`);
   // Only a repository the role does not write: its own `.git` is its own business.
   if (isGitMetadata(request.target) && !(role?.writes ?? []).some((g) => covers(g, request.target)))
     throw new Error(
       `${request.target} is git's own bookkeeping, not a territory: granting it lets ${request.role} ` +
       `rewrite another owner's history. Decline it; a role that needs to commit gets a worktree of its own.`);
+  /**
+   * The whole repository is never granted from a request. A request is one
+   * denied path; the grant it derives is that path's folder, and at the root
+   * that folder is everything — every other role's territory included. A role
+   * that should write the whole repo gets `writes = ["**"]` from a person
+   * editing the policy, not from approving one denial.
+   */
+  const grant = request.grant ?? grantFor(request);
+  const g = String(grant).replace(/^\.\/+/, "").replace(/\/+$/, "");
+  if (["", ".", "*", "**", "./**"].includes(g) || /^(\*\*\/)*\*\*$/.test(g))
+    throw new Error(
+      `this request would grant ${request.role} the whole repository ("${grant}"), every other ` +
+      `role's territory included. A request cannot do that: decline it, and if ${request.role} really ` +
+      `should write everything, edit [roles.${request.role}] writes by hand.`);
 }
 
 /**
@@ -307,43 +658,110 @@ export function refuseIfBarred(config, request) {
  * so a crash mid-write cannot leave a half-written, partly-privileged policy.
  *
  * `mutate(toml)` returns `{ toml, changed }`. Nothing is written when unchanged.
+ * `after(result)` runs once the file is written, still under the lock — for
+ * the queue line that records the decision, so a decision and its edit are
+ * one step to anyone else taking this lock.
  */
-export function editPolicy(config, mutate, { waitMs = 10000 } = {}) {
-  return withLock(config.path, () => {
+export function editPolicy(config, mutate, { waitMs = 10000, after = null } = {}) {
+  return withLock(policyLockBase(config), () => {
     const before = readFileSync(config.path, "utf8");
     const result = mutate(before);
     if (result.changed) {
-      const tmp = `${config.path}.tmp-${process.pid}`;
-      writeFileSync(tmp, result.toml);
-      renameSync(tmp, config.path);
+      // A decision cannot settle against text the next run cannot load.
+      loadConfig(config.path, result.toml);
+      writePolicy(config, result.toml);
     }
+    after?.(result);
     return result;
   }, { waitMs });
 }
 
+/**
+ * Where the policy's lock lives: inside `.seisin/`, never beside the policy.
+ *
+ * It was `seisin.toml.lock`, next to the file. Any role that writes the repo
+ * root — every `--observe` run, any `writes = ["**"]` — could create that name
+ * holding a live pid and hold up every grant and every decline for as long as
+ * it liked. `.seisin/` is denied to every role (surface.js, parentInputs), so
+ * nothing confined can hold this one. withLock adds the `.lock`.
+ */
+export function policyLockBase(config) {
+  const dir = join(config.root, STATE_DIR);
+  mkdirSync(dir, { recursive: true });
+  return join(dir, "policy");
+}
+
+/**
+ * Write the policy through a temp file that nobody could have prepared.
+ *
+ * The temp was `seisin.toml.tmp-<pid>` beside the policy: a predictable name,
+ * in a directory roles can write, opened by writeFileSync — which follows a
+ * symlink. A role could plant that name as a link into its own territory, and
+ * the next grant made the policy itself a symlink the role could rewrite.
+ * Now the temp sits in `.seisin/`, has a random name, and is opened with `wx`
+ * (O_CREAT|O_EXCL), which refuses anything already there, a link included.
+ *
+ * A `.seisin/` on another filesystem (a symlink a person made) cannot be
+ * renamed across; then the temp goes beside the policy, still random and still
+ * exclusive, which is what defeats a planted name.
+ */
+function writePolicy(config, text) {
+  const mode = statSync(config.path).mode & 0o777;
+  const name = `seisin.toml.tmp-${randomBytes(12).toString("hex")}`;
+  const stateTmp = join(config.root, STATE_DIR, name);
+  writeFileSync(stateTmp, text, { flag: "wx", mode });
+  try {
+    chmodSync(stateTmp, mode);
+    renameSync(stateTmp, config.path);
+    return;
+  } catch (e) {
+    try { unlinkSync(stateTmp); } catch {}
+    if (e.code !== "EXDEV") throw e;
+  }
+  const near = join(dirname(config.path), `.${name}`);
+  writeFileSync(near, text, { flag: "wx", mode });
+  try { chmodSync(near, mode); renameSync(near, config.path); }
+  catch (e) { try { unlinkSync(near); } catch {} throw e; }
+}
+
+/**
+ * Adds a granted glob to a role in the config text, with its provenance.
+ *
+ * Edits the text rather than re-emitting the file, because a config someone
+ * wrote has comments and an order that mean something, and a tool that
+ * reformats it on every grant is a tool people stop letting near it.
+ *
+ * The edit is bounded to the role's own section, and that is not tidiness. The
+ * first version searched from the role header to the next `writes =` anywhere
+ * in the file, so granting for a role that had no `writes` line wrote the
+ * grant into the NEXT role — with a comment saying who it was for. A person
+ * granted one thing and the file recorded another. In a permission layer that
+ * is the worst possible bug, and it is not exotic: a role with only `keys`
+ * declared is an ordinary config.
+ */
 export function applyGrant(toml, request, note = "") {
   const field = request.action === "read" ? "keys" : "writes";
-  const header = new RegExp(`^\\[roles\\.${escapeRe(request.role)}\\]\\s*$`, "m");
+  const header = new RegExp(`^[ \\t]*\\[roles\\.${escapeRe(request.role)}\\][ \\t\\r]*(?:#[^\\n]*)?$`, "m");
   const at = header.exec(toml);
   if (!at) throw new Error(`no [roles.${request.role}] section to grant into`);
 
   // The section runs from its header to the next table header, or to the end.
   const from = at.index + at[0].length;
-  const next = /^\[[^\]]+\]\s*$/m.exec(toml.slice(from));
+  const next = /^[ \t]*\[[A-Za-z0-9_.\-]+\][ \t\r]*(?:#[^\n]*)?$/m.exec(toml.slice(from));
   const to = next ? from + next.index : toml.length;
   const section = toml.slice(from, to);
 
-  const open = new RegExp(`^${field}\\s*=\\s*\\[`, "m").exec(section);
+  const open = new RegExp(`^[ \\t]*${field}[ \\t]*=[ \\t]*\\[`, "m").exec(section);
   if (!open)
     throw new Error(
       `[roles.${request.role}] has no ${field} list to grant into. ` +
-      `Add \`${field} = []\` to that section first — seisin will not write it into another role's block.`
+      `Add \`${field} = []\` to that section first — seisin will not write it into another role's table.`
     );
 
   // The subset has no escapes, so a value carrying a quote or a newline cannot
   // be written down at all. The strict parser would reject the result rather
   // than widen anything — but leaving someone with a config that no longer
-  // loads, after they approved something, is its own kind of broken.
+  // loads, after they granted something, is its own kind of broken.
   tomlString(request.grant);   // refuses what the format cannot hold
 
   const start = open.index + open[0].length;
@@ -355,9 +773,9 @@ export function applyGrant(toml, request, note = "") {
    *
    * The list used to be re-written from every quoted string between its
    * brackets — comments included. `"src/web/**",  # was "src/**"` came back as
-   * two grants, so approving anything also granted what a comment mentioned,
-   * and the reason an approver typed (quoted in the provenance comment) became
-   * a path on the next approval. Every earlier provenance comment was lost on
+   * two grants, so granting anything also granted what a comment mentioned,
+   * and the reason a person typed (quoted in the provenance comment) became
+   * a path on the next grant. Every earlier provenance comment was lost on
    * the way. Now the items are the strings outside comments, what is there is
    * left as it is, and the new entry goes last. The reason is set off with
    * «», never a double quote, so no older reader can take it for a value.
@@ -369,7 +787,8 @@ export function applyGrant(toml, request, note = "") {
   }
   const stamp = `# granted ${new Date().toISOString().slice(0, 10)} · asked ${request.times}×` +
                 `${note ? ` · «${cleanReason(note)}»` : ""}`;
-  const edited = section.slice(0, start) + `${inner}\n  "${request.grant}"   ${stamp}\n]` + section.slice(list.end + 1);
+  const eol = toml.includes("\r\n") ? "\r\n" : "\n";
+  const edited = section.slice(0, start) + `${inner}${eol}  "${request.grant}"   ${stamp}${eol}]` + section.slice(list.end + 1);
   return { toml: toml.slice(0, from) + edited + toml.slice(to), changed: true };
 }
 
@@ -401,14 +820,14 @@ function scanList(text, start) {
 }
 
 /**
- * The approver's own words, made safe to put in a config file.
+ * The reason a person typed, made safe to put in a config file.
  *
  * A reason is free text typed by a person, and a person can be talked into
  * typing something — "paste this as the reason" is a plausible thing for an
  * agent to suggest. Newlines in a comment would end the comment, and what
  * follows is parsed as TOML. The strict parser rejects the result rather than
  * widening anything, so the worst case is a config that no longer loads, but a
- * permission file that can be broken by a sentence is still broken.
+ * policy that can be broken by a sentence is still broken.
  */
 export function cleanReason(s) {
   return String(s ?? "")