seisin 0.1.1 → 0.2.0

package/src/mcp.js

@@ -32,6 +32,8 @@ import { explain, ownersOf } from "./owners.js";
 import { settingsFor } from "./srt.js";
 import { pending, requestsPath, grantFor } from "./requests.js";
 import { read, logPath } from "./log.js";
+import { causesOf } from "./serve.js";
+import { walls, wasted } from "./walls.js";
 
 /**
  * Versions this server will agree to.
@@ -93,13 +95,35 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "seisin_causes",
+    description:
+      "Denials grouped by what was denied — by path, and one level coarser by the name at " +
+      "the end of it — with how many are on paths no role owns. This is the question " +
+      "`seisin_activity` cannot answer: the raw log has the events, this has them counted " +
+      "against the policy as it stands, so a cause that has been granted since stops " +
+      "counting. 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 paths is " +
+      "a question about who owns what. Read-only.",
+    inputSchema: { type: "object", properties: { limit: { type: "number" } } },
+  },
+  {
+    name: "seisin_walls",
+    description:
+      "What a role keeps being denied AND would still be denied today, with the calls it " +
+      "spent retrying. Recomputed against the policy rather than read out of the log, so " +
+      "something granted since is not listed. Use it to find out whether an agent is stuck " +
+      "rather than slow. Omit `role` for every role that has one. Read-only.",
+    inputSchema: { type: "object", properties: { role: { type: "string" } } },
+  },
   {
     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. " +
-      "Writes nothing: the approval is a human action in another channel.",
+      "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.",
     inputSchema: {
       type: "object",
       properties: { number: { type: "number", description: "position in seisin_requests" } },
@@ -166,6 +190,40 @@ const HANDLERS = {
     };
   },
 
+  /**
+   * The same arithmetic the console's front page does.
+   *
+   * It lives here as well as there because the two readers are different and
+   * neither can do the other's work: a person opens the console, an agent
+   * calls this. Giving the agent only `seisin_activity` hands it the raw log
+   * and asks it to re-derive the grouping — without the policy, which is the
+   * half that makes the grouping mean anything.
+   */
+  seisin_causes({ limit }) {
+    const cfg = config();
+    const c = causesOf(cfg, read(logPath(cfg.root), { limit: 4000 }));
+    return {
+      total: c.total,
+      distinct: c.distinct,
+      unowned: c.unowned,
+      families: c.families,
+      causes: typeof limit === "number" ? c.causes.slice(0, limit) : c.causes,
+    };
+  },
+
+  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}"`);
+    const out = {};
+    for (const r of names) {
+      const w = walls(cfg, r, { file });
+      if (w.length) out[r] = { walls: w, spentRetrying: wasted(w) };
+    }
+    return { roles: out, spentRetrying: Object.values(out).reduce((n, x) => n + x.spentRetrying, 0) };
+  },
+
   seisin_activity({ role, verdict, limit }) {
     if (verdict !== undefined && !["allowed", "denied", "observed"].includes(verdict))
       throw new Error(`verdict must be allowed, denied or observed, got ${JSON.stringify(verdict)}`);

package/src/nested.js

@@ -0,0 +1,86 @@
+/**
+ * Agents that sandbox themselves, and why seisin has to say so first.
+ *
+ * `codex` confines every command it runs with its own `sandbox-exec` profile.
+ * macOS will not apply a second Seatbelt profile to a process that already has
+ * one, so inside `seisin run` it fails with:
+ *
+ *     sandbox-exec: sandbox_apply: Operation not permitted
+ *
+ * Measured, twice: the README has it from the original run and the lab
+ * reproduced it — exit 71, and the inner command never produced a byte.
+ *
+ * Two things make it a special case in a tool that otherwise has none.
+ *
+ * **It does not fail at the start.** The agent launches, reads, thinks, and
+ * dies on the first command it tries to confine. So the operator sees a turn
+ * that did nothing, which reads exactly like an agent with nothing to do.
+ *
+ * **And the error explains nothing.** It names neither seisin, nor the agent,
+ * nor the fix. For a tool whose whole claim is that a refusal tells you what
+ * happened, shipping the one message that says nothing is the worst available
+ * outcome — so this is checked before the spawn and said in words.
+ *
+ * It is a closed list, not a detector. Guessing which binaries sandbox
+ * themselves from their name would be wrong in both directions, and being
+ * wrong here means printing a warning about a thing that is not happening.
+ */
+
+/**
+ * What each agent does by default, and what turns it off.
+ *
+ * `on: true` means the agent confines by default, so the warning is the
+ * normal case and silence needs a flag. codex is that. gemini is the other
+ * way round: off unless asked. Getting this backwards means warning about a
+ * thing that is not happening, which trains people to skip the line.
+ *
+ * `opencode` is absent. It has been run under seisin and the
+ * README describes its behaviour, but nothing here has measured whether it
+ * confines its own commands, and a closed list holds only what was checked.
+ */
+const SELF_SANDBOXING = {
+  codex: {
+    on: true,
+    off: ["--dangerously-bypass-approvals-and-sandbox"],
+    // The subcommand whose entire job is to confine. No flag turns that off.
+    never: ["sandbox"],
+  },
+  gemini: { on: false, onWith: ["-s", "--sandbox"], off: ["--sandbox=false"] },
+};
+
+/** The basename of a command, without its path. */
+const bare = (c) => String(c ?? "").split("/").pop();
+
+/**
+ * The warning for this command line, or null.
+ *
+ * Takes the argv `run` is about to spawn, and looks only at the first token
+ * and its flags. Anything cleverer would be guessing at a shell it cannot
+ * parse, and a wrong warning is worse than no warning.
+ */
+export function nestedSandboxWarning(cmd = []) {
+  const name = bare(cmd[0]);
+  const spec = Object.prototype.hasOwnProperty.call(SELF_SANDBOXING, name) ? SELF_SANDBOXING[name] : null;
+  if (!spec) return null;
+
+  const rest = cmd.slice(1);
+  if ((spec.never ?? []).includes(rest[0]))
+    return (
+      `\`${name} ${rest[0]}\` exists to run a command inside a sandbox, so it cannot run inside ` +
+      `one. The OS will not apply a second profile to a process that already has one.\n` +
+      `  Run the command directly — seisin is already the boundary here.`
+    );
+
+  const turnedOff = (spec.off ?? []).some((f) => rest.some((a) => a === f || a.startsWith(f + "=")));
+  if (turnedOff) return null;
+  const confining = spec.on || (spec.onWith ?? []).some((f) => rest.includes(f));
+  if (!confining) return null;
+
+  return (
+    `${name} confines the commands it runs with its own sandbox, and the OS will not apply a ` +
+    `second profile to a process that already has one.\n` +
+    `  This does not fail here — it fails on the first command ${name} tries to run, which ` +
+    `looks like an agent that did nothing.\n` +
+    `  Run it with its own sandbox off: \`${name} … ${(spec.off ?? ["--no-sandbox"])[0]}\`.`
+  );
+}

package/src/render.js

@@ -30,18 +30,51 @@ export const err = (s) => process.stderr.write(s);
 
 /* ── the map ──────────────────────────────────────────────────────────── */
 
+/**
+ * A database's sidecars, shown as the database.
+ *
+ * `writes` carries the expansion because the grant and the sentence have to
+ * agree — see config.js. Printing all four is then honest and unreadable: on a
+ * real policy it turned eight databases into thirty-two rows of the same name
+ * with three suffixes, which is what the expansion existed to remove.
+ *
+ * So the list is collapsed back for DISPLAY only, and only where the base is
+ * present, and it says the sidecars are there rather than hiding them. A
+ * sidecar declared without its database still prints on its own line — that is
+ * unusual enough to be worth seeing.
+ */
+const SIDECAR_RE = /-(wal|shm|journal)$/;
+
+export function collapseSidecars(paths) {
+  const have = new Set(paths);
+  const out = [];
+  for (const p of paths) {
+    const base = p.replace(SIDECAR_RE, "");
+    if (SIDECAR_RE.test(p) && have.has(base)) continue;      // shown on its base
+    out.push(SIDECAR_RE.test(p) || !have.has(p + "-wal") ? p : `${p}${C.dim}+wal+shm+journal${C.off}`);
+  }
+  return out;
+}
+
 /** The `check` report, as text. Takes the object `inspect()` returns. */
 export function renderReport(report) {
   const lines = [`\n${C.b}${report.where}${C.off}\n\n`];
   const width = Math.max(...report.roles.map((r) => r.name.length), 4);
 
   for (const r of report.roles) {
-    const writes = r.writes.join(" ") || `${C.dim}nothing${C.off}`;
+    const writes = collapseSidecars(r.writes).join(" ") || `${C.dim}nothing${C.off}`;
     const keys = r.keys.length ? r.keys.join(" ") : `${C.dim}none${C.off}`;
     lines.push(`  ${C.b}${r.name.padEnd(width)}${C.off}  ${C.blue}writes${C.off} ${writes}\n`);
     lines.push(`  ${" ".repeat(width)}  ${C.green}keys${C.off}   ${keys}\n\n`);
   }
 
+  if (report.providers?.length) {
+    lines.push(`  ${C.b}key providers${C.off} ${C.dim}— seisin runs these itself, outside the sandbox, as you${C.off}\n`);
+    for (const p of report.providers)
+      lines.push(`  ${C.green}${p.name}${C.off}  ${p.command.join(" ")}${p.mode ? `  ${C.dim}(${p.mode})${C.off}` : ""}\n`);
+    lines.push("\n");
+  }
+
   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`);

package/src/serve.js

@@ -19,6 +19,8 @@ import { loadConfig } from "./config.js";
 import { read, logPath } from "./log.js";
 import { settingsFor } from "./srt.js";
 import { pending, requestsPath, settle, applyGrant } from "./requests.js";
+import { walls } from "./walls.js";
+import { explain } from "./owners.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -29,9 +31,124 @@ const HERE = dirname(fileURLToPath(import.meta.url));
  * page is a view of it — someone editing seisin.toml in an editor should see
  * the console change, not wonder why it disagrees.
  */
+/**
+ * Today's denials, grouped by what was denied rather than by who asked.
+ *
+ * Called `causes` and not `friction`: `seisin review` already has a `friction`
+ * that counts something narrower — repeated denials that are not about keys —
+ * and two screens of one product reporting different numbers under one label
+ * is the kind of thing nobody notices until they are compared.
+ *
+ * The console used to show them per role, which is the same list a hundred
+ * times over: measured on one deployment, 1,080 of 1,422 refusals were a
+ * single lock file across six repositories, and per-role that reads as six
+ * hundred identical rows instead of one sentence. Grouped, the shape of the
+ * day is visible at a glance and it is almost never a territory dispute.
+ *
+ * `stillRefused` is recomputed against the policy as it stands, not read out
+ * of the log — a cause that has been granted since is history, not friction,
+ * and leaving it on the page sends somebody to fix what is already fixed.
+ */
+export function causesOf(cfg, entries) {
+  const by = new Map();
+  for (const e of entries) {
+    if (e.verdict !== "denied" || !e.target || !e.action) continue;
+    const k = `${e.action}\u0000${e.target}`;
+    const g = by.get(k) ?? { action: e.action, target: e.target, times: 0, roles: new Set(), owners: e.owners ?? [] };
+    g.times++;
+    g.roles.add(e.role);
+    by.set(k, g);
+  }
+  const total = [...by.values()].reduce((n, g) => n + g.times, 0);
+
+  /**
+   * The same grouping again, one level coarser: by the NAME at the end of the
+   * path rather than the path.
+   *
+   * Grouping by path alone gets the most important reading backwards. Measured
+   * here: six of the top seven causes were `.git/index.lock` in six different
+   * repositories, no single one above 17% — so "no cause dominates" is what the
+   * arithmetic says and the opposite of what is true. Three quarters of the
+   * window was one *kind* of thing, and that is a tooling problem with a
+   * mechanical fix, not a territory question anybody needs to rule on.
+   *
+   * By last segment, and nothing cleverer. A regex that recognised lock files,
+   * caches and build outputs would be a list of guesses about other people's
+   * toolchains that quietly goes stale; a repeated filename is a fact about
+   * this log.
+   */
+  const fams = new Map();
+  for (const g of by.values()) {
+    const name = g.target.split("/").filter(Boolean).pop() ?? g.target;
+    const f = fams.get(name) ?? { name, times: 0, paths: 0, where: [], roles: new Set() };
+    f.times += g.times;
+    f.paths++;
+    // The places, so the console can show what a name is made of instead of
+    // asserting a percentage the reader has to take on faith.
+    f.where.push({ target: g.target, times: g.times });
+    for (const r of g.roles) f.roles.add(r);
+    fams.set(name, f);
+  }
+  const families = [...fams.values()]
+    .sort((a, b) => b.times - a.times)
+    .map((f) => ({
+      name: f.name, times: f.times, paths: f.paths,
+      share: total ? f.times / total : 0,
+      roles: [...f.roles].sort(),
+      where: f.where.sort((a, b) => b.times - a.times).slice(0, 20),
+    }));
+
+  /**
+   * What a `grep` over the log cannot tell you.
+   *
+   * The headline used to be "74% of it is one name", and a field review
+   * applied this project's own test to it: *did the number tell you something
+   * you did not know?* For somebody who reads the raw log, no — they had
+   * already counted that. The console was repeating the log back.
+   *
+   * These two are different, because they need the **policy** and the log does
+   * not contain it. `unowned` is the count of causes on paths no role claims:
+   * no grant resolves those until somebody decides who owns them, which is a
+   * decision rather than a number. `settled` is friction that has since been
+   * granted — real yesterday, noise today.
+   */
+  const live = [...by.values()];
+  const unowned = live.filter((g) => !(g.owners ?? []).length).length;
+
+  return {
+    total,
+    unowned,
+    // The real number of distinct causes, not the length of the list below.
+    // The page says "over N distinct paths" and the list is capped at twelve,
+    // so taking N from the list reported the cap as if it were the count —
+    // a wrong number stated confidently, which is worse than no number.
+    distinct: by.size,
+    families: families.slice(0, 8),
+    causes: [...by.values()]
+      .sort((a, b) => b.times - a.times)
+      .slice(0, 12)
+      .map((g) => ({
+        action: g.action,
+        target: g.target,
+        times: g.times,
+        share: total ? g.times / total : 0,
+        roles: [...g.roles].sort(),
+        owners: g.owners,
+        // How many of the roles that hit this would still hit it. `some` and
+        // not `every`: two roles out of three still blocked is still friction,
+        // and requiring all of them would quietly retire a live cause the day
+        // one role got a grant.
+        stillRefused: [...g.roles].filter((r) => cfg.roles[r] && !explain(cfg, r, g.action, g.target).allowed).length,
+      })),
+  };
+}
+
 function state(configPath) {
   const cfg = loadConfig(configPath);
   const entries = read(logPath(cfg.root), { limit: 200 });
+  // A wider window than the activity tail, because grouping by cause is an
+  // arithmetic question and 200 lines of a busy day is one role's morning.
+  const forShape = read(logPath(cfg.root), { limit: 4000 });
 
   const roles = Object.values(cfg.roles).map((r) => ({
     name: r.name,
@@ -54,6 +171,13 @@ function state(configPath) {
     keyDirs: cfg.keyDirs,
     allowedDomains: cfg.allowedDomains,
     roles,
+    causes: causesOf(cfg, forShape),
+    // What each role keeps being refused AND would still be refused today.
+    // Empty for a role that has hit nothing twice, which is most of them.
+    walls: Object.fromEntries(
+      Object.keys(cfg.roles)
+        .map((r) => [r, walls(cfg, r, { file: logPath(cfg.root) })])
+        .filter(([, w]) => w.length)),
     log: entries.slice(-60).reverse(),
     live: true,
   };
@@ -114,8 +238,18 @@ export function serve(configPath, port = 4178) {
    */
   const token = randomBytes(24).toString("hex");
 
+  /**
+   * The path, without whatever came after `?`.
+   *
+   * `req.url` is the raw request target, so a query string made every route
+   * miss: `http://localhost:4178/?anything` answered 404 on the one page this
+   * server has. Harmless until a launcher appends a parameter or a link is
+   * shared with a suffix on it, and then the console just looks broken.
+   */
+  const pathOf = (u) => (u ?? "/").split("?")[0];
+
   const server = createServer(async (req, res) => {
-    if (req.method === "POST" && req.url === "/api/decide") {
+    if (req.method === "POST" && pathOf(req.url) === "/api/decide") {
       if (req.headers["x-seisin-token"] !== token) {
         res.writeHead(403, { "content-type": "application/json" });
         return res.end(JSON.stringify({ error: "bad or missing token" }));
@@ -133,7 +267,7 @@ export function serve(configPath, port = 4178) {
       res.writeHead(405).end("method not allowed");
       return;
     }
-    if (req.url === "/api/state") {
+    if (pathOf(req.url) === "/api/state") {
       let body;
       try {
         body = JSON.stringify(state(configPath));
@@ -145,7 +279,7 @@ export function serve(configPath, port = 4178) {
       res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
       return res.end(body);
     }
-    if (req.url === "/" || req.url === "/index.html") {
+    if (pathOf(req.url) === "/" || pathOf(req.url) === "/index.html") {
       // Inlined rather than put in the URL: a fragment survives in history, in
       // a screenshot, and in whatever the operator pastes into a chat.
       const html = readFileSync(page, "utf8")

package/src/srt.js

@@ -16,6 +16,7 @@
 import { join, dirname } from "node:path";
 import { STATE_DIR, CONFIG_NAME } from "./layout.js";
 import { homedir, tmpdir } from "node:os";
+import { entriesOf } from "./keys.js";
 import { realpathSync, lstatSync } from "node:fs";
 import { createHash } from "node:crypto";
 
@@ -283,7 +284,17 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
     denyRead.push(realOrSelf(roleHomeRoot(config)));
     allowRead.push(realOrSelf(home));
   }
-  for (const key of role.keys) {
+  /**
+   * Only a key that IS a file becomes a read grant.
+   *
+   * A reference has no path, so there is nothing here to allow: it is resolved
+   * by the parent before the sandbox starts and handed over as an environment
+   * variable or as a scratch file. See keys.js. Filtering here rather than
+   * upstream keeps the two kinds from having to know about each other — the
+   * settings this function emits are still, entirely, about the filesystem.
+   */
+  for (const entry of entriesOf(role).filter((e) => e.kind === "file")) {
+    const key = entry.raw;
     const path = key.includes("/") ? abs(key) : abs(join(dirs[0] ?? ".", key));
     // A key has to live in a declared key directory. Without this check a
     // slash in the name made the path relative to the repo root instead, so
@@ -373,11 +384,47 @@ export function settingsFor(config, roleName, spool = null, observe = false) {
         // Connecting is `network-outbound` and both of those are
         // `file-write-unlink`, so denying them leaves the first working.
         ...(spool ? [spool, dirname(spool)] : []),
+        /**
+         * Whatever the key providers execute.
+         *
+         * `seisin.toml` is denied because a role that can rewrite the policy
+         * has no policy. A provider command is the same thing one level out:
+         * the parent runs it, unsandboxed, as you — so a role that can rewrite
+         * `bin/open-vault.sh` decides what runs outside the box. That is not a
+         * wider boundary, it is no boundary, and it arrives disguised as an
+         * ordinary file in somebody's territory.
+         *
+         * Found by writing the documentation: every worked example ended up
+         * using a script, because the config language has no escapes and a
+         * one-line shell pipeline cannot be spelled. So the shape this protects
+         * is not a corner case — it is the shape the tool pushes you into.
+         *
+         * Only a command that resolves to a path. A bare name like `security`
+         * or `op` is found on PATH, which is not this policy's to reason about.
+         */
+        ...providerPaths(config),
       ],
     },
   };
 }
 
+/**
+ * The provider executables that live at a path, absolute.
+ *
+ * A command with no separator (`security`, `op`, `gpg`) is resolved by the OS
+ * from PATH and is deliberately left alone: denying "wherever gpg happens to
+ * be" would mean writing a rule about a machine rather than about a repo.
+ */
+export function providerPaths(config) {
+  const out = [];
+  for (const p of Object.values(config.keyProviders ?? {})) {
+    const cmd = p.command?.[0];
+    if (!cmd || !cmd.includes("/")) continue;
+    out.push(cmd.startsWith("/") ? cmd : join(config.root ?? ".", cmd));
+  }
+  return [...new Set(out)];
+}
+
 /**
  * `allowWrite` takes directories, not globs: the OS grants a subtree, it does
  * not pattern-match. `src/api/**` and `src/api/` mean the same thing to the

package/src/walls.js

@@ -0,0 +1,170 @@
+/**
+ * The walls a role has already hit.
+ *
+ * seisin answers *whose is this* at the moment of the refusal, once, in the
+ * middle of a turn, and then the sentence is gone. Nothing carries it forward,
+ * so the agent tries again — and the measurement that made this module exist
+ * says how often: of 345 denials on a real team, **88 (25%) were a repeat of
+ * something that same role had already been refused**. One role spent 37 calls
+ * on two walls, hitting the same one nineteen times.
+ *
+ * A block that repeats nineteen times is not a boundary working. It is a
+ * boundary that failed to communicate. The refusal was correct every time and
+ * still cost thirty-seven calls, because *correct* and *heard* are different
+ * properties and only one of them was being measured.
+ *
+ * So this reads what the role has already been told and hands it back, with
+ * the reason — the reason is the part that lets it look for the other way in.
+ *
+ * ## Why it recomputes instead of trusting the log
+ *
+ * The obvious version of this is a time window: only count the last two days,
+ * because an old wall may have been granted since and telling an agent not to
+ * do something it can now do is worse than saying nothing. That is what the
+ * prior art does, and the window is a proxy for the thing you actually want to
+ * know.
+ *
+ * seisin can ask the real question instead. The policy is right here, so every
+ * candidate is checked against it **now**: if the role would be allowed today,
+ * it is not a wall, whatever the log says. Same move as `owners` and the
+ * request queue — recompute rather than believe — and it means a grant makes
+ * its wall disappear on the next turn instead of two days later.
+ *
+ * A window is still accepted, and still useful for a different reason: a
+ * refusal from three weeks ago is noise even if it is still refused today.
+ */
+import { openSync, readSync, closeSync, statSync } from "node:fs";
+import { read } from "./log.js";
+import { explain } from "./owners.js";
+
+/** A wall is something you hit more than once. Once is information; twice is a pattern. */
+export const MIN_HITS = 2;
+
+/**
+ * What `role` keeps being denied, most-repeated first.
+ *
+ * Each entry is `{ action, target, times, reason, owners, firstAt, lastAt }`.
+ * The grain is action+target, not the directory above it: two writes into two
+ * different repositories are two walls, and merging them hides which one was
+ * hit.
+ */
+export function walls(config, role, { file, min = MIN_HITS, since = null, limit = 6 } = {}) {
+  const denied = read(file, { role, verdict: "denied", ...(since ? { since } : {}) });
+
+  const byKey = new Map();
+  for (const e of denied) {
+    if (!e.target || !e.action) continue;
+    const key = `${e.action}\u0000${e.target}`;
+    const seen = byKey.get(key);
+    if (seen) { seen.times++; seen.lastAt = e.at; continue; }
+    byKey.set(key, { action: e.action, target: e.target, times: 1, firstAt: e.at, lastAt: e.at });
+  }
+
+  const out = [];
+  for (const w of byKey.values()) {
+    if (w.times < min) continue;
+    // The policy as it stands, not as it stood. A granted wall is not a wall,
+    // and the whole point of saying this to an agent is that it is true now.
+    const verdict = explain(config, role, w.action, w.target);
+    if (verdict.allowed) continue;
+    out.push({ ...w, reason: verdict.reason, owners: verdict.owners });
+  }
+  out.sort((a, b) => b.times - a.times || a.target.localeCompare(b.target));
+  return limit > 0 ? out.slice(0, limit) : out;
+}
+
+/**
+ * How much of the log `timesHit` will look at.
+ *
+ * The log is append-only and never rotates — that is the storage design and it
+ * is the right one — so "read the file" is O(everything you have ever done),
+ * on a path that runs inside the hook. Measured on a 372 KB log: 3 ms per
+ * call, which is nothing, and 300 ms at 37 MB, which is not, on every refusal
+ * of every turn forever.
+ *
+ * So it reads the tail. That makes the count **recent repetition** rather than
+ * lifetime repetition, and recent is the one the sentence is about anyway: an
+ * agent being told "you have hit this three times" means this session, not
+ * last month. 4 MB is thousands of entries — far more than a turn produces,
+ * and bounded.
+ */
+const TAIL_BYTES = 4 * 1024 * 1024;
+
+/**
+ * How many times this exact denial is already in the recent log for this role.
+ *
+ * Deliberately NOT the same question as `walls()`: no policy recomputation, no
+ * threshold. The hook calls this while deciding, and the only thing it needs is
+ * a count — the policy has just been consulted, so asking it again would be
+ * asking a question already answered, in the one place that runs on every tool
+ * call.
+ */
+export function timesHit(file, role, action, target) {
+  let text;
+  try {
+    const { size } = statSync(file);
+    const from = Math.max(0, size - TAIL_BYTES);
+    const fd = openSync(file, "r");
+    try {
+      const buf = Buffer.alloc(size - from);
+      readSync(fd, buf, 0, buf.length, from);
+      text = buf.toString("utf8");
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return 0;                       // no log yet is not an error; it is a first turn
+  }
+  const lines = text.split("\n");
+  // The first line of a tail read is usually half an entry. Dropping it costs
+  // one count at most and keeps a truncated line from being parsed as if it
+  // were whole.
+  if (from0(text, file)) lines.shift();
+  let n = 0;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (e.role === role && e.verdict === "denied" && e.action === action && e.target === target) n++;
+  }
+  return n;
+}
+
+/** Did we start mid-file? Then the first line is a fragment. */
+function from0(text, file) {
+  try { return statSync(file).size > text.length; } catch { return false; }
+}
+
+/**
+ * The calls that went into hitting the same wall twice or more.
+ *
+ * `times - 1` per wall, because the first one is the agent finding out. Every
+ * one after that is the cost of not having been able to remember.
+ */
+export function wasted(list) {
+  return list.reduce((n, w) => n + w.times - 1, 0);
+}
+
+/**
+ * The block an agent reads, or `""` when there is nothing to say.
+ *
+ * Empty rather than "no walls found", because this goes into a prompt: a line
+ * that says nothing happened, every turn, is how an agent learns to skip the
+ * whole section — and then the one turn it matters, it is skipped too.
+ */
+export function render(list) {
+  if (!list.length) return "";
+  const lines = [
+    "WALLS — you have already been denied these, and the policy still denies them.",
+    "Do not retry; the reason is where the other way in is.",
+  ];
+  for (const w of list) {
+    lines.push(`  ${w.times}× ${w.action} ${w.target}`);
+    lines.push(`      ${w.reason}`);
+  }
+  const n = wasted(list);
+  // Said to the agent, not about it. One that can see what retrying cost has a
+  // reason to stop; one told "do not retry" has an instruction.
+  if (n > 0) lines.push(`  (${n} of your calls went into retrying these.)`);
+  return lines.join("\n") + "\n";
+}