seisin 0.1.1 → 0.3.0

package/src/inspect.js

@@ -8,11 +8,15 @@
  * does — each one is a way the policy silently does not hold — so they belong
  * where they can be exercised directly.
  */
-import { resolve, dirname, basename, relative } from "node:path";
-import { realpathSync, lstatSync, readdirSync } from "node:fs";
-import { ownersOf } from "./owners.js";
+import { resolve, dirname, basename, relative, join, delimiter } from "node:path";
+import { realpathSync, lstatSync, readdirSync, existsSync, readFileSync, statSync } from "node:fs";
+import { ownersOf, covers, enforcedNeverWrites } from "./owners.js";
+import { ROLE_KEYS } from "./config.js";
+import { entriesOf } from "./keys.js";
+import { SHAPES } from "./scan.js";
 import { wired } from "./commands/wire.js";
 import { RUNTIME_WRITES, CREDENTIAL_HOMES, expand, settingsFor } from "./srt.js";
+import { protections, resolveExecutable } from "./surface.js";
 
 /**
  * A report on one config: the roles, and every way the map lies.
@@ -27,8 +31,27 @@ export function inspect(config, only = null, where = config.path) {
 
   return {
     where,
-    roles: roles.map((r) => ({ name: r.name, writes: r.writes, keys: r.keys })),
+    roles: roles.map((r) => ({ name: r.name, writes: r.writes, keys: r.keys, neverWrites: r.neverWrites ?? [], localBinding: r.localBinding === true, localPorts: r.localPorts ?? [], mcp: r.mcp ?? null, trustd: r.trustd === true })),
+    /**
+     * The provider commands this config would run, listed because they are the
+     * one thing in a `seisin.toml` that **executes**, and it executes in the
+     * parent, unsandboxed, as you. Everything else in the file only describes a
+     * boundary. `check` runs nothing, so this is where you see them first — and
+     * seeing them first is the whole point when the file came with a repo you
+     * cloned rather than one you wrote.
+     */
+    providers: Object.values(config.keyProviders ?? {}).map((p) => ({
+      name: p.name, command: p.command, mode: p.mode,
+    })),
     shared: sharedPaths(config, roles),
+    /**
+     * What the kernel will refuse a role inside its own territory, and why:
+     * programs installed where a role writes, the hooks and settings of each
+     * project, provider scripts and `file://` targets. Each takes something
+     * away from a territory as written, so it is shown rather than applied
+     * quietly. See surface.js for the family and the measurements.
+     */
+    protected: protections(config, roles),
     warnings: warningsFor(config, roles),
     limits: LIMITS,
   };
@@ -56,7 +79,7 @@ const LIMITS = [
       "equivalent to read here — bubblewrap does not log refusals, and the runtime's substitute " +
       "is not reachable from outside it. The boundary holds exactly as well; what you lose is " +
       "seeing it work. Run `seisin wire` so the hook records what it can. The ask is upstream: " +
-      "github.com/carlostapiaolguin3-stack/seisin/blob/main/docs/upstream/cli-violations.md",
+      "github.com/carlostapiacl/seisin/blob/main/docs/upstream/cli-violations.md",
   }]),
   {
     kind: "keys-only-what-you-declared",
@@ -76,7 +99,25 @@ const LIMITS = [
       "library can read them; nothing reaches a caller that runs the binary, which is what " +
       "seisin does. So for an agent whose endpoints are not published, the options are to " +
       "find them another way or drop the network restriction for it. The ask is upstream: " +
-      "github.com/carlostapiaolguin3-stack/seisin/blob/main/docs/upstream/cli-violations.md",
+      "github.com/carlostapiacl/seisin/blob/main/docs/upstream/cli-violations.md",
+  },
+  ...(process.platform === "linux" ? [{
+    kind: "control-files-linux",
+    headline: "a project's hooks and settings are protected only where they already exist",
+    detail:
+      "bubblewrap denies a path by mounting over it, and for a path that is not there it would " +
+      "create it on your disk. So on Linux a role can still create a .git/hooks entry or a " +
+      ".claude/settings.json in a project of its territory that had none. On macOS the kernel " +
+      "refuses creating them too.",
+  }] : []),
+  {
+    kind: "shared-scratch",
+    headline: "roles share ~/.cache, ~/.local/share and the temp dir unless isolate = \"home\"",
+    detail:
+      "programs installed there that are on your PATH are protected, and so are Claude Code's " +
+      "settings and plugins. Anything else a program outside the box reads from those places — a " +
+      "cache it executes, a tool not on PATH — is writable by every role. isolate = \"home\" " +
+      "gives each role its own.",
   },
   {
     kind: "unlink-uncovered",
@@ -86,10 +127,127 @@ const LIMITS = [
       // package, so for most readers it named a file they do not have.
       "writes and deletes are one permission to the kernel, so `rm` inside a " +
       "role's own folders succeeds. Closing it needs denyUnlink in the sandbox " +
-      "runtime: github.com/carlostapiaolguin3-stack/seisin#how-it-holds",
+      "runtime: github.com/carlostapiacl/seisin#how-it-holds",
   },
 ];
 
+/**
+ * What is wrong with a role table's keys, as opposed to its paths.
+ *
+ * Two things, both about `never_writes` and both ways a subtraction can look
+ * written and not be:
+ *
+ *   - a key seisin does not know. It used to be dropped without a word, which
+ *     for `writes` is a role with less than it thinks, and for a misspelt
+ *     `never_writes` is a role with MORE than its owner thinks — the one
+ *     direction a permission file must not fail in. Named with the nearest
+ *     known key when there is one close enough to be the intended spelling.
+ *   - a `never_writes` entry that no `writes` of the same role covers. It
+ *     subtracts from nothing, so it is either a typo in the path or a rule
+ *     that stopped applying when the territory moved. Either way it reads as
+ *     protection and is not.
+ *
+ * Silent when `never_writes` is absent. Absent is valid; a check that asks for
+ * the key would turn an optional subtraction into a required migration.
+ */
+function roleKeyWarnings(roles, config = null) {
+  const warnings = [];
+  for (const r of roles) {
+    const enforced = new Set(enforcedNeverWrites(config, r));
+    const skipped = (r.neverWritesDeclared ?? r.neverWrites ?? []).filter((g) => !enforced.has(g));
+    if (skipped.length)
+      warnings.push({
+        kind: "never-writes-not-enforced-here",
+        headline: `${r.name}: never_writes ${skipped.join(" ")} — not enforced on Linux until it exists`,
+        detail: "bubblewrap denies a path by mounting over it, and would create a missing one on the host " +
+          "for the whole run — for a lock file, locking everyone else out, and for good if the role is " +
+          "killed. seisin skips those, and explain says allowed for them, so the sentence matches the kernel.",
+      });
+    for (const k of r.unknownKeys ?? []) {
+      const near = nearest(k, ROLE_KEYS);
+      warnings.push({
+        kind: "unknown-role-key",
+        headline: `${r.name}: unknown key "${k}" in [roles.${r.name}] — ignored` +
+          (near ? `. Did you mean "${near}"?` : ""),
+        detail: `Known keys: ${ROLE_KEYS.join(", ")}. ` +
+          (near === "never_writes"
+            ? "As written this subtracts nothing: the role can still write every path it lists."
+            : "Nothing in it takes effect."),
+      });
+    }
+    // macOS only, and not by omission: on Linux the runtime removes the network
+    // namespace, so every role already has a loopback of its own — it can serve
+    // and reach its own server with or without the key, and reaches nothing on
+    // the host either way (measured in Docker, Debian 12, bwrap 0.8.0).
+    if (r.localBinding && process.platform === "darwin")
+      warnings.push({
+        kind: "local-binding-reaches-localhost",
+        headline: `${r.name}: local_binding lets it connect to every port on localhost, not only listen`,
+        detail: "The runtime grants bind on any interface, inbound, and outbound to localhost:*. " +
+          "Anything listening on this machine without authentication — a local control API, a " +
+          "database, a dev server — is within this role's reach, outside its territory.",
+      });
+    // Both at once is a config that says "these ports" and grants "every port".
+    // macOS only: on Linux local_binding reaches nothing on the host, so there
+    // local_ports is the only one of the two that does anything.
+    if (r.localBinding && r.localPorts?.length && process.platform === "darwin")
+      warnings.push({
+        kind: "local-ports-moot",
+        headline: `${r.name}: local_ports names ${r.localPorts.join(", ")}, but local_binding already opens every localhost port`,
+        detail: "local_binding grants outbound to localhost:* in the kernel profile, so the port list " +
+          "restricts nothing for this role. Drop local_binding if the role only needs to reach " +
+          "those ports; keep it only if the role has to listen.",
+      });
+    // trustd is a macOS service; on Linux the key changes nothing.
+    if (r.trustd && process.platform === "darwin")
+      warnings.push({
+        kind: "trustd-open",
+        headline: `${r.name}: trustd = true opens com.apple.trustd.agent, a path out that the domain list does not see`,
+        detail: "trustd verifies certificates for Go (before 1.27) and Dart on macOS, and to do it fetches, " +
+          "outside the sandbox, the URLs a certificate carries. The runtime calls it an exfiltration vector; " +
+          "no public demonstration exists. Go 1.27+ does not need it: seisin sets SSL_CERT_FILE.",
+      });
+    for (const g of r.neverWrites ?? []) {
+      if (r.writes.some((w) => covers(w, g) || covers(w, g.replace(/\/\*\*$/, ""))))
+        continue;
+      warnings.push({
+        kind: "never-writes-subtracts-nothing",
+        headline: `${r.name}: never_writes "${g}" is not inside any of its writes`,
+        detail: "It denies something that was already denied, so it protects nothing. " +
+          "Check the path, or drop the entry if the territory moved.",
+      });
+    }
+  }
+  return warnings;
+}
+
+/** The candidate within edit distance 3 of `word`, or null. */
+function nearest(word, candidates) {
+  // Spellings of the same idea in another vocabulary, checked first because
+  // letters mislead here: `no_writes` is three edits from `writes`, and
+  // suggesting the grant for a misspelt subtraction is the worst answer.
+  if (/deny|never|no_?write/i.test(word)) return "never_writes";
+  let best = null, bestD = 4;
+  for (const c of candidates) {
+    const d = distance(word.toLowerCase(), c);
+    if (d < bestD) { best = c; bestD = d; }
+  }
+  return best;
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]; row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cur = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return row[b.length];
+}
+
 /**
  * Paths more than one role claims.
  *
@@ -102,7 +260,21 @@ export function sharedPaths(config, roles = Object.values(config.roles)) {
   for (const r of roles)
     for (const glob of r.writes)
       if (ownersOf(config, glob.replace(/\/\*\*$/, "")).length > 1) seen.add(glob);
-  return [...seen];
+  /**
+   * A shared database counts once, not four times.
+   *
+   * `writes` carries the sidecar expansion so that the grant and the sentence
+   * agree (see config.js), and this list read straight off it turned nine
+   * shared things into thirty-three — the same name with three suffixes,
+   * announced as if it were three more decisions to make. The expansion exists
+   * to stop a policy saying one thing four times; a warning that undoes that
+   * is the feature leaking into the place it was meant to clean up.
+   *
+   * A sidecar shared WITHOUT its database still counts on its own, because
+   * that is a real and odd thing to have.
+   */
+  const todas = new Set(seen);
+  return [...seen].filter((p) => !(/-(wal|shm|journal)$/.test(p) && todas.has(p.replace(/-(wal|shm|journal)$/, ""))));
 }
 
 /**
@@ -147,6 +319,58 @@ function homeReachWarning(config) {
 
 
 /** Every way this policy does not hold, each with what to do about it. */
+/**
+ * Credential-shaped names at the top of the repository, and nothing deeper.
+ *
+ * One `readdir`, no recursion, conventional names only. It exists to answer
+ * "does this repo plausibly have secrets" fast enough to run on every `check`,
+ * not to find them — `seisin scan` is the one that looks properly.
+ */
+const CREDENTIAL_NAMES = /^(\.env(\..+)?|\.secrets|secrets|\.netrc|.*\.(pem|key|p12|pfx))$/i;
+
+function credentialish(root) {
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = new Set(entries.filter((e) => CREDENTIAL_NAMES.test(e.name)).map((e) => e.name));
+
+  /**
+   * And the ones whose name gives nothing away.
+   *
+   * The name test misses `credentials.txt`, `tokens.conf`, `config.local` —
+   * which a field review found by writing a test file this did not catch, and
+   * then blaming the test. The test was fine; the detector was name-only.
+   *
+   * So the root's small text files are also read, with the same shapes
+   * `seisin scan` uses. Root only, small only, and it stops at the first hit
+   * per file: this runs on every `check` and the full walk is `scan`'s job.
+   */
+  const CERTAIN = SHAPES.filter(([c]) => c === "certain").map(([, , re]) => re);
+  for (const e of entries) {
+    if (found.size >= 4) break;
+    if (!e.isFile() || found.has(e.name)) continue;
+    try {
+      const p = join(root, e.name);
+      if (statSync(p).size > 64 * 1024) continue;
+      const text = readFileSync(p, "utf8");
+      if (CERTAIN.some((re) => re.test(text))) found.add(e.name);
+    } catch {
+      /* unreadable, or not text: not our business here */
+    }
+  }
+  return [...found].sort().slice(0, 4);
+}
+
+/** Is this a command the shell would find? Walks PATH; asks no shell. */
+function onPath(cmd) {
+  if (cmd.includes("/")) return existsSync(cmd);
+  const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  return dirs.some((d) => existsSync(join(d, cmd)));
+}
+
 function warningsFor(config, roles) {
   const warnings = [];
 
@@ -168,6 +392,34 @@ function warningsFor(config, roles) {
       });
     }
   }
+  warnings.push(...roleKeyWarnings(roles, config));
+
+  // A provider the parent could not find where no role writes. `run` refuses
+  // it with the same sentence; here it is found before anybody runs anything.
+  for (const [scheme, p] of Object.entries(config.keyProviders ?? {})) {
+    const cmd = p.command?.[0];
+    if (!cmd || cmd.includes("/")) continue;
+    try { resolveExecutable(cmd, config); } catch (e) {
+      if (!/a role can write/.test(e.message)) continue;
+      warnings.push({
+        kind: "provider-in-territory",
+        headline: `the ${scheme}:// provider "${cmd}" is only found where a role can write`,
+        detail: e.message.split("\n").slice(1).map((l) => l.trim()).join(" "),
+      });
+    }
+  }
+
+  // PATH entries that are not absolute resolve against wherever the parent is
+  // standing, which is the repo. They are ignored for every lookup seisin makes
+  // outside the box; said here because a lookup that skips them can find a
+  // different program than your shell does.
+  const unanchored = (process.env.PATH ?? "").split(delimiter).filter((d) => !d || !d.startsWith("/"));
+  if (unanchored.length)
+    warnings.push({
+      kind: "relative-path",
+      headline: `PATH has ${unanchored.length} relative entr${unanchored.length === 1 ? "y" : "ies"} (${unanchored.map((d) => JSON.stringify(d)).join(", ")})`,
+      detail: "They resolve inside the repo, where roles write, so seisin skips them when it looks for a program to run outside the box.",
+    });
   const shared = sharedPaths(config, roles);
 
   if (shared.length)
@@ -400,13 +652,84 @@ function warningsFor(config, roles) {
       });
   }
 
-  if (config.keyDirs.length === 0 && Object.values(config.roles).some((r) => r.keys.length))
+  /**
+   * A policy with no credential floor at all, in a repo that has credentials.
+   *
+   * `[keys] dir` is what produces `denyRead`. Without it the emitted settings
+   * carry an empty deny list, so every role reads every secret in the
+   * repository — and until this warning, nothing said so. The existing
+   * `keys-unscoped` only fires when a role *lists* keys, which is the case
+   * where somebody already thought about it.
+   *
+   * The dangerous shape is the other one, and it is not hypothetical: a policy
+   * generated by a script. The deployment this was built against generates its
+   * `seisin.toml` from a Python program, and declares `[keys] dir` mostly so
+   * `scan` skips those directories. A generator that dropped that one line
+   * would hand every role the credential tree and produce a clean `check`.
+   *
+   * Credit where it is due: this is `L-01` of a code review of another
+   * project's contract type, which makes its credential floor impossible to
+   * construct empty. That is the right shape and it is a bigger change than a
+   * warning. This is the cheap half — and the review's claim that the file
+   * path was safe turned out to be generous: it was not.
+   *
+   * Deliberately NOT a full `seisin scan`: that walks the tree and `check` has
+   * to stay instant. A shallow look at the repository root catches the
+   * conventional places and costs one `readdir`.
+   */
+  if ((config.keyDirs ?? []).length === 0) {
+    const found = credentialish(config.root);
+    if (found.length)
+      warnings.push({
+        kind: "no-key-floor",
+        headline: `no [keys] dir is declared, and this repo has ${found.join(", ")} — every role can read them`,
+        detail:
+          "Without a key directory the emitted policy denies no reads at all. Declare the " +
+          "directory your secrets live in, and the roles that may read each one.",
+      });
+  }
+
+  // Only a key that is a PATH needs a key directory. A config whose secrets all
+  // live in a vault has no `[keys] dir` and nothing wrong with it, and warning
+  // there would be the tool insisting on the arrangement it was built for.
+  if (config.keyDirs.length === 0 &&
+      Object.values(config.roles).some((r) => entriesOf(r).some((k) => k.kind === "file")))
     warnings.push({
       kind: "keys-unscoped",
       headline: "keys are listed but [keys] dir is unset — nothing will be scoped",
       detail: null,
     });
 
+  /**
+   * A provider whose command is not on PATH.
+   *
+   * This is the half of validating references that can be done without
+   * resolving one — which is the whole requirement: a broken policy has to be
+   * visible in `check`, not on the first run, and certainly not by asking
+   * somebody's keychain for a password to find out. The scheme and the
+   * provider are checked when the config loads, so by the time we are here
+   * they exist; what is left is whether the command does.
+   *
+   * A warning and not an error: the binary can legitimately be missing on the
+   * machine reading the policy and present on the one that runs it, which is
+   * every CI checkout.
+   */
+  const used = new Set();
+  for (const r of Object.values(config.roles))
+    for (const k of entriesOf(r)) if (k.kind === "ref") used.add(k.scheme);
+  for (const scheme of [...used].sort()) {
+    const provider = config.keyProviders?.[scheme];
+    if (!provider || onPath(provider.command[0])) continue;
+    warnings.push({
+      kind: "provider-missing",
+      headline: `the ${scheme} provider runs "${provider.command[0]}", which is not on PATH`,
+      detail:
+        "every key of that scheme will stop the run rather than resolve. Nothing is " +
+        "substituted for a key that did not resolve, so this fails closed — but it fails " +
+        "at the start of a turn, not here.",
+    });
+  }
+
   return warnings;
 }
 

package/src/intake.js

@@ -0,0 +1,215 @@
+/**
+ * The parent's intake: what arrives during a run, checked, and written down.
+ *
+ * Two sources, and they are not equally trustworthy. The hook runs inside the
+ * box, so everything it sends is a claim by the process being recorded. The
+ * kernel is the thing that actually refused. Both end up as log lines and,
+ * sometimes, as requests in front of a person; this module is where each is
+ * recomputed from the policy rather than believed.
+ *
+ * Every line written here carries two fields that make it evidence rather
+ * than a sentence:
+ *
+ *   - `run`, the id of the run that produced it — the same id as the nonce in
+ *     the kernel's command tag and the run's private directory (rundir.js).
+ *     Before, the log had no run marker and "how many runs since" was guessed
+ *     from 10-minute gaps.
+ *   - `policy`, a hash of the policy file the run STARTED with. The kernel
+ *     enforces that one for the whole run, whatever happens to the file
+ *     afterwards, and `review` reading today's policy over last week's lines
+ *     could not tell a grant made since from one that was always there.
+ *
+ * Pulled out of run.js, which held both handlers inline between the spawn and
+ * the signal handling — 180 lines of policy arithmetic inside the launcher.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { toRepoRelative } from "./paths.js";
+import { explain, ownersOf } from "./owners.js";
+import { append, logPath } from "./log.js";
+import { record, requestsPath } from "./requests.js";
+import { inScope, scopeOf, reachedForContent } from "./violations.js";
+
+/** A hash of the policy file as it is now, short: it names a version, it proves nothing. */
+export function policyId(config) {
+  try {
+    return createHash("sha256").update(readFileSync(config.path)).digest("hex").slice(0, 12);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The handlers for one run.
+ *
+ * `fromHook(to, entry)` is the spool's sink; `fromKernel(denial)` is
+ * watchDenials' callback; `stats` counts what the kernel said that was left
+ * out on purpose, for the line at the end of the run.
+ */
+export function intake({ config, role, runId, observe = false, settings, notify }) {
+  const stamp = { run: runId.slice(0, 8), policy: policyId(config) };
+  const log = (entry) => append(logPath(config.root), { ...entry, ...stamp });
+  const ask = (asked) => { record(requestsPath(config.root), asked); notify?.maybe(asked); };
+
+  const scope = scopeOf(settings, config.root);
+  const keyDirs = (config.keyDirs ?? []).map((d) => (d.startsWith("/") ? d : join(config.root, d)));
+  const connects = new Set();         // one line per refused target per run
+  const stats = { offPolicy: 0, walks: 0 };
+
+  /**
+   * Nothing from inside the box is taken at its word.
+   *
+   * The sender is the process being recorded, so every field it supplies is
+   * a claim. Two of them matter. `role` decides whose request this is — left
+   * alone, a frontend agent could file one as backend and wait for a human to
+   * approve it. `owners` decides who the queue says it belongs to, and the
+   * parent can work that out itself from the policy.
+   *
+   * So the role is overwritten with the role of this run, the owners are
+   * recomputed, and anything shaped wrong is dropped. Forging a *log* line is
+   * noise. Forging a *request* is a sentence placed in front of a person for
+   * approval, and that is a different thing entirely.
+   */
+  function fromHook(to, entry) {
+    if (!entry || typeof entry !== "object") return;
+    if (entry.action !== "read" && entry.action !== "write") return;
+    if (typeof entry.target !== "string" || !entry.target.trim()) return;
+
+    if (to === "log") {
+      // The same treatment the queue already got. The role was overwritten but
+      // everything else was passed through, so a process inside the box could
+      // write "allowed" lines for paths it never touched — which would not move
+      // the boundary, but would move `review`, and `init --from-observations`
+      // builds a policy out of exactly this.
+      if (!["allowed", "denied", "observed"].includes(entry.verdict)) return;
+      /**
+       * The verdict is the hook's account of what it did, so it stays — but it
+       * is checked. The parent works out what the policy this run started with
+       * says, and when the two differ the line carries `disputed` with the
+       * parent's answer. Two causes, both worth seeing: the policy file changed
+       * since the run started (the hook reads it fresh, the kernel does not), or
+       * the line was not written by the hook at all.
+       */
+      const expected = observe
+        ? "observed"
+        : explain(config, role, entry.action, entry.target).allowed ? "allowed" : "denied";
+      return void log({
+        at: entry.at,
+        role,
+        tool: String(entry.tool ?? "").slice(0, 40),
+        action: entry.action,
+        kind: entry.kind === "key" ? "key" : "file",
+        target: entry.target.slice(0, 1000),
+        verdict: entry.verdict,
+        owners: ownersOf(config, entry.target),      // recomputed, never taken
+        reason: String(entry.reason ?? "").slice(0, 500),
+        ...(expected !== entry.verdict ? { disputed: expected } : {}),
+      });
+    }
+
+    /**
+     * The policy has to actually refuse it, or it does not belong in a queue.
+     *
+     * Nothing checked. A process inside the box could file a request for a path
+     * its own role already owns, and the queue would print *first refused on
+     * …* about something that was never refused — a sentence placed in front of
+     * a person for approval, describing an event that did not happen.
+     *
+     * Same treatment as `owners` above: the claim is recomputed here rather
+     * than believed. It is the policy answering a question about itself, which
+     * is arithmetic, and it is the parent asking — the one process the confined
+     * side cannot reach.
+     *
+     * This does not require the agent to have *tried*. Asking for a permission
+     * before reaching for it is a reasonable thing to do, and the wording says
+     * "asked" rather than "refused" for exactly that case. What it rules out is
+     * a request for something that is not refused at all — nor for a
+     * `never_writes` path, git's metadata, or a protected one, none of which a
+     * grant can open.
+     */
+    const v = explain(config, role, entry.action, entry.target);
+    if (v.allowed || v.neverWrites || v.gitMetadata || v.protected) return;
+    // The owners explain found: for a key that is who declares it, not who
+    // writes the directory it sits in — the queue said "owned by dev" about
+    // backend's key because dev writes `**`.
+    ask({ role, action: entry.action, target: entry.target, owners: v.owners });
+  }
+
+  function fromKernel(d) {
+    /**
+     * A refused connection: logged, never queued.
+     *
+     * Once per target per run, because the thing that dials a closed port is
+     * usually a readiness loop, and a loop polling a database every half second
+     * would otherwise write the log the size of the wait. And no request: a port
+     * is not a territory anyone owns, so there is nobody to hand it to — the
+     * sentence says what the policy would have to change instead.
+     */
+    if (d.action === "connect") {
+      if (connects.has(d.path)) return;
+      connects.add(d.path);
+      const v = explain(config, role, "connect", d.path);
+      log({
+        at: new Date().toISOString(), role, tool: "kernel", source: "kernel",
+        action: "connect", kind: "network", target: d.path, verdict: "denied",
+        owners: [], reason: d.operation, ...(v.listed ? { listed: true } : {}),
+      });
+      return;
+    }
+    if (!inScope(d.path, scope)) { stats.offPolicy++; return; }
+    if (!reachedForContent(d)) { stats.walks++; return; }
+    // Relative inside the repo, absolute outside it. A role can be refused at
+    // ~/.ssh under `isolate`, and "../../../.ssh/id_rsa" would be a worse
+    // answer to "what was refused" than the path itself.
+    const rel = toRepoRelative(config, d.path);
+
+    /**
+     * A refusal the hook never saw still leaves a request behind.
+     *
+     * Without this the two halves of the record disagree in the worst
+     * direction: `review` would show a role stopped repeatedly on a directory
+     * while the queue held nothing to approve, so the one refusal a person most
+     * needed to see — the one that escaped the hook — would be the one with no
+     * way to act on it.
+     *
+     * There is no double counting to avoid. When the hook catches something it
+     * denies the tool call outright and the command never runs, so the kernel
+     * never sees it. These are the ones that got past it, which is the whole
+     * reason this exists. Inside the repo only: `~/.ssh` is refused on purpose
+     * under `isolate` and is not a territory anyone is meant to ask for.
+     */
+    const verdict = rel !== d.path && d.action === "write"
+      ? explain(config, role, "write", rel)
+      : null;
+    const barred = verdict?.neverWrites ?? null;
+    const unaskable = verdict?.gitMetadata === true || verdict?.protected != null;
+    // A request for something the policy already grants cannot be approved into
+    // anything: it is misattribution or a kernel/policy mismatch, and either way
+    // the line in the log is the evidence, not a question for a person. The hook
+    // path has always had this check; the kernel path did not, which is how a
+    // role ended up asking for its own territory.
+    const granted = verdict?.allowed === true;
+    if (rel !== d.path && !barred && !unaskable && !granted)
+      ask({ role, action: d.action, target: rel, owners: ownersOf(config, rel) });
+
+    log({
+      at: new Date().toISOString(),
+      role,
+      tool: "kernel",
+      source: "kernel",
+      action: d.action,
+      kind: keyDirs.some((k) => d.path === k || d.path.startsWith(k + "/")) ? "key" : "file",
+      target: rel,
+      verdict: "denied",
+      owners: ownersOf(config, rel),
+      reason: d.operation,
+      // So the log can tell a subtraction doing its job from a missing permission,
+      // and a protected file from a territory somebody could be asked for.
+      ...(barred ? { neverWrites: barred } : {}),
+      ...(verdict?.protected ? { protected: verdict.protected } : {}),
+    });
+  }
+
+  return { fromHook, fromKernel, stats };
+}