seisin 0.4.2 → 0.5.0

package/src/log.js

@@ -11,9 +11,9 @@
  * what an agent tried last night reads the same today — and since the change in
  * spool.js, nothing inside the sandbox can rewrite one either. append() below
  * tries the parent's socket first for exactly that reason; writing the file
- * directly is what happens when there is no parent, outside the box.
+ * directly is what happens when there is no parent, outside the sandbox.
  */
-import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, dirname, join } from "node:path";
 import { STATE_DIR, LOG_NAME } from "./layout.js";
@@ -44,9 +44,14 @@ export function append(file, entry) {
       // segment. Done here so the size check and the append never race.
       maybeRotate(file);
       // `prev` goes last and is computed from the previous line exactly as it
-      // sits on disk, so verifying needs nothing but the file.
-      const line = JSON.stringify({ at: new Date().toISOString(), ...entry, prev: hashOf(lastLine(file)) });
+      // sits on disk, so verifying needs nothing but the file. `at` is this
+      // process's clock, whatever the entry says: named again after the spread
+      // so a caller's `at` cannot replace it (the key keeps its first place).
+      const now = new Date().toISOString();
+      const line = JSON.stringify({ at: now, ...entry, at: now, prev: hashOf(lastLine(file)) });
       appendFileSync(file, line + "\n");
+      // Once per log: pin where the chain begins. See recordGenesis.
+      if (!existsSync(genesisPath(file))) { try { recordGenesis(file); } catch {} }
     }, { waitMs: envInt("SEISIN_LOG_LOCK_WAIT_MS", 6000) });
     return true;
   } catch (e) {
@@ -65,7 +70,52 @@ export function droppedPath(file) {
 }
 
 function countLines(file) {
-  try { return readFileSync(file, "utf8").split("\n").filter((l) => l.trim()).length; } catch { return 0; }
+  return readLines(file).length;
+}
+
+/**
+ * The complete lines of a JSON-lines file, raw and non-blank, oldest first.
+ *
+ * The one reader the JSONL files here share (the log, its segments, the
+ * request queue, the tail the hook counts from). With `tail`, only the last
+ * that many bytes are read, and the line the cut lands in is dropped — unless
+ * the cut falls exactly on a line boundary, which is checked by reading one
+ * byte earlier rather than guessed from string lengths (a byte count and a
+ * UTF-16 length disagree on every "ñ"). A missing file is no lines.
+ */
+export function readLines(file, { tail = 0 } = {}) {
+  let fd;
+  try { fd = openSync(file, "r"); } catch { return []; }
+  try {
+    const { size } = fstatSync(fd);
+    const from = tail > 0 ? Math.max(0, size - tail) : 0;
+    const start = from > 0 ? from - 1 : 0;
+    const buf = Buffer.alloc(size - start);
+    let got = 0;
+    while (got < buf.length) {
+      const n = readSync(fd, buf, got, buf.length - got, start + got);
+      if (n === 0) break;
+      got += n;
+    }
+    const lines = buf.subarray(0, got).toString("utf8").split("\n");
+    // Started one byte early: the first piece is either empty (the cut was on
+    // a newline) or the fragment the cut landed in. Dropped either way.
+    if (from > 0) lines.shift();
+    return lines.filter((l) => l.trim());
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** `readLines`, parsed. A malformed line — a half-written one from a killed process — is skipped. */
+export function readEntries(file, opts) {
+  const out = [];
+  for (const line of readLines(file, opts)) {
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (e && typeof e === "object") out.push(e);
+  }
+  return out;
 }
 
 /**
@@ -140,9 +190,9 @@ function maybeRotate(file) {
  * from nono's audit trail; the Merkle root and the signature it adds on top
  * are left for when someone asks for them.
  *
- * The first chained line of a file points at GENESIS. A file started by
- * rotation should point at the last line of the one before it; there is no
- * rotation yet, and when there is, that is what it has to do.
+ * The first chained line of a log points at GENESIS (or, after a legacy
+ * prefix, at the last legacy line). A segment started by rotation points at
+ * the last line of the one before it — see maybeRotate and verifyLog.
  */
 export const GENESIS = "0".repeat(32);
 
@@ -150,18 +200,34 @@ export function hashOf(line) {
   return line == null ? GENESIS : createHash("sha256").update(line).digest("hex").slice(0, 32);
 }
 
-/** The last complete line of the file, or null when there is none. */
+/**
+ * The last complete line of the file, or null when there is none.
+ *
+ * Read backwards a chunk at a time until a newline is found before it. It
+ * read a fixed 64 KB, so a single line longer than that came back as its own
+ * tail, the next `prev` hashed a fragment, and the chain broke with nobody
+ * having touched the file.
+ */
 function lastLine(file) {
-  if (!existsSync(file)) return null;
-  const { size } = statSync(file);
-  if (size === 0) return null;
-  const from = Math.max(0, size - 64 * 1024);
-  const fd = openSync(file, "r");
+  let fd;
+  try { fd = openSync(file, "r"); } catch { return null; }
   try {
-    const buf = Buffer.alloc(size - from);
-    readSync(fd, buf, 0, buf.length, from);
-    const lines = buf.toString("utf8").split("\n").filter((l) => l.trim());
-    return lines.length ? lines[lines.length - 1] : null;
+    const CHUNK = 64 * 1024;
+    let pos = fstatSync(fd).size;
+    let acc = Buffer.alloc(0);
+    while (pos > 0) {
+      const from = Math.max(0, pos - CHUNK);
+      const buf = Buffer.alloc(pos - from);
+      readSync(fd, buf, 0, buf.length, from);
+      acc = Buffer.concat([buf, acc]);
+      pos = from;
+      const lines = acc.toString("utf8").split("\n");
+      let i = lines.length - 1;
+      while (i >= 0 && !lines[i].trim()) i--;
+      // Whole once something precedes it in the buffer, or the file starts here.
+      if (i > 0 || (i === 0 && pos === 0)) return lines[i];
+    }
+    return null;
   } finally {
     closeSync(fd);
   }
@@ -213,10 +279,23 @@ export function withLock(file, fn, { waitMs = 6000, staleMs = 5000 } = {}) {
   }
 }
 
-/** True if the process is still there. EPERM means it is, and not ours to signal. */
-function alive(pid) {
+/**
+ * Is this process still there? False only when the kernel says there is no
+ * such process (ESRCH).
+ *
+ * The one answer both callers need, and it leans the same way for both: an
+ * answer that is not "gone" — EPERM (there, and not ours to signal), anything
+ * unexpected, a pid that is not a positive integer — counts as alive. For a
+ * lock that means waiting on a holder that might be done; for a run directory
+ * it means leaving one that might be stale. Both are cheaper than the other
+ * mistake: breaking a lock someone holds, or deleting a live run's socket and
+ * keys from under it. rundir.js used to call every error but EPERM "dead" and
+ * swept on it.
+ */
+export function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return true;   // not a pid we can ask about; kill(-n) is a group
   try { process.kill(pid, 0); return true; }
-  catch (e) { return e.code !== "ESRCH"; }
+  catch (e) { return e?.code !== "ESRCH"; }
 }
 
 /**
@@ -243,21 +322,30 @@ function reapable(lock, staleMs) {
  * Walk the file and say where the chain breaks.
  *
  * Lines written before the chain existed have no `prev`; they are counted as an
- * unchained prefix, not reported as tampering. After the first chained line,
- * a line without `prev` is itself a break.
+ * unchained prefix, not reported as tampering — but only where such a prefix
+ * can be: at the head of the oldest segment (`legacy`). After the first chained
+ * line, and anywhere in a segment that rotation started, a line without `prev`
+ * is itself a break. So is a rotation marker without one: seisin never wrote
+ * such a marker.
+ *
+ * `digest` hashes the unchained prefix and `first` is the hash of the first
+ * chained line: what the genesis record pins (see recordGenesis).
  */
-function walk(file, { seed = GENESIS, startLine = 0 } = {}) {
-  const out = { lines: 0, unchained: 0, chained: 0, breaks: [], tail: null };
-  if (!existsSync(file)) return out;
+function walk(file, { seed = GENESIS, startLine = 0, legacy = true } = {}) {
+  const out = { lines: 0, unchained: 0, chained: 0, breaks: [], tail: null, digest: null, first: null, rotated: false };
+  const prefix = createHash("sha256");
   let previous = null;
   let started = false;
-  for (const line of readFileSync(file, "utf8").split("\n")) {
-    if (!line.trim()) continue;
+  for (const line of readLines(file)) {
     out.lines++;
     let e = null;
     try { e = JSON.parse(line); } catch {}
     const prev = e?.prev;
-    if (!started && prev === undefined) { out.unchained++; previous = line; continue; }
+    if (out.lines === 1 && e?.event === "rotated") out.rotated = true;
+    if (!started && prev === undefined && legacy && !out.rotated) {
+      out.unchained++; prefix.update(line + "\n"); previous = line; continue;
+    }
+    if (!started) out.first = hashOf(line);
     started = true;
     const first = out.chained === 0 && out.unchained === 0;
     // A rotation marker leading a segment we have nothing to check it against —
@@ -266,14 +354,15 @@ function walk(file, { seed = GENESIS, startLine = 0 } = {}) {
     // called a break. For any later segment the seed is the real previous tail,
     // so the marker's `prev` IS checked, and a whole segment deleted or
     // reordered in the middle shows.
-    const rotationStart = first && e?.event === "rotated" && seed === GENESIS;
+    const rotationStart = first && e?.event === "rotated" && prev !== undefined && seed === GENESIS;
     const expected = first ? seed : hashOf(previous);
-    const ok = rotationStart || prev === expected || (first && prev === hashOf(previous));
+    const ok = prev !== undefined && (rotationStart || prev === expected || (first && prev === hashOf(previous)));
     if (!ok) out.breaks.push({ line: startLine + out.lines, expected, found: prev ?? null });
     out.chained++;
     previous = line;
   }
   out.tail = previous;
+  out.digest = out.unchained ? prefix.digest("hex").slice(0, 32) : null;
   return out;
 }
 
@@ -282,6 +371,54 @@ export function verifyChain(file, seed = GENESIS) {
   return { lines: r.lines, unchained: r.unchained, chained: r.chained, breaks: r.breaks };
 }
 
+/**
+ * Where the chain begins, written once beside the log.
+ *
+ * The unchained prefix was taken on trust, and that was the hole: strip `prev`
+ * from every line and the whole log becomes "from before the chain", so an
+ * edit or a deletion anywhere in it verified as intact. The record pins the
+ * boundary the first time a chained line is written by a seisin that knows to
+ * — how many legacy lines there were, a digest of them, and the hash of the
+ * first chained line — so a log that no longer matches it is broken, not old.
+ *
+ * Written under the log lock, by `append`, and never rewritten. A log whose
+ * record is missing (written by an older seisin and not appended to since, or
+ * the record deleted) verifies as before and says the genesis is unrecorded.
+ *
+ * ── Recorded late ──
+ * The record is only as good as the moment it was taken. Written with the
+ * first chained line, it pins a start nobody could have edited yet. Written
+ * later — a log chained by an older seisin, or a record deleted and re-made by
+ * the next append — it pins whatever the log says by then, tampered or not.
+ * That is still worth pinning (nothing after it can be rewritten unseen), but
+ * it must not read as the same guarantee: such a record says `late`, how many
+ * chained lines already stood before it, and `verify` repeats both.
+ */
+export function genesisPath(file) {
+  return file + ".genesis";
+}
+
+function recordGenesis(file) {
+  const segs = logSegments(file);
+  if (!segs.length) return;
+  const r = walk(segs[0]);
+  if (!r.first) return;               // nothing chained yet: nothing to pin
+  // Chained lines that stood before the one `append` just wrote. Any at all
+  // means the start is being pinned after the fact.
+  let before = r.chained - 1;
+  segs.slice(1).forEach((seg) => { before += walk(seg, { legacy: false }).chained; });
+  const record = { at: new Date().toISOString(), legacy: r.unchained, digest: r.digest, first: r.first };
+  if (before > 0) Object.assign(record, { late: true, after: before });
+  writeFileSync(genesisPath(file), JSON.stringify(record) + "\n", { flag: "wx" });
+}
+
+function readGenesis(file) {
+  try {
+    const g = JSON.parse(readFileSync(genesisPath(file), "utf8"));
+    return g && Number.isInteger(g.legacy) && typeof g.first === "string" ? g : null;
+  } catch { return null; }
+}
+
 /**
  * Verify the whole log, across every rotated segment, as one chain.
  *
@@ -291,40 +428,88 @@ export function verifyChain(file, seed = GENESIS) {
  * single segment and this is exactly `verifyChain`. What it cannot see is a
  * segment dropped off the *oldest* end by the keep limit: that is retention, not
  * tampering, and the count of segments is reported so the drop is not silent.
+ *
+ * `genesis` says whether the chain's starting point was checked against its
+ * record: `recorded`, `unrecorded` (no record yet — see recordGenesis), or
+ * `pruned` (the segment it described was dropped for retention). `late` is
+ * `{ at, after }` when the record was made after chained lines already stood.
+ *
+ * A record whose first chained hash differs, over a chain that otherwise
+ * holds, is not an edit inside this log: it describes a different start.
+ * That happens when the operator archives the log by hand and leaves the
+ * record behind — or when the log was rewritten from its first line. Both are
+ * reported as a break (the second is exactly what the record exists to catch),
+ * but marked `foreign`, so `verify` can say which file to move or remove.
  */
 export function verifyLog(file) {
   const segs = logSegments(file);
-  const agg = { lines: 0, unchained: 0, chained: 0, breaks: [], segments: segs.length, dropped: countLines(droppedPath(file)) };
+  const agg = { lines: 0, unchained: 0, chained: 0, breaks: [], segments: segs.length, dropped: countLines(droppedPath(file)), genesis: "unrecorded", late: null };
+  const pinned = readGenesis(file);
   let seed = GENESIS;
-  for (const seg of segs) {
-    const r = walk(seg, { seed, startLine: agg.lines });
+  segs.forEach((seg, i) => {
+    const r = walk(seg, { seed, startLine: agg.lines, legacy: i === 0 });
+    if (i === 0 && pinned) {
+      if (r.rotated) agg.genesis = "pruned";
+      else {
+        agg.genesis = "recorded";
+        if (pinned.late) agg.late = { at: pinned.at ?? null, after: Number.isInteger(pinned.after) ? pinned.after : null };
+        // Where the first chained line should be, and what it should hash to.
+        const at = pinned.legacy + 1;
+        // A different first line in a chain that otherwise holds is a
+        // different start, not an edit — an edit to the first line would also
+        // break the line after it. A log with no chain left at all was not
+        // replaced by another seisin log (those chain from their first line):
+        // it was stripped.
+        if (r.first && r.first !== pinned.first && r.breaks.length === 0)
+          r.breaks.unshift({ line: at, expected: pinned.first, found: r.first, genesis: true, foreign: true });
+        else if (r.unchained !== pinned.legacy || r.first !== pinned.first)
+          r.breaks.unshift({ line: at, expected: pinned.first, found: r.unchained !== pinned.legacy ? null : r.first, genesis: true });
+        else if ((r.digest ?? null) !== (pinned.digest ?? null))
+          r.breaks.unshift({ line: 1, expected: pinned.digest, found: r.digest, genesis: true });
+      }
+    }
     agg.lines += r.lines;
     agg.unchained += r.unchained;
     agg.chained += r.chained;
     agg.breaks.push(...r.breaks);
     seed = hashOf(r.tail);
-  }
+  });
   return agg;
 }
 
-/** Reads entries, newest last. A malformed line is skipped, never fatal. */
+/**
+ * Reads entries, newest last, across every segment. A malformed line is
+ * skipped, never fatal.
+ *
+ * It read the current segment only, so the first rotation (8 MiB) took the
+ * history out from under everything that reads a window — the console, causes,
+ * walls, the staleness of a request — without a word. Segments are read newest
+ * first and the walk stops at the first one that ends before `since`, or once
+ * `limit` entries are in hand.
+ */
 export function read(file, { role, verdict, since, limit = 0 } = {}) {
-  if (!existsSync(file)) return [];
-  let out = [];
-  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
+  const parts = [];
+  let have = 0;
+  for (const seg of logSegments(file).reverse()) {
+    if (since && seg !== file) {
+      // A retired segment that ended before the window has nothing in it.
+      let last = null;
+      try { last = JSON.parse(lastLine(seg)); } catch {}
+      if (typeof last?.at === "string" && last.at < since) break;
+    }
+    const got = [];
+    for (const e of readEntries(seg)) {
+      if (e.event === "rotated") continue; // a structural marker, not a decision
+      if (role && e.role !== role) continue;
+      if (verdict && e.verdict !== verdict) continue;
+      if (since && e.at < since) continue;
+      got.push(e);
     }
-    if (e.event === "rotated") continue; // a structural marker, not a decision
-    if (role && e.role !== role) continue;
-    if (verdict && e.verdict !== verdict) continue;
-    if (since && e.at < since) continue;
-    out.push(e);
+    parts.unshift(got);
+    have += got.length;
+    if (limit > 0 && have >= limit) break;
   }
+  let out = parts.flat();
   if (limit > 0 && out.length > limit) out = out.slice(-limit);
   return out;
 }
@@ -354,7 +539,7 @@ export function observed(entries) {
     // it, or the line was not written by the hook at all. Either way it is not
     // evidence of what the role legitimately reached for, so it must not become
     // policy: `init --from-observations` builds `writes`/`keys` from here, and a
-    // process inside the box could otherwise send `verdict:"observed"` lines for
+    // process inside the sandbox could otherwise send `verdict:"observed"` lines for
     // paths outside its territory and have them proposed as its own.
     if (e.disputed) continue;
     const r = roles.get(e.role) ?? { writes: new Set(), keys: new Set() };

package/src/mcp.js

@@ -29,11 +29,12 @@
 import { toRepoRelative } from "./paths.js";
 import { loadConfig, findConfig } from "./config.js";
 import { inspect } from "./inspect.js";
-import { explain, ownersOf } from "./owners.js";
+import { explain, explainFileRead, ownersOf, readTarget } from "./owners.js";
+import { CREDENTIAL_HOMES, expand } from "./grants.js";
 import { settingsFor } from "./srt.js";
-import { pending, requestsPath, grantFor, refuseIfBarred, markStale, shellId } from "./requests.js";
+import { pending, requestsPath, refuseIfBarred, shellId } from "./requests.js";
 import { read, logPath } from "./log.js";
-import { causesOf } from "./serve.js";
+import { causesOf, parseSince, queue as requestQueue, verdicts, wallsByRole } from "./views.js";
 import { walls, wasted } from "./walls.js";
 
 /**
@@ -53,7 +54,7 @@ const TOOLS = [
   {
     name: "seisin_state",
     description:
-      "The permission map: every role, the folders it may write, the keys it may read, " +
+      "The map: every role, its territory (the folders it may write), the keys it may read, " +
       "and every way the policy silently does not hold. Read-only.",
     inputSchema: {
       type: "object",
@@ -78,15 +79,15 @@ const TOOLS = [
   {
     name: "seisin_requests",
     description:
-      "Permissions agents asked for and cannot have yet, waiting on a human, with how many " +
-      "times each was asked. A refusal files one of these automatically, so this is where " +
-      "to look after being denied rather than retrying. Read-only — approving is not " +
+      "Requests: access agents asked for and cannot have yet, waiting on a person, with how many " +
+      "times each was asked. A denial files one of these automatically, so this is where " +
+      "to look after being denied rather than retrying. Read-only — granting is not " +
       "available here, by design.",
     inputSchema: { type: "object", properties: {} },
   },
   {
     name: "seisin_activity",
-    description: "Recent allow/deny decisions, newest last. Read-only.",
+    description: "Recent log entries — allowed, denied or observed — newest last. Read-only.",
     inputSchema: {
       type: "object",
       properties: {
@@ -101,11 +102,16 @@ const TOOLS = [
     description:
       "Denials grouped by what was denied — by path, and one level coarser by the name at " +
       "the end of it — over the whole log, or since an ISO date. The counts are history: " +
-      "what was refused. What is measured against the policy as it stands is where each " +
+      "what was denied. What is measured against the policy as it stands is where each " +
       "path is now — `standing`: unowned (a decision nobody has made), owned, protected " +
       "(closed to every role on purpose, nothing to grant) or outside (a port, a key, or " +
       "outside the repository) — and, per cause, `stillRefused`, how many of the roles " +
-      "that hit it would hit it today. `seisin_activity` has the raw events; this has " +
+      "that hit it would hit it today. An unowned cause also carries `kind` and `hint`: " +
+      "git (lock or metadata), credential, temporary, build or territory, and the move " +
+      "that fits it (`standing.unowned.kinds` counts them). Only `territory` is a question " +
+      "of who owns what; do not propose an owner for the others — a lock, a test's scratch " +
+      "or a credential given to whoever asked widens a role. " +
+      "`seisin_activity` has the raw events; this has " +
       "them read against the policy. Reach for it before proposing a change: a day that " +
       "is three quarters one filename is a tooling problem, and the same volume spread " +
       "across unrelated unowned paths is a question about who owns what. Read-only.",
@@ -113,7 +119,7 @@ const TOOLS = [
       type: "object",
       properties: {
         limit: { type: "number" },
-        since: { type: "string", description: "ISO date; only refusals at or after it" },
+        since: { type: "string", description: "ISO date; only denials at or after it" },
       },
     },
   },
@@ -130,10 +136,10 @@ const TOOLS = [
     name: "seisin_draft_grant",
     description:
       "Draft the change a pending request would make, as text, plus the command a person " +
-      "runs to apply it. Reach for this after a refusal: the denial is already in " +
-      "seisin_requests, and this turns it into a concrete proposal someone can approve. " +
+      "runs to apply it. Reach for this after a denial: it is already in " +
+      "seisin_requests, and this turns it into a concrete proposal a person can grant. " +
       "Read-only, and it is the tool where that matters most: the name says grant and it " +
-      "does not grant. The approval is a human action in another channel.",
+      "does not grant. Granting is a person's action, in another channel.",
     inputSchema: {
       type: "object",
       properties: {
@@ -185,6 +191,14 @@ const HANDLERS = {
     if (!cfg.roles[role])
       return { error: `unknown role "${role}"`, known: Object.keys(cfg.roles) };
     if (action === "mcp") return explain(cfg, role, "mcp", target);
+    // A read of a file outside every key dir is open, as it is for the CLI.
+    // The server has no working directory of its own, so the root stands in.
+    if (action === "read") {
+      const asked = readTarget(cfg, target, cfg.root);
+      return asked.key
+        ? explain(cfg, role, "read", asked.target)
+        : explainFileRead(cfg, role, asked.target, CREDENTIAL_HOMES.map(expand));
+    }
     const rel = toRepoRelative(cfg, target);
     const verdict = explain(cfg, role, action, rel);
     return { ...verdict, alsoOwnedBy: action === "write" ? ownersOf(cfg, rel) : undefined };
@@ -192,7 +206,7 @@ const HANDLERS = {
 
   seisin_requests() {
     const cfg = config();
-    const queue = markStale(pending(requestsPath(cfg.root)), read(logPath(cfg.root)));
+    const queue = requestQueue(cfg.root, read(logPath(cfg.root)), cfg.keyDirs);
     return {
       pending: queue.map((r, i) => ({
         number: i + 1, id: r.key, role: r.role, action: r.action,
@@ -202,7 +216,7 @@ const HANDLERS = {
       // Said in the payload and not only in the tool description, because a
       // model reading this is deciding what to do next.
       note: queue.length
-        ? "Approving is not available through MCP. Tell the operator to run: seisin grant '<id>'"
+        ? "Granting is not available through MCP. Ask a person to run: seisin grant '<id>'"
         : "nothing waiting",
     };
   },
@@ -222,9 +236,8 @@ const HANDLERS = {
     // after the console had stopped doing so, and the two then disagreed about
     // the same log — 3,999 refusals here against 6,630 there, measured — with
     // nothing telling the agent its window was half of the person's.
-    const t = since ? Date.parse(since) : NaN;
-    const from = Number.isNaN(t) ? null : new Date(t).toISOString();
-    const c = causesOf(cfg, read(logPath(cfg.root), from ? { since: from } : {}));
+    const from = parseSince(since);
+    const c = causesOf(cfg, read(logPath(cfg.root), from ? { since: from } : {}), { ask: verdicts(cfg) });
     return {
       total: c.total,
       distinct: c.distinct,
@@ -238,14 +251,15 @@ const HANDLERS = {
 
   seisin_walls({ role }) {
     const cfg = config();
-    const file = logPath(cfg.root);
-    const names = role ? [role] : Object.keys(cfg.roles);
     if (role && !cfg.roles[role]) throw new Error(`unknown role "${role}"`);
+    // One read of the log for every role, not one per role (32 on a real policy).
+    const denied = read(logPath(cfg.root), { verdict: "denied" });
+    const ask = verdicts(cfg);
+    const byRole = role
+      ? Object.fromEntries([[role, walls(cfg, role, { entries: denied, ask })]].filter(([, w]) => w.length))
+      : wallsByRole(cfg, denied, { ask });
     const out = {};
-    for (const r of names) {
-      const w = walls(cfg, r, { file });
-      if (w.length) out[r] = { walls: w, spentRetrying: wasted(w) };
-    }
+    for (const [r, w] of Object.entries(byRole)) out[r] = { walls: w, spentRetrying: wasted(w) };
     return { roles: out, spentRetrying: Object.values(out).reduce((n, x) => n + x.spentRetrying, 0) };
   },
 
@@ -260,7 +274,7 @@ const HANDLERS = {
 
   seisin_draft_grant({ id, number } = {}) {
     const cfg = config();
-    const queue = pending(requestsPath(cfg.root));
+    const queue = pending(requestsPath(cfg.root), { keyDirs: cfg.keyDirs });
     let req;
     if (typeof id === "string" && id) {
       req = queue.find((r) => r.key === id);
@@ -334,9 +348,9 @@ function handle(message, { write, version }) {
         capabilities: { tools: {} },
         serverInfo: { name: "seisin", title: "seisin — folders and keys per agent", version },
         instructions:
-          "Read-only view of this repo's agent permissions. Ask seisin_explain before " +
+          "Read-only view of this repo's roles, territories and keys. Ask seisin_explain before " +
           "suggesting an agent edit a file it may not own. Granting is not available " +
-          "here: surface seisin_requests and let the operator run `seisin grant`.",
+          "here: surface seisin_requests and let a person run `seisin grant`.",
       });
     }
     case "ping":

package/src/notify.js

@@ -17,7 +17,7 @@
  *     never holds the URL, and `SEISIN_NOTIFY_URL` is dropped from its
  *     environment even if the role names it;
  *   - the URL is not readable from any territory. A ntfy topic or a webhook is
- *     a credential — whoever can read it can send the person a fake "approve
+ *     a credential — whoever can read it can send the person a fake "grant
  *     #3". So it lives in a key directory no role declares (`url_file`), or in
  *     the parent's environment, and never as a plain value in seisin.toml,
  *     which every role can read.
@@ -26,11 +26,11 @@ import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { keyOf, pending, requestsPath, grantFor, shellId } from "./requests.js";
 
-export const FORMATS = ["text", "json", "slack"];
-export const ENV_URL = "SEISIN_NOTIFY_URL";
+const FORMATS = ["text", "json", "slack"];
+const ENV_URL = "SEISIN_NOTIFY_URL";
 
 /** The URL to notify, or null. Read in the parent only. */
-export function notifyUrl(config, env = process.env) {
+function notifyUrl(config, env = process.env) {
   if (env[ENV_URL]) return env[ENV_URL].trim();
   if (!config.notify?.urlFile) return null;
   try {
@@ -45,9 +45,14 @@ export function notifyUrl(config, env = process.env) {
 export function message(config, req, number, format = "text") {
   const owner = req.owners?.length ? `It belongs to ${req.owners.join(", ")}.` : "Nobody owns it.";
   const text =
-    `seisin (${basename(config.root)}): ${req.role} was refused ${req.action} on ${req.target}. ${owner} ` +
-    `Approve: seisin grant ${shellId(keyOf(req))} · decline: seisin decline ${shellId(keyOf(req))}`;
-  if (format === "slack") return { type: "application/json", body: JSON.stringify({ text }) };
+    `seisin (${basename(config.root)}): ${req.role} was denied ${req.action} on ${req.target}. ${owner} ` +
+    `Grant: seisin grant ${shellId(keyOf(req))} · decline: seisin decline ${shellId(keyOf(req))}`;
+  // Slack reads `<url|label>` as a link and `<!channel>` as a mention, and the
+  // path is chosen by the agent: `<https://evil|approve here>` in a target
+  // would arrive as a clickable link in the channel a person approves from.
+  // Its own escaping, and only these three characters, is what it asks for.
+  if (format === "slack")
+    return { type: "application/json", body: JSON.stringify({ text: text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;") }) };
   if (format === "json")
     return {
       type: "application/json",
@@ -141,6 +146,6 @@ export function readNotify(table, { path, root, keyDirs, roles, own }) {
   if (holders.length)
     throw new Error(
       `${path}: [notify] url_file "${urlFile}" is declared as a key by ${holders.join(", ")} — ` +
-      `that role could read it and send the person a fake "approve". No role may hold it.`);
+      `that role could read it and send the person a fake "grant this". No role may hold it.`);
   return { urlFile, format };
 }