seisin 0.5.0 → 0.6.0

package/src/mcp.js

@@ -16,7 +16,7 @@
  *
  * If granting were a tool here, an agent holding it could widen its own
  * territory and the record would say a human did it. See
- * `docs/permission-requests.md`.
+ * `docs/requests.md`.
  *
  * ── Why there is no SDK ──
  * The official SDK pulls 91 packages and 26 MB — express, hono, cors, jose —
@@ -29,13 +29,13 @@
 import { toRepoRelative } from "./paths.js";
 import { loadConfig, findConfig } from "./config.js";
 import { inspect } from "./inspect.js";
-import { explain, explainFileRead, ownersOf, readTarget } from "./owners.js";
-import { CREDENTIAL_HOMES, expand } from "./grants.js";
+import { explain, ownersOf } from "./owners.js";
 import { settingsFor } from "./srt.js";
-import { pending, requestsPath, refuseIfBarred, shellId } from "./requests.js";
+import { queueOf, queueData, refuseIfBarred, shellId } from "./requests.js";
 import { read, logPath } from "./log.js";
 import { causesOf, parseSince, queue as requestQueue, verdicts, wallsByRole } from "./views.js";
 import { walls, wasted } from "./walls.js";
+import { lineReader } from "./lines.js";
 
 /**
  * Versions this server will agree to.
@@ -80,9 +80,11 @@ const TOOLS = [
     name: "seisin_requests",
     description:
       "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.",
+      "times each was asked and where each goes: `handoff` is seisin's decision from the policy " +
+      "(route to the owning role, or a person decides; a cycle or a chain too deep stops). " +
+      "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, and nothing here " +
+      "starts a role, by design.",
     inputSchema: { type: "object", properties: {} },
   },
   {
@@ -105,7 +107,7 @@ const TOOLS = [
       "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 " +
+      "outside the repository) — and, per cause, `stillDenied`, how many of the roles " +
       "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 " +
@@ -119,7 +121,7 @@ const TOOLS = [
       type: "object",
       properties: {
         limit: { type: "number" },
-        since: { type: "string", description: "ISO date; only denials at or after it" },
+        since: { type: "string", description: "ISO date, or a duration back from now (7d, 12h); only denials at or after it" },
       },
     },
   },
@@ -165,6 +167,8 @@ const HANDLERS = {
     return {
       config: cfg.path,
       keyDirectories: cfg.keyDirs,
+      read: cfg.read,
+      isolate: cfg.isolate,
       roles: report.roles.map((r) => ({
         ...r,
         sandbox: settingsFor(cfg, r.name).filesystem,
@@ -194,10 +198,7 @@ const HANDLERS = {
     // 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));
+      return explain(cfg, role, "read", target, cfg.root);
     }
     const rel = toRepoRelative(cfg, target);
     const verdict = explain(cfg, role, action, rel);
@@ -206,13 +207,12 @@ const HANDLERS = {
 
   seisin_requests() {
     const cfg = config();
-    const queue = requestQueue(cfg.root, read(logPath(cfg.root)), cfg.keyDirs);
+    const queue = requestQueue(cfg, read(logPath(cfg.root)), { readOnly: true });
     return {
-      pending: queue.map((r, i) => ({
-        number: i + 1, id: r.key, role: r.role, action: r.action,
-        wants: r.grant, ownedBy: r.owners, asked: r.times, lastAsked: r.last,
-        ...(r.stale ? { stale: `not asked again in ${r.stale.runs} runs of ${r.role} since` } : {}),
-      })),
+      // The same shape as `seisin requests --json`, each with its handoff
+      // decision. Reading it tells an agent where its request goes; it cannot
+      // change where, and nothing here starts the role it names.
+      ...queueData(queue),
       // 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
@@ -274,7 +274,8 @@ const HANDLERS = {
 
   seisin_draft_grant({ id, number } = {}) {
     const cfg = config();
-    const queue = pending(requestsPath(cfg.root), { keyDirs: cfg.keyDirs });
+    // Owners as the policy says now, the same as seisin_requests shows.
+    const queue = queueOf(cfg, null, { readOnly: true });
     let req;
     if (typeof id === "string" && id) {
       req = queue.find((r) => r.key === id);
@@ -388,30 +389,14 @@ function handle(message, { write, version }) {
 export function serveMcp(version = "0.0.0", input = process.stdin, output = process.stdout) {
   const ctx = { version, write: (s) => output.write(s) };
   input.setEncoding("utf8");
-  let buffer = "";
-
-  input.on("data", (chunk) => {
-    buffer += chunk;
-    // A megabyte with no newline in it is not a JSON-RPC message, it is a
-    // client — or something wearing one — filling this process's memory.
-    // spool.js already caps its input; this one did not.
-    if (buffer.length > 1_000_000) {
-      buffer = "";
-      return;
-    }
-    let nl;
-    while ((nl = buffer.indexOf("\n")) !== -1) {
-      const line = buffer.slice(0, nl).trim();
-      buffer = buffer.slice(nl + 1);
-      if (!line) continue;
-      try {
-        handle(JSON.parse(line), ctx);
-      } catch {
-        // Unparseable input has no id to answer to, so there is nobody to tell.
-        // Staying alive is the only useful response.
-      }
+  input.on("data", lineReader((line) => {
+    try {
+      handle(JSON.parse(line), ctx);
+    } catch {
+      // Unparseable input has no id to answer to, so there is nobody to tell.
+      // Staying alive is the only useful response.
     }
-  });
+  }));
 
   return new Promise((done) => input.on("end", done));
 }

package/src/nested.js

@@ -41,7 +41,15 @@
 const SELF_SANDBOXING = {
   codex: {
     on: true,
-    off: ["--dangerously-bypass-approvals-and-sandbox"],
+    // `-s danger-full-access` first: it is the one to suggest. It turns off only
+    // the sandbox, and inside `seisin run` that is the whole change wanted —
+    // `--dangerously-bypass…` also turns off approvals, which says more than
+    // the situation needs. Warning about `-s danger-full-access` was a warning
+    // about a thing that was not happening: measured on 2026-09-30 with codex
+    // 0.150.1, a turn under seisin with that flag ran its commands and finished.
+    off: ["--sandbox=danger-full-access", "--dangerously-bypass-approvals-and-sandbox"],
+    // The same setting spelt as a flag and its value, two words.
+    offPairs: [["-s", "danger-full-access"], ["--sandbox", "danger-full-access"]],
     // The subcommand whose entire job is to confine. No flag turns that off.
     never: ["sandbox"],
   },
@@ -71,7 +79,8 @@ export function nestedSandboxWarning(cmd = []) {
       `  Run the command directly — seisin is already the boundary here.`
     );
 
-  const turnedOff = (spec.off ?? []).some((f) => rest.some((a) => a === f || a.startsWith(f + "=")));
+  const turnedOff = (spec.off ?? []).some((f) => rest.some((a) => a === f || a.startsWith(f + "="))) ||
+    (spec.offPairs ?? []).some(([flag, value]) => rest.some((a, i) => a === flag && rest[i + 1] === value));
   if (turnedOff) return null;
   const confining = spec.on || (spec.onWith ?? []).some((f) => rest.includes(f));
   if (!confining) return null;
@@ -81,6 +90,6 @@ export function nestedSandboxWarning(cmd = []) {
     `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]}\`.`
+    `  Run it with its own sandbox off: \`${name} … ${spec.offPairs ? spec.offPairs[0].join(" ") : (spec.off ?? ["--no-sandbox"])[0]}\`.`
   );
 }

package/src/notify.js

@@ -23,8 +23,10 @@
  *     which every role can read.
  */
 import { readFileSync } from "node:fs";
-import { basename, join } from "node:path";
-import { keyOf, pending, requestsPath, grantFor, shellId } from "./requests.js";
+import { basename, join, resolve, sep } from "node:path";
+import { keyOf, pending, requestsPath, grantFor, shellId, queueOf, withHandoffs } from "./requests.js";
+import { describeHandoff } from "./handoff.js";
+import { realAncestor } from "./paths.js";
 
 const FORMATS = ["text", "json", "slack"];
 const ENV_URL = "SEISIN_NOTIFY_URL";
@@ -41,9 +43,19 @@ function notifyUrl(config, env = process.env) {
   }
 }
 
-/** The body for one request, in the chosen format. */
+/**
+ * The body for one request, in the chosen format.
+ *
+ * Whose it is and where it goes are the queue's decision (handoff.js), the
+ * same one `seisin requests` prints; a request handed in without one is
+ * decided here by the same function, never described from its stored owners.
+ */
 export function message(config, req, number, format = "text") {
-  const owner = req.owners?.length ? `It belongs to ${req.owners.join(", ")}.` : "Nobody owns it.";
+  const d = req.handoff ?? withHandoffs(config, [{ ...req, key: keyOf(req) }])[0].handoff;
+  const owners = d.owners ?? [];
+  const where = describeHandoff(d, req.attempt);
+  const owner = (owners.length ? `It belongs to ${owners.join(", ")}.` : "Nobody owns it.") +
+    (where ? ` ${where[0].toUpperCase()}${where.slice(1)}.` : "");
   const 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))}`;
@@ -58,7 +70,7 @@ export function message(config, req, number, format = "text") {
       type: "application/json",
       body: JSON.stringify({
         text, repo: basename(config.root), number, id: keyOf(req), role: req.role, action: req.action,
-        target: req.target, owners: req.owners ?? [], grant: grantFor(req),
+        target: req.target, owners, grant: grantFor(req), handoff: d,
       }),
     };
   return { type: "text/plain; charset=utf-8", body: text };
@@ -86,10 +98,10 @@ export function notifier(config, { env = process.env, fetchImpl = globalThis.fet
     const key = keyOf(req);
     if (known.has(key)) return false;
     known.add(key);
-    const queue = pending(file);
+    const queue = queueOf(config);
     const number = queue.findIndex((p) => p.key === key) + 1;
     if (number < 1) return false;
-    const { type, body } = message(config, { ...req, owners: req.owners ?? queue[number - 1].owners }, number, format);
+    const { type, body } = message(config, queue[number - 1], number, format);
     inflight.push(
       fetchImpl(url, {
         method: "POST",
@@ -100,20 +112,37 @@ export function notifier(config, { env = process.env, fetchImpl = globalThis.fet
         signal: AbortSignal.timeout(timeoutMs),
       })
         .then((r) => { if (!r.ok) failures.push(`HTTP ${r.status}`); })
-        .catch((e) => failures.push(e.name === "TimeoutError" ? "timed out" : e.message)),
+        // Native fetch errors can embed the whole URL, including a webhook
+        // credential. Only report known categories, never the raw message.
+        .catch((e) => failures.push(notificationFailure(e))),
     );
     return true;
   }
 
   async function settle(capMs = timeoutMs + 500) {
     if (!inflight.length) return failures;
-    await Promise.race([Promise.allSettled(inflight), new Promise((ok) => setTimeout(ok, capMs))]);
+    let timer;
+    try {
+      await Promise.race([Promise.allSettled(inflight), new Promise((ok) => { timer = setTimeout(ok, capMs); })]);
+    } finally {
+      clearTimeout(timer);
+    }
     return failures;
   }
 
   return { enabled: !!url, maybe, settle };
 }
 
+function notificationFailure(error) {
+  if (error?.name === "TimeoutError") return "timed out";
+  if (error?.name === "AbortError") return "aborted";
+  const code = error?.cause?.code ?? error?.code;
+  if (code === "ERR_INVALID_URL") return "invalid URL";
+  if (code === "ENOTFOUND") return "host not found";
+  if (code === "ECONNREFUSED") return "connection unavailable";
+  return "request failed";
+}
+
 /**
  * `[notify]` from seisin.toml, refused rather than guessed when it would leak.
  * Called by the config loader.
@@ -132,16 +161,28 @@ export function readNotify(table, { path, root, keyDirs, roles, own }) {
   if (urlFile === undefined) return { urlFile: null, format };
   if (typeof urlFile !== "string" || !urlFile.trim() || urlFile.startsWith("/") || urlFile.split("/").includes(".."))
     throw new Error(`${path}: [notify] url_file must be a path inside the repo`);
-  const inKeyDir = keyDirs.some((d) => urlFile.startsWith(d.replace(/\/+$/, "") + "/"));
+  const canonical = (p) => realAncestor(resolve(root, p));
+  const file = canonical(urlFile);
+  const inKeyDir = keyDirs.some((d) => file.startsWith(canonical(d) + sep));
   if (!inKeyDir)
     throw new Error(
       `${path}: [notify] url_file "${urlFile}" is not inside a key directory, so every role can read ` +
       `it. Move it under ${keyDirs[0] ?? "a [keys] dir"}.`);
   // A file key is written bare (`netlify.txt`, meaning the first key directory)
   // or with its directory (`shared/api.txt`) — the same resolution settingsFor uses.
-  const resolve = (raw) => (raw.includes("/") ? raw : join(keyDirs[0] ?? "", raw));
+  const fileKey = (raw) => canonical(raw.includes("/") ? raw : join(keyDirs[0] ?? "", raw));
   const holders = Object.entries(roles)
-    .filter(([, r]) => r.keyEntries?.some((k) => k.kind === "file" && resolve(k.raw) === urlFile))
+    .filter(([, r]) => r.keyEntries?.some((k) => {
+      if (k.kind === "file") {
+        const held = fileKey(k.raw);
+        return file === held || file.startsWith(held + sep);
+      }
+      if (k.kind !== "ref" || k.scheme !== "file") return false;
+      // Match the builtin resolver's last-fragment rule. A reference delivers
+      // the contents even though it opens no filesystem read for the role.
+      const hash = k.ref.lastIndexOf("#");
+      return canonical(hash === -1 ? k.ref : k.ref.slice(0, hash)) === file;
+    }))
     .map(([n]) => n);
   if (holders.length)
     throw new Error(

package/src/owners.js

@@ -14,8 +14,10 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { protectedBy } from "./surface.js";
-import { entriesOf } from "./keys.js";
+import { entriesOf, parseKey, BUILTIN } from "./keys.js";
 import { WILD, fromCwd, toRepoRelative } from "./paths.js";
+import { AGENTS, AGENT_CREDENTIALS, CREDENTIAL_HOMES, expand } from "./grants.js";
+import { keptFor, shutByTerritory } from "./territory.js";
 
 /**
  * Does this glob cover this path? Supports `**`, `*`, `?` and a trailing `/`.
@@ -243,11 +245,55 @@ export function ownersOf(config, path) {
     if (!config.root || !path.startsWith(root)) return [];
     path = path.slice(root.length);
   }
+  // A private folder has one owner, whatever else covers it: every other role
+  // is given a denyWrite on it (srt.js), and denyWrite wins over any territory.
+  const mine = privateOwner(config, path);
   return Object.values(config.roles)
     .filter((r) => r.writes.some((g) => covers(g, path)) && !neverWrites(r, path, config))
+    .filter((r) => !mine || r.name === mine.role)
     .map((r) => r.name);
 }
 
+/**
+ * The private folder that holds `path` — `{ role, entry }` — or null.
+ *
+ * `path` is repo-relative, or absolute inside the repo. One answer for the
+ * settings, `explain`, the hook and `check`, so the denies the kernel is given
+ * and the sentence about them cannot drift apart.
+ */
+export function privateOwner(config, path) {
+  let p = String(path ?? "");
+  if (p.startsWith("/")) {
+    const root = config.root?.endsWith("/") ? config.root : `${config.root}/`;
+    if (!config.root || !p.startsWith(root)) return null;
+    p = p.slice(root.length);
+  }
+  for (const r of Object.values(config.roles ?? {}))
+    for (const entry of r.private ?? [])
+      if (covers(entry.replace(/\/\*\*$/, "").replace(/\/+$/, ""), p)) return { role: r.name, entry };
+  return null;
+}
+
+/** The answer for `role` touching another role's private folder, or null. */
+function privateAnswer(config, role, target, read = false) {
+  const hit = privateOwner(config, target);
+  if (!hit) return null;
+  // The owner's write goes on through the ordinary questions (never_writes
+  // still subtracts inside it); its read is answered here, because "every
+  // role reads it" is exactly what is no longer true.
+  if (hit.role === role)
+    return read
+      ? { allowed: true, owners: [role], privateTo: role,
+          reason: `${target} is in ${role}'s private folder (private = ["${hit.entry}"]): ${role} reads it, and no other role does` }
+      : null;
+  return {
+    allowed: false, owners: [hit.role], privateTo: hit.role,
+    reason: `${target} is in ${hit.role}'s private folder (private = ["${hit.entry}"]): only ${hit.role} ` +
+      `reads or writes it, and every other role is denied both, in any read mode. ` +
+      `There is nothing to grant — ask ${hit.role} for what you need from it`,
+  };
+}
+
 /**
  * Where a refused target stands against the policy as it is now.
  *
@@ -271,6 +317,8 @@ export function standing(config, entry) {
   const target = entry.target;
   if (entry.kind === "network")
     return { kind: "outside", owners: [], why: "a port or a socket, which no role owns" };
+  if (entry.kind === "system")
+    return { kind: "outside", owners: [], why: "a system service, which no role owns" };
   if (entry.kind === "key")
     return { kind: "outside", owners: [], why: "a key directory, closed on purpose" };
   const guard = protectedBy(config, target);
@@ -401,10 +449,30 @@ export function keyName(config, target) {
  * inside a key directory is a key question; anything else is answered as the
  * open read it is, with how to make it a key.
  */
+/**
+ * An agent's sign-in file: closed to every run but a run of that agent, which
+ * is a fact about the command and not the role (AGENT_CREDENTIALS, grants.js).
+ * explain has no command, so it answers for the ordinary case and names the
+ * exception. Nothing to grant either way, and the sentence says so: the advice
+ * it replaced was "add it to a role's keys", which would hand a ChatGPT token
+ * to a role by policy.
+ */
+function signInAnswer(role, target) {
+  if (!String(target ?? "").startsWith("/")) return null;
+  const agent = AGENTS.find((a) => AGENT_CREDENTIALS[a].map(expand).includes(target));
+  if (!agent) return null;
+  return {
+    allowed: false, owners: [], signIn: agent,
+    reason: `${target} is ${agent}'s sign-in: only a run whose command is ${agent} reads it ` +
+      `(seisin run ${role} -- ${agent} …), and the commands that run inside it. ` +
+      `Any other command run as ${role} is denied it, and there is nothing to grant`,
+  };
+}
+
 export function explainFileRead(config, role, rel, credentialHomes = []) {
   // Only a key directory makes a key: settingsFor refuses a key declared
   // anywhere else, so nothing outside one is denied by being a key.
-  if (inKeyDir(config, rel)) return explain(config, role, "read", rel);
+  if (inKeyDir(config, rel)) return explainPolicy(config, role, "read", rel);
   const level = config.isolate === true ? "home" : config.isolate;
   if ((level === "credentials" || level === "home") && rel.startsWith("/")) {
     const hit = credentialHomes.find((h) => rel === h || rel.startsWith(h + "/"));
@@ -414,6 +482,17 @@ export function explainFileRead(config, role, rel, credentialHomes = []) {
         reason: `${rel} is under ${hit}, which isolate = "${level}" closes to every role`,
       };
   }
+  const signIn = signInAnswer(role, rel);
+  if (signIn) return signIn;
+  const shut = privateAnswer(config, role, rel, true);
+  if (shut) return shut;
+  if (config.read === "territory" && rel.startsWith("/") &&
+      shutByTerritory(rel, keptFor(config, config.roles[role])))
+    return {
+      allowed: false, owners: [], readTerritory: true,
+      reason: `${rel} is outside what ${role} keeps readable under read = "territory". ` +
+        `Declare it in reads, or declare the tool that needs it in toolchain`,
+    };
   const dirs = (config.keyDirs ?? []).map(dirSpelling);
   return {
     allowed: true, owners: [], open: true,
@@ -433,6 +512,10 @@ export function explainFileRead(config, role, rel, credentialHomes = []) {
  * where you stand, and inside a key directory it is a key question again.
  */
 export function readTarget(config, target, cwd = process.cwd()) {
+  // A reference is a key by its spelling, never a path: resolving
+  // `keychain://x` from where you stand printed `keychain:/x` and answered
+  // a question about a file nobody asked about.
+  if (refOf(target)) return { key: true, target };
   if (!target.includes("/") && !isAbsolute(target)) {
     const declared = keyHolders(config, target).length > 0;
     const bare = (s) => s.replace(/\.[^.]+$/, "");
@@ -487,6 +570,64 @@ export function keyHolders(config, key) {
     .map((r) => r.name);
 }
 
+/** `scheme://…`, optionally `NAME=scheme://…`, read as a key entry — or null. */
+function refOf(target) {
+  try {
+    const e = parseKey(target);
+    return e.kind === "ref" ? e : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A reference key is a question about the policy, not about the disk.
+ *
+ * Two facts answer it: whether the role lists the reference in its `keys`,
+ * and which provider turns it into a value. The role never reads where the
+ * secret lives — the parent resolves it before the sandbox starts and hands
+ * over the value — so there is no path to normalise and no key directory to
+ * be inside of. Matched on scheme and reference; the variable name in front is
+ * how it is delivered, not which secret it is.
+ */
+function explainRef(config, role, ref) {
+  const spelled = `${ref.scheme}://${ref.ref}`;
+  const declaring = (r) => {
+    try {
+      return entriesOf(r).find((e) => e.kind === "ref" && e.scheme === ref.scheme && e.ref === ref.ref);
+    } catch {
+      return undefined;
+    }
+  };
+  const holders = Object.values(config.roles).filter(declaring).map((r) => r.name);
+  const provider = BUILTIN.has(ref.scheme)
+    ? `seisin's built-in ${ref.scheme}:// provider`
+    : Object.hasOwn(config.keyProviders ?? {}, ref.scheme) ? `[keys.providers.${ref.scheme}]` : null;
+  if (!provider)
+    return {
+      allowed: false, owners: holders, key: "ref",
+      reason: `${spelled} uses the "${ref.scheme}" scheme and no [keys.providers.${ref.scheme}] is declared, ` +
+        `so nothing resolves it — declare the provider before a role can hold this key`,
+    };
+  const mine = config.roles[role] && declaring(config.roles[role]);
+  if (mine)
+    return {
+      allowed: true, owners: holders, key: "ref", provider,
+      reason: `${role} declares ${mine.raw}: the parent resolves it through ${provider} and hands ` +
+        `${role} the value as ${mine.name} — the role never reads where it is kept`,
+    };
+  if (!holders.length)
+    return {
+      allowed: false, owners: [], key: "ref", provider,
+      reason: `no role declares ${spelled} (${provider} would resolve it) — ` +
+        `add it to a role's keys: [roles.${role}] keys = ["${ref.raw}"]`,
+    };
+  return {
+    allowed: false, owners: holders, key: "ref", provider,
+    reason: `${spelled} belongs to ${holders.join(", ")}, through ${provider}`,
+  };
+}
+
 /** The keys of `role` that grant a read: the path ones. A malformed entry grants nothing. */
 function fileKeys(role) {
   let entries;
@@ -568,10 +709,14 @@ function explainMcp(config, role, name) {
  * not a permission problem, it is a hole in the map. Saying so is more useful
  * than denying quietly, and it is the only way the hole ever gets fixed.
  */
-export function explain(config, role, action, target) {
+function explainPolicy(config, role, action, target) {
   if (action === "connect") return explainConnect(config, role, target);
   if (action === "mcp") return explainMcp(config, role, target);
   if (action === "read") {
+    const ref = refOf(target);
+    if (ref) return explainRef(config, role, ref);
+    const signIn = signInAnswer(role, target);
+    if (signIn) return signIn;
     const holders = keyHolders(config, target);
     if (holders.includes(role)) return { allowed: true, owners: holders, reason: `${role} declares ${target}` };
     if (holders.length === 0) {
@@ -617,6 +762,8 @@ export function explain(config, role, action, target) {
    * approves it, and the subtraction is undone from the other side without
    * anyone deciding to undo it.
    */
+  const shut = privateAnswer(config, role, target);
+  if (shut) return shut;
   const r = config.roles[role];
   const barred = r && r.writes.some((g) => covers(g, target)) ? neverWrites(r, target, config) : null;
   if (barred)
@@ -648,3 +795,18 @@ export function explain(config, role, action, target) {
     return { allowed: false, owners: [], reason: `${target} has no owner — no role can write it until one claims it` };
   return { allowed: false, owners, reason: `${target} belongs to ${owners.join(", ")}` };
 }
+
+/**
+ * One public answer for CLI, MCP and library callers.
+ *
+ * Reads first decide whether the target is a declared key or a file, then ask
+ * the same territory/isolation question. Callers may supply their cwd; servers
+ * use the policy root, while the CLI uses the directory it is standing in.
+ */
+export function explain(config, role, action, target, cwd = config.root) {
+  if (action !== "read") return explainPolicy(config, role, action, target);
+  const asked = readTarget(config, target, cwd);
+  return asked.key
+    ? explainPolicy(config, role, "read", asked.target)
+    : explainFileRead(config, role, asked.target, CREDENTIAL_HOMES.map(expand));
+}

package/src/paths.js

@@ -12,7 +12,7 @@
  * project refuses. Found by the read-only review of 2026-09-22.
  */
 import { realpathSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
 
 /**
  * `p` with its deepest existing ancestor resolved through symlinks and the rest
@@ -57,6 +57,22 @@ export function toRepoRelative(config, target) {
   return target;
 }
 
+/**
+ * One spelling for a path, so two of them can be compared with `===`.
+ *
+ * Repo-relative and normalized inside the repo (`./a/`, `a/../a` and the
+ * absolute path through either symlinked spelling of the root are all `a`);
+ * absolute and resolved through its existing ancestors outside it. Used where
+ * a path a caller gave must match the path a denial names exactly — never as
+ * a prefix and never as a glob.
+ */
+export function samePath(config, target) {
+  if (typeof target !== "string" || !target.trim()) return null;
+  const rel = toRepoRelative(config, isAbsolute(target) ? normalize(target) : target);
+  if (isAbsolute(rel)) return realAncestor(normalize(rel)).replace(/(.)\/+$/, "$1");
+  return normalize(rel).replace(/\/+$/, "") || ".";
+}
+
 /**
  * A path typed at a prompt, made absolute the way a shell user means it:
  * against the directory they are standing in. Relative arguments used to be

package/src/provider-run.js

@@ -0,0 +1,81 @@
+/**
+ * Runs one key provider and reports what it printed, as JSON on stdout.
+ *
+ * A separate process because `spawnSync` cannot do two things a provider
+ * needs, and `resolveRef` is synchronous by contract (keys.js):
+ *
+ *   - **Take the answer when the provider exits.** `spawnSync` returns when
+ *     the child has exited AND every copy of its stdout is closed. A provider
+ *     that printed the value, exited 0 and left a background process holding
+ *     the pipe made seisin wait the whole timeout and then say the provider
+ *     "did not answer". Here the answer is what was read by the time the
+ *     provider exited, plus a short drain for bytes still in the pipe.
+ *   - **Stop it for good.** A timeout is SIGKILL, not SIGTERM: a provider that
+ *     ignored SIGTERM held the run forever. And it goes to every descendant
+ *     too, so a child the provider was waiting on dies with it instead of
+ *     living on. Found by walking `ps`, not by a process group of its own: a
+ *     new session would take the provider's terminal away, and a pinentry
+ *     needs it. A provider that exits on its own keeps whatever it left
+ *     running: an agent it starts (gpg-agent, an op daemon) is its business.
+ *
+ * stderr is read and counted, never kept: a provider may print the value
+ * there, and nothing downstream shows it.
+ *
+ * argv: <timeoutMs> <maxBytes> <drainMs> <command> [args…]
+ */
+import { spawn, execFileSync } from "node:child_process";
+
+const [timeoutMs, maxBytes, drainMs] = process.argv.slice(2, 5).map(Number);
+const argv = process.argv.slice(5);
+
+const chunks = [];
+let size = 0, errBytes = 0, timedOut = false, tooBig = false, done = false;
+
+function finish(result) {
+  if (done) return;
+  done = true;
+  clearTimeout(timer);
+  const out = tooBig ? "" : Buffer.concat(chunks).toString("base64");
+  process.stdout.write(JSON.stringify({ ...result, out, errBytes, timedOut, tooBig }), () => process.exit(0));
+}
+
+/** The provider and every process below it. */
+function tree(root) {
+  const kids = new Map();
+  try {
+    for (const line of execFileSync("ps", ["-A", "-o", "pid=,ppid="], { encoding: "utf8" }).split("\n")) {
+      const [pid, ppid] = line.trim().split(/\s+/).map(Number);
+      if (pid && ppid) kids.set(ppid, [...(kids.get(ppid) ?? []), pid]);
+    }
+  } catch {}
+  const all = [root];
+  for (let i = 0; i < all.length; i++) all.push(...(kids.get(all[i]) ?? []));
+  return all;
+}
+
+const child = spawn(argv[0], argv.slice(1), { stdio: ["ignore", "pipe", "pipe"] });
+const kill = () => {
+  if (!child.pid) return;
+  // Stopped first, so nothing forks between the listing and the kill.
+  const pids = tree(child.pid);
+  for (const pid of pids) try { process.kill(pid, "SIGSTOP"); } catch {}
+  for (const pid of tree(child.pid)) if (!pids.includes(pid)) pids.push(pid);
+  for (const pid of pids) try { process.kill(pid, "SIGKILL"); } catch {}
+};
+const timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+
+child.stdout.on("data", (c) => {
+  size += c.length;
+  if (size > maxBytes) { tooBig = true; chunks.length = 0; kill(); return; }
+  if (!tooBig) chunks.push(c);
+});
+child.stderr.on("data", (c) => { errBytes += c.length; });
+child.on("error", (e) => finish({ error: e.code ?? e.message }));
+child.on("exit", (status, signal) => {
+  // What the provider wrote before exiting may still be in the pipe. Wait for
+  // the end of it, but not for a descendant that kept the pipe open.
+  const drained = () => finish({ status, signal });
+  if (child.stdout.readableEnded) return drained();
+  child.stdout.once("end", drained);
+  setTimeout(drained, drainMs).unref();
+});