seisin 0.4.0 → 0.5.0

package/src/render.js

@@ -25,6 +25,17 @@ export const C =
       }
     : { dim: "", b: "", off: "", red: "", green: "", yellow: "", blue: "" };
 
+/**
+ * A value chosen by an agent (a target, a grant, an id) made safe to print.
+ *
+ * `target` and the id built from it are strings the agent picked, and they were
+ * written to the terminal raw. Terminal escape sequences (ESC, CR, other C0
+ * controls) let such a string repaint the line a person reads before approving.
+ * On disk they are already JSON-escaped; this is for the screen. Stripped, not
+ * rendered, so what shows is the literal path with the control bytes removed.
+ */
+export const safe = (s) => String(s ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+
 export const out = (s) => process.stdout.write(s);
 export const err = (s) => process.stderr.write(s);
 
@@ -56,8 +67,16 @@ export function collapseSidecars(paths) {
   return out;
 }
 
-/** The `check` report, as text. Takes the object `inspect()` returns. */
-export function renderReport(report) {
+/**
+ * The `check` report, as text. Takes the object `inspect()` returns.
+ *
+ * The map and one line per warning first; the paragraphs behind `verbose`.
+ * On a three-role repo the full report ran to forty lines of explanation under
+ * a six-line map, and the one warning a person could act on sat in the middle.
+ * Nothing is dropped: the protected paths, each warning's reason and the
+ * standing limits are one flag away, and the footer says how many.
+ */
+export function renderReport(report, { verbose = true } = {}) {
   const lines = [`\n${C.b}${report.where}${C.off}\n\n`];
   const width = Math.max(...report.roles.map((r) => r.name.length), 4);
 
@@ -90,10 +109,10 @@ export function renderReport(report) {
   // What the kernel refuses inside a territory, and why. Shown because each one
   // takes something from a territory as written; capped because a monorepo has
   // a hooks directory per package and the reader needs the shape, not all 200.
-  if (report.protected?.length) {
+  if (report.protected?.length && verbose) {
     const root = report.where ? report.where.replace(/\/[^/]*$/, "/") : "";
     const show = (p) => (root && p.startsWith(root) ? p.slice(root.length) : p.replace(/^\/Users\/[^/]+|^\/home\/[^/]+/, "~"));
-    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, refused anyway: something outside the box runs or reads it${C.off}\n`);
+    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, denied anyway: something outside the sandbox runs or reads it${C.off}\n`);
     const LIMIT = 12;
     for (const e of report.protected.slice(0, LIMIT)) {
       const who = e.roles.length > 3 ? `${e.roles.slice(0, 3).join(", ")} +${e.roles.length - 3}` : e.roles.join(", ");
@@ -104,6 +123,18 @@ export function renderReport(report) {
     lines.push("\n");
   }
 
+  if (!verbose) {
+    for (const w of report.warnings) lines.push(`  ${C.yellow}${w.headline}${C.off}\n`);
+    if (report.warnings.length) lines.push("\n");
+    const more = [
+      report.protected?.length ? `${report.protected.length} protected path(s)` : "",
+      report.warnings.some((w) => w.detail) ? "why each warning matters" : "",
+      report.limits?.length ? `${report.limits.length} standing limit(s)` : "",
+    ].filter(Boolean);
+    if (more.length) lines.push(`  ${C.dim}seisin check --verbose: ${more.join(", ")}${C.off}\n\n`);
+    return lines.join("");
+  }
+
   for (const w of report.warnings) {
     lines.push(`  ${C.yellow}${w.headline}${C.off}\n`);
     if (w.detail) lines.push(`  ${C.dim}${w.detail}${C.off}\n`);
@@ -125,7 +156,7 @@ export function renderReport(report) {
 /** The `explain` answer, as text. Takes what `owners.explain()` returns. */
 export function renderVerdict(role, action, target, verdict) {
   const head = verdict.allowed ? `${C.green}allowed${C.off}` : `${C.yellow}denied${C.off}`;
-  return `\n  ${head}  ${C.b}${role}${C.off} ${action} ${target}\n  ${C.dim}${verdict.reason}${C.off}\n\n`;
+  return `\n  ${head}  ${C.b}${role}${C.off} ${action} ${safe(target)}\n  ${C.dim}${safe(verdict.reason)}${C.off}\n\n`;
 }
 
 /* ── the log ──────────────────────────────────────────────────────────── */
@@ -149,7 +180,7 @@ export function renderEntry(e) {
   // about a run, a reader needs to know which line is which without going to
   // the file — so the one that carries more weight is the one that is marked.
   const from = e.source === "kernel" ? `  ${C.dim}[kernel]${C.off}` : "";
-  return `  ${C.dim}${(e.at ?? "").slice(11, 19)}${C.off}  ${mark}  ${C.b}${e.role}${C.off} ${e.action} ${e.target}${owners}${from}\n`;
+  return `  ${C.dim}${(e.at ?? "").slice(11, 19)}${C.off}  ${mark}  ${C.b}${e.role}${C.off} ${e.action} ${safe(e.target)}${owners}${from}\n`;
 }
 
 /* ── the scan ─────────────────────────────────────────────────────────── */
@@ -166,16 +197,40 @@ export function renderScan(result, keyDirs) {
   const { certain, review, skipped, truncated } = result;
   const links = result.links ?? [];
   const where = keyDirs.length ? keyDirs.join(", ") : `${C.yellow}nowhere — [keys] dir is unset${C.off}`;
-  const lines = [`\n  ${C.dim}protected: ${where}${C.off}\n\n`];
+  const lines = [`\n  ${C.dim}protected: ${where}${C.off}\n`];
+  // Scoped to the territories: say where it looked, and how to look everywhere.
+  if (result.scope) {
+    const shown = result.scope.slice(0, 10).map(safe).join(", ");
+    const more = result.scope.length > 10 ? ` and ${result.scope.length - 10} more` : "";
+    lines.push(`  ${C.dim}scanned: where the territories are — ${shown}${more}. ${C.b}seisin scan --all${C.off}${C.dim} walks the whole folder${C.off}\n`);
+  }
+  lines.push("\n");
 
-  if (certain.length === 0 && review.length === 0 && links.length === 0) {
-    lines.push(`  ${C.green}nothing credential-shaped outside the declared directories${C.off}\n\n`);
+  // A pruned checkout is part of what a clean result means, so it is said
+  // even when there is nothing else to say — in yellow, not dim: every role
+  // can still read it, and a dim line under a green verdict read as clean.
+  const paths = result.nestedPaths ?? [];
+  let nested = "";
+  if (skipped.nested) {
+    nested = `  ${C.yellow}not scanned: ${skipped.nested} nested checkout(s)${C.off} — another repository each; every role can still read them. Scan one with ${C.b}cd <dir> && seisin scan${C.off}\n`;
+    for (const p of paths.slice(0, 15)) nested += `    ${safe(p)}\n`;
+    if (paths.length > 15) nested += `    ${C.dim}… and ${paths.length - 15} more${C.off}\n`;
+    nested += "\n";
+  }
+  const named = result.named ?? [];
+  if (certain.length === 0 && review.length === 0 && links.length === 0 && named.length === 0) {
+    lines.push(skipped.nested
+      ? `  nothing credential-shaped in what was scanned ${C.dim}(outside the declared directories)${C.off}\n\n`
+      : `  ${C.green}nothing credential-shaped outside the declared directories${C.off}\n\n`, nested);
     return lines.join("");
   }
 
   if (certain.length) {
-    lines.push(`  ${C.red}${certain.length} credential(s)${C.off} — these shapes are issued, not written by accident\n\n`);
-    for (const h of certain) lines.push(`    ${C.b}${h.file}${C.off}${C.dim}:${h.line}${C.off}  ${h.shape}\n`);
+    lines.push(`  ${C.red}${certain.length} credential(s)${C.off} — issued shapes, or a password in a URL: a credential, not a word that mentions one\n\n`);
+    for (const h of certain) {
+      const whose = h.owners?.length ? `  ${C.dim}in ${h.owners.map(safe).join(", ")}'s territory${C.off}` : "";
+      lines.push(`    ${C.b}${safe(h.file)}${C.off}${C.dim}:${h.line}${C.off}  ${h.shape}${whose}\n`);
+    }
     lines.push("\n");
   }
 
@@ -189,6 +244,18 @@ export function renderScan(result, keyDirs) {
     lines.push("\n");
   }
 
+  // By name, not by content, and said that way: a .env of DEBUG=1 is on this
+  // list too. What it is for is the .env nobody declared.
+  if (named.length) {
+    lines.push(`  ${C.yellow}${named.length} file(s) that usually hold secrets${C.off} — by their name, not certain; every role reads them\n\n`);
+    for (const h of named.slice(0, 15)) {
+      const whose = h.owners?.length ? `  ${C.dim}in ${h.owners.map(safe).join(", ")}'s territory${C.off}` : "";
+      lines.push(`    ${C.b}${safe(h.file)}${C.off}${whose}\n`);
+    }
+    if (named.length > 15) lines.push(`    ${C.dim}… and ${named.length - 15} more${C.off}\n`);
+    lines.push("\n");
+  }
+
   // Links are their own finding, not a line with a secret-shaped name in it.
   // What is reported is that the link leaves the repo — the destination is
   // named and never opened, because the point is that it exists.
@@ -206,7 +273,9 @@ export function renderScan(result, keyDirs) {
   if (skipped.ignored) quiet.push(`${skipped.ignored} ignored path(s)`);
   if (skipped.protectedDirs) quiet.push(`${skipped.protectedDirs} inside declared key dir(s)`);
   if (quiet.length) lines.push(`  ${C.dim}not reported: ${quiet.join(" · ")}${C.off}\n`);
-  if (truncated) lines.push(`  ${C.yellow}stopped at the limit — there are more${C.off}\n`);
+  // Only the ones to review are capped; a certain hit is always listed above.
+  if (truncated) lines.push(`  ${C.yellow}${result.omitted ?? "more"} more to review were not listed — the cap applies to review, never to certain hits${C.off}\n`);
+  if (nested) lines.push(nested);
   lines.push(`  ${C.dim}seisin does not move these. Where a credential lives is your call.${C.off}\n\n`);
   return lines.join("");
 }

package/src/requests.js

@@ -1,38 +1,41 @@
 /**
- * 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.
  *
  * 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/permission-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 } from "node:fs";
+import { neverWrites, isGitMetadata, covers, keyHolders, inKeyDir } from "./owners.js";
+import { protectedBy } from "./surface.js";
+import { appendFileSync, mkdirSync, readFileSync, 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, readEntries } from "./log.js";
 
-export const REQUESTS_NAME = "requests.jsonl";
+const REQUESTS_NAME = "requests.jsonl";
 
 export function requestsPath(root) {
   return join(root, STATE_DIR, REQUESTS_NAME);
@@ -56,14 +59,34 @@ export function keyOf({ role, action, target }) {
   return `${role}:${action}:${dir}`;
 }
 
+/**
+ * A request's id as one shell word, for the commands seisin suggests.
+ *
+ * The id carries a path an agent chose, so it is single-quoted whole and any
+ * quote inside it is closed and escaped: pasting the suggestion runs `seisin
+ * grant` on that request and nothing else.
+ */
+export function shellId(key) {
+  return `'${String(key).replace(/'/g, `'\\''`)}'`;
+}
+
 /** The glob a grant would add, derived from what was asked. */
-export function grantFor({ action, target }) {
+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;
 }
@@ -72,7 +95,9 @@ 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();
+    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.
@@ -80,8 +105,27 @@ function write(file, entry) {
   }
 }
 
+/**
+ * Who a read request's key belongs to, from the policy as it is now.
+ *
+ * A key is declared, not owned: nobody writes `.secrets/`, so the owners a
+ * write-territory lookup finds for one are always none, and the queue said
+ * "(unowned)" about a key another role declares — right before a grant that
+ * would share it. Recomputed rather than read from the line, like every other
+ * field that decides what a person is shown.
+ */
+export function withDeclarers(config, queue) {
+  for (const r of queue) {
+    if (r.action !== "read" || typeof r.target !== "string") continue;
+    if (!inKeyDir(config, r.target) && r.target.includes("/")) continue;
+    r.owners = keyHolders(config, r.target);
+    r.declared = true;
+  }
+  return queue;
+}
+
 /** 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. */
+ *  on every denial; `seisin run` drops anything the policy does not deny. */
 export function record(file, { role, action, target, owners }) {
   return write(file, { kind: "asked", key: keyOf({ role, action, target }), role, action, target, owners: owners ?? [] });
 }
@@ -103,6 +147,9 @@ 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.
+ *
+ * Nothing in src/ calls it today — handoff.js decides but nothing records the
+ * outcome; the tests do, and pending() keeps reading what it writes.
  */
 export function recordHandoff(file, key, decision = {}) {
   const { type, role, limit, max, reason, depth, chainId, revision } = decision;
@@ -123,20 +170,35 @@ 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 [];
+let reduced = null;   // { file, ino, size, mtimeMs, all }
+
+export function pending(file, { includeSettled = false, keyDirs = null } = {}) {
+  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 {
+    all = reduce(file);
+    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(file) {
   const byKey = new Map();
 
-  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
-    }
+  for (const e of readEntries(file)) {
     if (!e.key) continue;
 
     if (e.kind === "asked") {
@@ -157,7 +219,8 @@ 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. (Only the tests write
+     * handoff lines today — see recordHandoff.)
      */
     if (e.kind === "handoff") {
       seen.handoff = {
@@ -170,14 +233,13 @@ export function pending(file, { includeSettled = false } = {}) {
     seen.state = e.kind; seen.reason = e.reason ?? ""; seen.decided = e.at;
   }
 
-  const all = [...byKey.values()];
-  return includeSettled ? all : all.filter((r) => r.state === "pending");
+  return [...byKey.values()];
 }
 
 /**
  * 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
@@ -221,7 +283,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
@@ -236,35 +298,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) {
@@ -276,6 +316,18 @@ 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.`);
   // 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(
@@ -283,6 +335,93 @@ export function refuseIfBarred(config, request) {
       `rewrite another owner's history. Decline it; a role that needs to commit gets a worktree of its own.`);
 }
 
+/**
+ * Apply one policy edit under a lock, and write it atomically.
+ *
+ * `grant` and the console both did read → applyGrant → write with no lock, so
+ * two approvals racing (a person at the CLI and one on the console, or two
+ * terminals) lost one edit: the queue marked both granted while `seisin.toml`
+ * kept only the last writer's change (measured: 39 of 40 concurrent pairs). The
+ * lock serialises them — it already survives a writer that died holding it
+ * (see log.js) — and the write goes to a temp file then renames over the config,
+ * 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, after = null } = {}) {
+  return withLock(policyLockBase(config), () => {
+    const before = readFileSync(config.path, "utf8");
+    const result = mutate(before);
+    if (result.changed) 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 name = `seisin.toml.tmp-${randomBytes(12).toString("hex")}`;
+  const stateTmp = join(config.root, STATE_DIR, name);
+  writeFileSync(stateTmp, text, { flag: "wx" });
+  try {
+    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" });
+  try { 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");
@@ -295,43 +434,82 @@ export function applyGrant(toml, request, note = "") {
   const to = next ? from + next.index : toml.length;
   const section = toml.slice(from, to);
 
-  const line = new RegExp(`^(${field}\\s*=\\s*)\\[([^\\]]*)\\]`, "m");
-  const m = line.exec(section);
-  if (!m)
+  const open = new RegExp(`^${field}\\s*=\\s*\\[`, "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 items = (m[2].match(/"[^"]*"/g) ?? []).map((s) => s.slice(1, -1));
-  if (items.includes(request.grant)) return { toml, changed: false };
+  const start = open.index + open[0].length;
+  const list = scanList(section, start);
+  if (list.items.includes(request.grant)) return { toml, changed: false };
 
+  /**
+   * Appended, never rebuilt.
+   *
+   * 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 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.
+   */
+  let inner = section.slice(start, list.end).replace(/\s+$/, "");
+  if (list.lastItemEnd !== null && !list.commaAfterLast) {
+    const at = list.lastItemEnd - start;
+    inner = inner.slice(0, at) + "," + inner.slice(at);
+  }
   const stamp = `# granted ${new Date().toISOString().slice(0, 10)} · asked ${request.times}×` +
-                `${note ? ` · "${cleanReason(note)}"` : ""}`;
-  const body = [...items, request.grant]
-    .map((v) => `  "${v}"${v === request.grant ? `,   ${stamp}` : ","}`)
-    .join("\n")
-    .replace(/,(\s*#[^\n]*)?$/, "$1");
-
-  const edited = section.replace(line, `$1[\n${body}\n]`);
+                `${note ? ` · «${cleanReason(note)}»` : ""}`;
+  const edited = section.slice(0, start) + `${inner}\n  "${request.grant}"   ${stamp}\n]` + section.slice(list.end + 1);
   return { toml: toml.slice(0, from) + edited + toml.slice(to), changed: true };
 }
 
 /**
- * The approver's own words, made safe to put in a config file.
+ * The strings of a TOML array that starts at `start` (just past its `[`),
+ * skipping comments, and where it closes. The subset has no escapes, so a
+ * string runs to the next double quote.
+ */
+function scanList(text, start) {
+  const items = [];
+  let lastItemEnd = null;
+  let commaAfterLast = false;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (c === "#") { const nl = text.indexOf("\n", i); if (nl === -1) break; i = nl; continue; }
+    if (c === '"') {
+      const close = text.indexOf('"', i + 1);
+      if (close === -1) break;
+      items.push(text.slice(i + 1, close));
+      lastItemEnd = close + 1;
+      commaAfterLast = false;
+      i = close;
+      continue;
+    }
+    if (c === ",") { commaAfterLast = true; continue; }
+    if (c === "]") return { items, end: i, lastItemEnd, commaAfterLast };
+  }
+  throw new Error(`the ${text.slice(0, 40).trim()}… list never closes; fix the config by hand before granting`);
+}
+
+/**
+ * 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 ?? "")