seisin 0.1.0

package/src/render.js

@@ -0,0 +1,150 @@
+/**
+ * Everything that decides how output looks, and nothing that decides anything else.
+ *
+ * This exists because the commands used to do both. A function that computes a
+ * verdict and paints it in the same breath can only be tested by running the
+ * binary and matching a regular expression against its stdout — which is what
+ * the suite was doing eight times, and which tests the renderer as much as the
+ * logic. Split apart, the decision returns data and the test reads a field.
+ *
+ * Nothing here reads config, touches the filesystem, or exits. If a change to
+ * this file could alter what seisin allows, it is in the wrong file.
+ */
+
+/**
+ * ANSI codes, or empty strings when nobody is watching.
+ *
+ * Resolved once at import: a pipe does not become a terminal halfway through a
+ * command. `NO_COLOR` is honoured because this prints into logs and CI.
+ */
+export const C =
+  process.stdout.isTTY && !process.env.NO_COLOR
+    ? {
+        dim: "\x1b[2m", b: "\x1b[1m", off: "\x1b[0m",
+        red: "\x1b[31m", green: "\x1b[32m", yellow: "\x1b[33m", blue: "\x1b[34m",
+      }
+    : { dim: "", b: "", off: "", red: "", green: "", yellow: "", blue: "" };
+
+export const out = (s) => process.stdout.write(s);
+export const err = (s) => process.stderr.write(s);
+
+/* ── the map ──────────────────────────────────────────────────────────── */
+
+/** 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 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`);
+  }
+
+  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`);
+    lines.push("\n");
+  }
+
+  // Dim, and last: a standing limit is not an alarm, but it is not a footnote
+  // either — it is the part of the map that is blank.
+  for (const l of report.limits ?? []) {
+    lines.push(`  ${C.dim}${l.headline}${C.off}\n`);
+    if (l.detail) lines.push(`  ${C.dim}${l.detail}${C.off}\n`);
+    lines.push("\n");
+  }
+  return lines.join("");
+}
+
+/* ── one verdict ──────────────────────────────────────────────────────── */
+
+/** 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`;
+}
+
+/* ── the log ──────────────────────────────────────────────────────────── */
+
+/**
+ * One log entry, one line, always the same shape.
+ *
+ * Denials are amber and not red on purpose: a role stopped at its own border is
+ * the system working, and painting routine correctness as an error teaches
+ * people to stop reading the colour.
+ */
+export function renderEntry(e) {
+  const mark =
+    e.verdict === "denied" ? `${C.yellow}denied ${C.off}`
+    : e.verdict === "observed" ? `${C.dim}seen   ${C.off}`
+    : `${C.green}allowed${C.off}`;
+  const owners =
+    e.owners?.length && e.verdict === "denied" ? `  ${C.dim}→ ${e.owners.join(", ")}${C.off}` : "";
+  // Which writer saw this. The hook reports an attempt and can be talked
+  // around; the kernel reports a refusal and cannot. When the two disagree
+  // 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`;
+}
+
+/* ── the scan ─────────────────────────────────────────────────────────── */
+
+/**
+ * Two lists, never one.
+ *
+ * A provider-issued string and a line that merely mentions a password are
+ * different claims. Merging them is how a scanner earns a reputation for crying
+ * wolf, and the first real run of this one returned 200 findings of which 2
+ * mattered. The split is the whole reason the output is readable.
+ */
+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`];
+
+  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`);
+    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("\n");
+  }
+
+  if (review.length) {
+    const byFile = new Map();
+    for (const h of review) byFile.set(h.file, (byFile.get(h.file) ?? 0) + 1);
+    lines.push(`  ${C.yellow}${review.length} line(s) to look at${C.off} in ${byFile.size} file(s) — a secret-shaped name with a literal value\n\n`);
+    for (const [file, n] of [...byFile].slice(0, 15))
+      lines.push(`    ${file}${C.dim}${n > 1 ? `  ×${n}` : ""}${C.off}\n`);
+    if (byFile.size > 15) lines.push(`    ${C.dim}… and ${byFile.size - 15} more file(s)${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.
+  if (links.length) {
+    lines.push(`  ${C.yellow}${links.length} symlink(s) out of the repo${C.off} — present in the tree, stored somewhere else\n\n`);
+    for (const h of links.slice(0, 15)) lines.push(`    ${C.b}${h.file}${C.off} ${C.dim}→${C.off} ${h.shape}\n`);
+    lines.push("\n");
+  }
+
+  // What was thrown away matters as much as what was kept: it is the only way
+  // to tell a quiet scan from a broken one.
+  const quiet = [];
+  if (skipped.reference) quiet.push(`${skipped.reference} value(s) read from the environment`);
+  if (skipped.placeholder) quiet.push(`${skipped.placeholder} placeholder(s)`);
+  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`);
+  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

@@ -0,0 +1,259 @@
+/**
+ * The queue of permissions 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
+ * 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
+ * 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
+ * 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
+ * person can act on in one command instead of in an editor. See
+ * `docs/permission-requests.md` for why approving 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
+ * deleted — it is followed by a line saying what happened to it.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { STATE_DIR, tomlString } from "./layout.js";
+import { send } from "./spool.js";
+
+export const REQUESTS_NAME = "requests.jsonl";
+
+export function requestsPath(root) {
+  return join(root, STATE_DIR, REQUESTS_NAME);
+}
+
+/**
+ * Identity of a request: the same role wanting the same kind of access to the
+ * same place is one request asked twice, not two requests.
+ *
+ * The path is generalised to its directory on purpose. An agent denied on
+ * `src/api/a.ts` and then on `src/api/b.ts` is not asking two questions, and a
+ * queue that says it is becomes a queue nobody reads.
+ */
+export function keyOf({ role, action, target }) {
+  // A line can arrive malformed — a killed process, or something inside the
+  // sandbox writing to the queue on purpose. Reading the queue must not be the
+  // thing that fails: `seisin run` prints it on the way out and the console
+  // polls it, so a crash here takes down the half of the tool a person uses.
+  const t = typeof target === "string" ? target : "";
+  const dir = action === "read" ? t : t.split("/").slice(0, -1).join("/") || ".";
+  return `${role}:${action}:${dir}`;
+}
+
+/** The glob a grant would add, derived from what was asked. */
+export function grantFor({ action, target }) {
+  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
+  // and another one of the same name is what gets read.
+  if (action === "read") return t.includes("/") ? t : t.replace(/^.*\//, "");
+  const dir = t.split("/").slice(0, -1).join("/");
+  return dir ? `${dir}/**` : t;
+}
+
+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");
+    return true;
+  } catch {
+    // Same rule as the log: never take the agent down over bookkeeping.
+    return false;
+  }
+}
+
+/** Records that a role asked for something the policy denies it. Safe to call
+ *  on every denial; `seisin run` drops anything the policy does not refuse. */
+export function record(file, { role, action, target, owners }) {
+  return write(file, { kind: "asked", key: keyOf({ role, action, target }), role, action, target, owners: owners ?? [] });
+}
+
+/** Records a decision. `by` is always a person; there is no other caller. */
+export function settle(file, key, decision, reason = "") {
+  return write(file, { kind: decision, key, reason });
+}
+
+/**
+ * Records what the execution plane last tried to do about a request, which is a
+ * different question from what a person decided about it.
+ *
+ * `settle` answers "did the authority change?". This answers "what happened to
+ * the work?" — handed to the owner, stopped by a cycle, held back by a budget.
+ * They are kept apart deliberately: a request whose handoff was throttled is
+ * still `pending`, because nobody has decided anything about it. Writing the
+ * outcome into `state` would make admission look like a verdict.
+ *
+ * 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.
+ */
+export function recordHandoff(file, key, decision = {}) {
+  const { type, role, limit, max, reason, depth, chainId, revision } = decision;
+  return write(file, {
+    kind: "handoff", key, outcome: type ?? "unknown",
+    ...(role !== undefined && { role }),
+    ...(limit !== undefined && { limit }),
+    ...(max !== undefined && { max }),
+    ...(reason !== undefined && { reason }),
+    ...(depth !== undefined && { depth }),
+    ...(chainId != null && { chainId }),
+    ...(revision != null && { revision }),
+  });
+}
+
+/**
+ * The queue as it stands: one entry per distinct request, with how many times
+ * 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.
+ */
+export function pending(file, { includeSettled = false } = {}) {
+  if (!existsSync(file)) return [];
+  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
+    }
+    if (!e.key) continue;
+
+    if (e.kind === "asked") {
+      const seen = byKey.get(e.key);
+      if (seen) { seen.times++; seen.last = e.at; continue; }
+      byKey.set(e.key, {
+        key: e.key, role: e.role, action: e.action, target: e.target,
+        owners: e.owners ?? [], grant: grantFor(e),
+        times: 1, first: e.at, last: e.at, state: "pending", reason: "",
+      });
+      continue;
+    }
+    const seen = byKey.get(e.key);
+    if (!seen) continue;
+
+    /**
+     * Two lifecycles in one file, and only one of them is `state`.
+     *
+     * 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.
+     */
+    if (e.kind === "handoff") {
+      seen.handoff = {
+        outcome: e.outcome, role: e.role, limit: e.limit, max: e.max,
+        reason: e.reason, depth: e.depth, chainId: e.chainId, at: e.at,
+      };
+      continue;
+    }
+
+    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");
+}
+
+/**
+ * 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.
+ */
+export function applyGrant(toml, request, note = "") {
+  const field = request.action === "read" ? "keys" : "writes";
+  const header = new RegExp(`^\\[roles\\.${escapeRe(request.role)}\\]\\s*$`, "m");
+  const at = header.exec(toml);
+  if (!at) throw new Error(`no [roles.${request.role}] section to grant into`);
+
+  // The section runs from its header to the next table header, or to the end.
+  const from = at.index + at[0].length;
+  const next = /^\[[^\]]+\]\s*$/m.exec(toml.slice(from));
+  const 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)
+    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.`
+    );
+
+  // 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.
+  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 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]`);
+  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.
+ *
+ * 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.
+ */
+export function cleanReason(s) {
+  return String(s ?? "")
+    .replace(/[\r\n\t]/g, " ")
+    .replace(/["\\]/g, "'")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 240);
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/review.js

@@ -0,0 +1,167 @@
+/**
+ * What the log says about the policy.
+ *
+ * Everything here is arithmetic over `.seisin/log.jsonl` and the config. No
+ * model, no network, no heuristics that could be wrong in an interesting way —
+ * and that is deliberate rather than modest. This project's whole argument is
+ * that interpreting text is the wrong way to decide things; adding something
+ * that reads the log and forms an opinion would contradict it on the way in.
+ *
+ * Three questions, and the second is the one nothing else can answer.
+ *
+ *   1. What is a role being stopped by, over and over?
+ *      Forty denials on one directory is not an agent misbehaving. It is a
+ *      policy that is wrong, and today it reads as forty tidy amber lines
+ *      nobody adds up.
+ *
+ *   2. What was granted and never used?
+ *      Every permission file only ever grows, everywhere, and the reason is
+ *      always the same: nobody can prove a line is dead, so the safe move is to
+ *      leave it. Here the log can prove it. This is the only direction that
+ *      makes a policy smaller.
+ *
+ *   3. What does nobody own?
+ *      `explain` says it one path at a time. Added up, it is the shape of the
+ *      hole in the map.
+ *
+ * Every answer carries the window it was computed over, because "never used"
+ * means nothing without "…in how long".
+ */
+import { read, logPath } from "./log.js";
+import { covers, ownersOf } from "./owners.js";
+
+/**
+ * One reading of the log against the policy.
+ *
+ * `minDenials` is the point at which repetition stops being an accident. Three
+ * is low on purpose: the cost of mentioning it is a line, and the cost of
+ * missing it is a role that quietly cannot do its job.
+ */
+export function review(config, { minDenials = 3 } = {}) {
+  const entries = read(logPath(config.root), { limit: 0 });
+
+  if (entries.length === 0)
+    return { window: null, entries: 0, friction: [], guarded: [], unused: [], unusedKnowable: false, unowned: [] };
+
+  const at = entries.map((e) => e.at).filter(Boolean).sort();
+  const window = { from: at[0], to: at[at.length - 1], entries: entries.length };
+
+  return { window, entries: entries.length, ...findings(config, entries, minDenials) };
+}
+
+function findings(config, entries, minDenials) {
+  /* ── 1. what keeps stopping a role ──────────────────────────────────── */
+
+  /**
+   * Two piles, because they are two different decisions and only one of them is
+   * "grant it".
+   *
+   * A role stopped at another role's territory is a policy question: either the
+   * territory is drawn wrong or the work belongs to somebody else. That is what
+   * the advice *grant, or move the territory* is for.
+   *
+   * A role stopped at a `[keys] dir` is **the policy working**. A key directory
+   * is closed to everyone — nobody holds it, so there is nobody to hand the work
+   * to — and it is the one place where a grant is never the answer.
+   *
+   * Counting them together was not cosmetic. Measured against a real repository:
+   * six of the eight lines at the top of this report were key directories, so
+   * the strongest recommendation this tool made about that repo was to grant two
+   * roles the credential directory. The distinction sat in the config the whole
+   * time and this report was the only thing not using it.
+   */
+  const stopped = new Map();                 // role + directory -> how often
+  for (const e of entries) {
+    if (e.verdict !== "denied" || !e.target) continue;
+    const dir = e.action === "read" ? e.target : dirOf(e.target);
+    const key = `${e.role} ${e.action} ${dir}`;
+    const seen = stopped.get(key) ?? {
+      role: e.role, action: e.action, where: dir, times: 0,
+      owners: e.owners ?? [],
+      // Carried by the log from both writers — the hook sets it from the config
+      // and so does the parent for a kernel denial. Recomputing it from the path
+      // here would be a second opinion on a settled question.
+      kind: e.kind === "key" ? "key" : "file",
+    };
+    seen.times++;
+    stopped.set(key, seen);
+  }
+
+  const repeated = [...stopped.values()]
+    .filter((f) => f.times >= minDenials)
+    .sort((a, b) => b.times - a.times);
+
+  const friction = repeated.filter((f) => f.kind !== "key");
+  const guarded = repeated.filter((f) => f.kind === "key");
+
+  /* ── 2. what was granted and never used ─────────────────────────────── */
+
+  /**
+   * This question refuses to answer when the log cannot support an answer, and
+   * that refusal is the whole of the second finding.
+   *
+   * "Never used" is read off `allowed` lines, and **only the hook writes those**.
+   * The kernel reports what it refused; it has nothing to say about what went
+   * through. So a log with no hook behind it holds denials and nothing else,
+   * every grant falls through as unused, and this section reports that the whole
+   * policy is dead — under a heading calling itself the only evidence anyone
+   * will ever have for making a permission file smaller.
+   *
+   * Measured on a real repository with the hook not installed: every write
+   * permission of every role listed as never used, while those roles were
+   * working.
+   *
+   * It became reachable the day the kernel started writing here. Before that an
+   * unwired repo had an empty log and this section said nothing, which was
+   * accidentally right. A partial input is more dangerous than no input, because
+   * it looks like an answer.
+   *
+   * So: no `allowed` line in the window, no answer. `unused` stays empty rather
+   * than full — a consumer that has never heard of `unusedKnowable` then reports
+   * nothing instead of everything, which is the direction this has to fail in.
+   */
+  const knowable = entries.some((e) => e.verdict === "allowed");
+
+  // Only writes. A key that is declared and not read is ordinary — most roles
+  // hold a credential for the one turn a month that needs it — but a folder a
+  // role owns and has never written to in the whole log is a line nobody would
+  // miss, and the only evidence anyone will ever have for removing it.
+  const used = new Set();
+  for (const e of entries) {
+    if (e.verdict !== "allowed" || e.action !== "write" || !e.target) continue;
+    for (const role of Object.values(config.roles))
+      for (const glob of role.writes)
+        if (role.name === e.role && covers(glob, e.target)) used.add(`${role.name} ${glob}`);
+  }
+
+  const unused = [];
+  if (knowable)
+    for (const role of Object.values(config.roles))
+      for (const glob of role.writes)
+        if (!used.has(`${role.name} ${glob}`)) unused.push({ role: role.name, glob });
+
+  /* ── 3. what nobody owns ────────────────────────────────────────────── */
+
+  const unowned = new Map();
+  for (const e of entries) {
+    if (!e.target || e.kind === "key") continue;
+    if (ownersOf(config, e.target).length) continue;
+    const dir = dirOf(e.target);
+    unowned.set(dir, (unowned.get(dir) ?? 0) + 1);
+  }
+
+  return {
+    friction,
+    guarded,
+    unused,
+    unusedKnowable: knowable,
+    unowned: [...unowned.entries()]
+      .map(([where, times]) => ({ where, times }))
+      .sort((a, b) => b.times - a.times),
+  };
+}
+
+/** The directory a path sits in, or "." for a bare filename. */
+function dirOf(p) {
+  return p.split("/").slice(0, -1).join("/") || ".";
+}