seisin 0.4.2 → 0.5.0

package/src/owners.js

@@ -11,9 +11,11 @@
  * exception, and they are handled separately below.
  */
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { protectedBy } from "./surface.js";
+import { entriesOf } from "./keys.js";
+import { WILD, fromCwd, toRepoRelative } from "./paths.js";
 
 /**
  * Does this glob cover this path? Supports `**`, `*`, `?` and a trailing `/`.
@@ -43,9 +45,23 @@ import { protectedBy } from "./surface.js";
 export function covers(glob, path) {
   const p = normalized(path);
   const m = matcherOf(glob);
+  /**
+   * Above the root only for a glob that climbs there itself.
+   *
+   * `../../etc/passwd` is a path the kernel refuses to every role, and `**`
+   * matched it as a string, so `explain` answered "inside territory" for it.
+   * A territory reaches outside the repo only by saying so — the
+   * `../shared/lab/dev.md` a role writes beside its own directory — and
+   * that one still matches, because both sides start with the same `..`.
+   */
+  if (climbs(p) && !m.climbs) return false;
   // The path itself, or anything beneath it. The `/` is load-bearing: without
   // it `src/api` would also cover `src/apifoo.ts`, which the kernel does not.
   if (m.prefix !== null) return p === m.prefix || p.startsWith(m.prefix + "/");
+  // The literal head of the glob, before its first wildcard, has to be the
+  // head of the path too. Most pairs fail here, for the price of a
+  // startsWith — `check` asks ~400k of them on a real policy.
+  if (!p.startsWith(m.head)) return false;
   return matchGlob(m.glob, p);
 }
 
@@ -69,7 +85,8 @@ function matcherOf(glob) {
   if (m) return m;
   let g = normalize(glob);
   if (glob.endsWith("/")) g += "/**";
-  m = WILD.test(g) ? { prefix: null, glob: g } : { prefix: g, glob: null };
+  const wild = WILD.test(g);
+  m = { prefix: wild ? null : g, glob: wild ? g : null, climbs: climbs(g), head: wild ? headOf(g) : "" };
   if (GLOBS.size >= MAX_CACHED) GLOBS.clear();
   GLOBS.set(glob, m);
   return m;
@@ -84,8 +101,15 @@ function normalized(path) {
   return p;
 }
 
-/** The four characters toRegExp() treats as wildcards. */
-const WILD = /[*?[\]]/;
+/**
+ * What every path a glob matches starts with: its text up to the first
+ * wildcard, minus a final `/` — `src/api/**` matches `src/api` itself, and
+ * `a/**\/b` matches `a/b`.
+ */
+const headOf = (g) => g.slice(0, g.search(WILD)).replace(/\/$/, "");
+
+/** Does a normalised path start above the repo root? */
+const climbs = (p) => p === ".." || p.startsWith("../");
 
 /**
  * One spelling per file, before anybody decides anything about it.
@@ -97,8 +121,10 @@ const WILD = /[*?[\]]/;
  * every sentence seisin said about it was wrong, which is the half of the tool
  * that is actually ours.
  *
- * A path that climbs above the repo root comes back as `..`, which owns
- * nothing and matches nothing. Outside the repo has no owner by definition.
+ * A path that climbs above the repo root keeps its leading `..` segments
+ * (`src/../../x` is `../x`). `covers` matches such a path only against a glob
+ * that climbs out too, so outside the repo has no owner unless a territory
+ * names that place explicitly.
  */
 export function normalize(s) {
   const flat = s.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/\/+$/, "");
@@ -111,22 +137,9 @@ export function normalize(s) {
   return up.join("/");
 }
 
-/**
- * Glob to RegExp.
- *
- * The wildcards are parked on sentinels before `*` is expanded, because
- * expanding `**` first produces a `.*` whose own `*` the next pass would
- * rewrite again. Getting that order wrong is silent: the regex still compiles
- * and quietly matches the wrong set of files.
- *
- * `src/api/**` also matches `src/api` itself. Without that, the directory a
- * role was just granted comes back ownerless, which reads as a bug every time.
- *
- * Dotfiles are matched like any other name: `*.env` covers `.env`. Shell globs
- * hide them by default, and most glob libraries copy that. A permission tool
- * must not: covering one file too many costs an argument, covering one too few
- * is the hole. When the two readings disagree, this one takes the wider set.
- */
+/** matchGlob's memo, shared between calls (see there). */
+let MEMO = new Uint8Array(4096);
+
 /**
  * Does `glob` cover `path`? A linear matcher, not a regular expression.
  *
@@ -141,11 +154,31 @@ export function normalize(s) {
  * Same wildcards as before: `?` one non-`/`, `*` a run of non-`/`, `**` any run
  * including `/`, `**\/` zero or more whole directories, a trailing `/**` the
  * subtree. Characters are compared literally; nothing is treated as regex.
+ *
+ * `src/api/**` also matches `src/api` itself. Without that, the directory a
+ * role was just granted comes back ownerless, which reads as a bug every time.
+ *
+ * Dotfiles are matched like any other name: `*.env` covers `.env`. Shell globs
+ * hide them by default, and most glob libraries copy that. A permission tool
+ * must not: covering one file too many costs an argument, covering one too few
+ * is the hole. When the two readings disagree, this one takes the wider set.
  */
 function matchGlob(glob, path) {
   const G = glob.length, P = path.length;
-  // memo[gi * (P+1) + pi]: 0 unknown, 1 true, 2 false. One flat array, reused.
-  const memo = new Uint8Array((G + 1) * (P + 1));
+  // memo[gi * (P+1) + pi]: 0 unknown, 1 true, 2 false. One flat array, kept
+  // between calls and cleared over the part this call uses: allocating it
+  // fresh was most of the cost of a call that fails on its second character.
+  // Nothing re-enters matchGlob while it runs, so sharing it is safe.
+  // An outsized pair gets its own array, so one long path does not pin
+  // megabytes for the life of a server.
+  const size = (G + 1) * (P + 1);
+  let memo;
+  if (size > 1 << 20) memo = new Uint8Array(size);
+  else {
+    if (MEMO.length < size) MEMO = new Uint8Array(Math.max(size, MEMO.length * 2));
+    memo = MEMO;
+    memo.fill(0, 0, size);
+  }
   const at = (gi, pi) => {
     for (;;) {
       const key = gi * (P + 1) + pi;
@@ -241,6 +274,12 @@ export function standing(config, entry) {
   if (entry.kind === "key")
     return { kind: "outside", owners: [], why: "a key directory, closed on purpose" };
   const guard = protectedBy(config, target);
+  // A family the policy hands to a role is protected from everybody else and
+  // owned by that role — if it is also that role's territory.
+  if (guard?.family) {
+    const holders = ownersOf(config, target).filter((o) => config.roles[o]?.controlFiles?.includes(guard.family));
+    if (holders.length) return { kind: "owned", owners: holders };
+  }
   if (guard) return { kind: "protected", owners: [], why: guard.why };
   if (target.startsWith("/")) {
     const root = config.root?.endsWith("/") ? config.root : `${config.root}/`;
@@ -323,6 +362,92 @@ export function neverWrites(role, path, config = null) {
   return enforcedNeverWrites(config, role).find((g) => covers(g, path)) ?? null;
 }
 
+/** A key dir as the policy's paths spell it: no leading `./`, no trailing `/`. */
+const dirSpelling = (d) => String(d).replace(/^\.\/+/, "").replace(/\/+$/, "");
+
+/** Is the repo-relative `rel` one of the key directories, or inside one? */
+export function inKeyDir(config, rel) {
+  return (config.keyDirs ?? []).some((d) => {
+    const k = dirSpelling(d);
+    const r = k.startsWith("/") ? relFromRoot(config, k) : k;
+    return r !== null && (rel === r || rel.startsWith(r + "/"));
+  });
+}
+
+function relFromRoot(config, abs) {
+  const root = config.root ?? "";
+  return abs === root ? "." : abs.startsWith(root + "/") ? abs.slice(root.length + 1) : null;
+}
+
+/**
+ * How a key is written in a role's `keys` list: relative to the first key
+ * directory when it lives there, with its directory otherwise — the same form
+ * settingsFor and keyHolders resolve back.
+ */
+export function keyName(config, target) {
+  const t = String(target ?? "");
+  const first = config.keyDirs?.length ? dirSpelling(config.keyDirs[0]) : null;
+  return first && t.startsWith(first + "/") ? t.slice(first.length + 1) : t;
+}
+
+/**
+ * A read of a FILE — a path, not a key name — and whether the role gets it.
+ *
+ * Reads are open by design: every role reads everything outside the `[keys]`
+ * dirs (and, under `isolate`, outside the credential homes). `explain` used to
+ * send every read through the key question, so `explain dev read .env` said
+ * "denied — no role declares .env" about a file every role could read. A wrong
+ * no from the tool whose job is saying what the kernel will do. Now a path
+ * 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.
+ */
+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);
+  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 + "/"));
+    if (hit)
+      return {
+        allowed: false, owners: [],
+        reason: `${rel} is under ${hit}, which isolate = "${level}" closes to every role`,
+      };
+  }
+  const dirs = (config.keyDirs ?? []).map(dirSpelling);
+  return {
+    allowed: true, owners: [], open: true,
+    reason: dirs.length
+      ? `${rel} is outside every [keys] dir (${dirs.join(", ")}), so every role reads it. ` +
+        `Move it into ${dirs[0]}/ to make it a key`
+      : `no [keys] dir is declared, so every role reads every file. ` +
+        `Declare one under [keys] and move ${rel} into it to make it a key`,
+  };
+}
+
+/**
+ * What a read is about: a key, named the way the policy names keys, or a file.
+ *
+ * `explain dev read stripe` asks about a key — a bare name some role declares,
+ * or one sitting in a key directory. Everything else is a path, resolved from
+ * where you stand, and inside a key directory it is a key question again.
+ */
+export function readTarget(config, target, cwd = process.cwd()) {
+  if (!target.includes("/") && !isAbsolute(target)) {
+    const declared = keyHolders(config, target).length > 0;
+    const bare = (s) => s.replace(/\.[^.]+$/, "");
+    const inDir = (config.keyDirs ?? []).some((d) => {
+      const dir = isAbsolute(d) ? d : join(config.root, d);
+      if (existsSync(join(dir, target))) return true;
+      try { return readdirSync(dir).some((f) => bare(f) === target); } catch { return false; }
+    });
+    const here = fromCwd(config, target, cwd);
+    const isFileHere = existsSync(here) && !inKeyDir(config, toRepoRelative(config, here));
+    if ((declared || inDir) && !isFileHere) return { key: true, target };
+  }
+  return { key: false, target: toRepoRelative(config, fromCwd(config, target, cwd)) };
+}
+
 /** Every role allowed to read `key`, matched with or without its extension. */
 export function keyHolders(config, key) {
   const dirs = config.keyDirs ?? [];
@@ -349,19 +474,30 @@ export function keyHolders(config, key) {
   // netlify` — so it stays, and only for an unqualified question.
   const loose = !key.includes("/");
 
+  /**
+   * Only path keys. A reference — `keychain://x`, `NAME=file://.secrets/a#X` —
+   * is resolved by the parent and delivered as a value; the role is never
+   * given the file. Comparing the raw strings let `explain` say "declares
+   * a.env" about a role whose key merely pointed into it, a yes the kernel
+   * would refuse.
+   */
   return Object.values(config.roles)
-    .filter((r) => r.keys.some((k) =>
+    .filter((r) => fileKeys(r).some((k) =>
       resolve(k) === wanted || (loose && bare(k) === bare(key))))
     .map((r) => r.name);
 }
 
-/**
- * The sentence a blocked agent should read.
- *
- * Three outcomes, and the third is the one worth having: a path nobody owns is
- * 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.
- */
+/** The keys of `role` that grant a read: the path ones. A malformed entry grants nothing. */
+function fileKeys(role) {
+  let entries;
+  try {
+    entries = entriesOf(role);
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.kind === "file").map((e) => e.raw);
+}
+
 /**
  * A connection the kernel refused: `tcp:<port>` or a unix socket path.
  *
@@ -425,14 +561,28 @@ function explainMcp(config, role, name) {
       : `${role} declares mcp = [], no MCP servers` };
 }
 
+/**
+ * The sentence a blocked agent should read.
+ *
+ * Three outcomes, and the third is the one worth having: a path nobody owns is
+ * 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) {
   if (action === "connect") return explainConnect(config, role, target);
   if (action === "mcp") return explainMcp(config, role, target);
   if (action === "read") {
     const holders = keyHolders(config, target);
     if (holders.includes(role)) return { allowed: true, owners: holders, reason: `${role} declares ${target}` };
-    if (holders.length === 0)
-      return { allowed: false, owners: [], reason: `no role declares ${target} — add it under a [roles.<name>] keys list` };
+    if (holders.length === 0) {
+      // A key is written as a name relative to the key directory — `stripe.txt`,
+      // not `.secrets/stripe.txt` — so the advice says the name to write.
+      const name = keyName(config, target);
+      return {
+        allowed: false, owners: [],
+        reason: `no role declares ${target} — add "${name}" to a role's keys: [roles.<name>] keys = ["${name}"]`,
+      };
+    }
     return { allowed: false, owners: holders, reason: `${target} belongs to ${holders.join(", ")}` };
   }
 
@@ -442,11 +592,18 @@ export function explain(config, role, action, target) {
    *
    * The policy, seisin's state, the key directories, what the parent executes
    * or reads for a key, and the files that make git or Claude Code run
-   * something outside the box. The kernel denies all of them to every role —
+   * something outside the sandbox. The kernel denies all of them to every role —
    * surface.js has the list and the reasons — so saying "belongs to dev" about
    * `seisin.toml` sent a request to a person that no grant could satisfy.
    */
-  const guard = protectedBy(config, target);
+  const guard = protectedBy(config, target, { role });
+  if (guard?.family)
+    return {
+      allowed: false, owners, protected: guard.why, family: guard.family,
+      reason: `${target} is protected (${guard.why}). A role writes it only when the policy hands it ` +
+        `that family: control_files = ["${guard.family}"] under [roles.${role}], and inside its own ` +
+        `territory. That is a person's decision about the policy, not a grant to request`,
+    };
   if (guard)
     return {
       allowed: false, owners, protected: guard.why,
@@ -466,7 +623,7 @@ export function explain(config, role, action, target) {
     return {
       allowed: false, owners, neverWrites: barred,
       reason: `${target} is denied by never_writes of ${role} ("${barred}") — ` +
-        `a subtraction written into the policy, not a missing permission`,
+        `a subtraction written into the policy, not a missing grant`,
     };
   if (owners.includes(role)) return { allowed: true, owners, reason: `${target} is inside ${role}'s territory` };
   /**
@@ -477,14 +634,14 @@ export function explain(config, role, action, target) {
    * else's history. Codex keeps `.git` read-only under a writable root for the
    * same reason; nono and Gemini grant the whole of it. Here it stays refused
    * and is said for what it is — not "belongs to X, ask them", which filed a
-   * request per lock file (327 of them for one index.lock on one portfolio)
-   * that nobody could sensibly approve. The requests side skips it too.
+   * request per lock file (327 of them for one index.lock in one multi-repo workspace)
+   * that nobody could sensibly grant. The requests side skips it too.
    */
   if (isGitMetadata(target))
     return {
       allowed: false, owners, gitMetadata: true,
       reason: `${target} is git's own bookkeeping in a repository ${role} does not write — ` +
-        `not a permission to ask for. Read what you need (git log, git show, git ls-remote) ` +
+        `not something to request. Read what you need (git log, git show, git ls-remote) ` +
         `or work in a worktree of your own`,
     };
   if (owners.length === 0)

package/src/paths.js

@@ -23,7 +23,8 @@ export function realAncestor(p) {
   let head = p, tail = "";
   while (head !== dirname(head)) {
     try {
-      const real = realpathSync(head);
+      // `.native`: the disk's own case on APFS — see realOrSelf in grants.js.
+      const real = realpathSync.native(head);
       return tail ? join(real, tail) : real;
     } catch {
       tail = tail ? join(basename(head), tail) : basename(head);
@@ -33,6 +34,13 @@ export function realAncestor(p) {
   return p;
 }
 
+/**
+ * The four characters the glob matcher treats as wildcards. Here, in a module
+ * that imports nothing of seisin's, so that owners.js and grants.js share one
+ * definition without importing each other.
+ */
+export const WILD = /[*?[\]]/;
+
 /**
  * Repo-relative when `target` is inside the repo, spelled either way; exactly as
  * written when it is relative already or lies outside. A path outside keeps its
@@ -48,3 +56,31 @@ export function toRepoRelative(config, target) {
   if (inside(realRoot, realTarget)) return relative(realRoot, realTarget) || ".";
   return target;
 }
+
+/**
+ * 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
+ * read against the policy's root, so `seisin explain web write app.js` from
+ * web/src asked about ./app.js at the root and answered "no owner".
+ *
+ * Only when the working directory is inside the repo. From anywhere else —
+ * `SEISIN_CONFIG` pointing at a policy elsewhere, a test harness — a relative
+ * path keeps meaning what it always meant: relative to the root.
+ */
+export function fromCwd(config, target, cwd = process.cwd()) {
+  if (typeof target !== "string" || isAbsolute(target)) return target;
+  const root = config.root;
+  const inside = (r, t) => t === r || t.startsWith(r + sep);
+  // The cwd and the root compared in the same spelling: as written, or both
+  // through their symlinks (on macOS /tmp is /private/tmp).
+  let base = root, here = cwd;
+  if (!inside(root, cwd)) {
+    base = realAncestor(root);
+    here = realAncestor(cwd);
+    if (!inside(base, here)) return target;
+  }
+  const rel = relative(base, join(here, target));
+  if (rel === "") return root;
+  if (rel === ".." || rel.startsWith(".." + sep)) return join(here, target);
+  return join(root, rel);
+}

package/src/redact.js

@@ -20,6 +20,7 @@
  * README spends its time avoiding.
  */
 import { Transform } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
 
 /** Reads the values this role may read. Unreadable or huge files are skipped. */
 export function secretsOf(settings, readFile) {
@@ -49,10 +50,18 @@ export function secretsOf(settings, readFile) {
  * It carries the tail of each chunk forward, because a value split across a
  * buffer boundary would otherwise sail through — which is the one case a
  * naive implementation always gets wrong and never notices.
+ *
+ * Bytes are decoded with a StringDecoder that lives as long as the stream. A
+ * chunk boundary falls wherever the pipe put it, including inside a multibyte
+ * character: decoding each chunk on its own turned `año` into `a��o`, and a
+ * secret with an `ñ` in it split that way was never seen whole, so it was
+ * never masked. The same care applies to the cut below, which must not leave
+ * half of a surrogate pair on either side.
  */
 export function redactor(secrets, label = "redacted") {
   if (secrets.length === 0) return null;
   const longest = secrets[0].length;
+  const decoder = new StringDecoder("utf8");
   let tail = "";
 
   return new Transform({
@@ -61,20 +70,25 @@ export function redactor(secrets, label = "redacted") {
       // — masking only the part about to be emitted — lets a secret that
       // straddles the cut through in two innocent halves. Written that way
       // first; the split-buffer test caught it on the first run.
-      const masked = mask(tail + chunk.toString("utf8"), secrets, label);
-      const keep = Math.min(longest - 1, masked.length);
-      this.push(masked.slice(0, masked.length - keep));
-      tail = masked.slice(masked.length - keep);
+      const text = typeof chunk === "string" ? chunk : decoder.write(chunk);
+      const masked = mask(tail + text, secrets, label);
+      let cut = masked.length - Math.min(longest - 1, masked.length);
+      if (cut > 0 && isHighSurrogate(masked.charCodeAt(cut - 1))) cut--;
+      if (cut > 0) this.push(masked.slice(0, cut));
+      tail = masked.slice(cut);
       done();
     },
     flush(done) {
-      this.push(mask(tail, secrets, label));
+      const rest = mask(tail + decoder.end(), secrets, label);
+      if (rest) this.push(rest);
       tail = "";
       done();
     },
   });
 }
 
+const isHighSurrogate = (c) => c >= 0xd800 && c <= 0xdbff;
+
 function mask(text, secrets, label) {
   let out = text;
   for (const s of secrets) out = out.split(s).join(`‹${label}›`);

package/src/render.js

@@ -67,8 +67,16 @@ export function collapseSidecars(paths) {
   return out;
 }
 
-/** The `check` report, as text. Takes the object `inspect()` returns. */
-export function renderReport(report) {
+/**
+ * The `check` report, as text. Takes the object `inspect()` returns.
+ *
+ * The map and one line per warning first; the paragraphs behind `verbose`.
+ * On a three-role repo the full report ran to forty lines of explanation under
+ * a six-line map, and the one warning a person could act on sat in the middle.
+ * Nothing is dropped: the protected paths, each warning's reason and the
+ * standing limits are one flag away, and the footer says how many.
+ */
+export function renderReport(report, { verbose = true } = {}) {
   const lines = [`\n${C.b}${report.where}${C.off}\n\n`];
   const width = Math.max(...report.roles.map((r) => r.name.length), 4);
 
@@ -101,10 +109,10 @@ export function renderReport(report) {
   // What the kernel refuses inside a territory, and why. Shown because each one
   // takes something from a territory as written; capped because a monorepo has
   // a hooks directory per package and the reader needs the shape, not all 200.
-  if (report.protected?.length) {
+  if (report.protected?.length && verbose) {
     const root = report.where ? report.where.replace(/\/[^/]*$/, "/") : "";
     const show = (p) => (root && p.startsWith(root) ? p.slice(root.length) : p.replace(/^\/Users\/[^/]+|^\/home\/[^/]+/, "~"));
-    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, refused anyway: something outside the box runs or reads it${C.off}\n`);
+    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, denied anyway: something outside the sandbox runs or reads it${C.off}\n`);
     const LIMIT = 12;
     for (const e of report.protected.slice(0, LIMIT)) {
       const who = e.roles.length > 3 ? `${e.roles.slice(0, 3).join(", ")} +${e.roles.length - 3}` : e.roles.join(", ");
@@ -115,6 +123,18 @@ export function renderReport(report) {
     lines.push("\n");
   }
 
+  if (!verbose) {
+    for (const w of report.warnings) lines.push(`  ${C.yellow}${w.headline}${C.off}\n`);
+    if (report.warnings.length) lines.push("\n");
+    const more = [
+      report.protected?.length ? `${report.protected.length} protected path(s)` : "",
+      report.warnings.some((w) => w.detail) ? "why each warning matters" : "",
+      report.limits?.length ? `${report.limits.length} standing limit(s)` : "",
+    ].filter(Boolean);
+    if (more.length) lines.push(`  ${C.dim}seisin check --verbose: ${more.join(", ")}${C.off}\n\n`);
+    return lines.join("");
+  }
+
   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`);
@@ -177,16 +197,40 @@ 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`];
+  const lines = [`\n  ${C.dim}protected: ${where}${C.off}\n`];
+  // Scoped to the territories: say where it looked, and how to look everywhere.
+  if (result.scope) {
+    const shown = result.scope.slice(0, 10).map(safe).join(", ");
+    const more = result.scope.length > 10 ? ` and ${result.scope.length - 10} more` : "";
+    lines.push(`  ${C.dim}scanned: where the territories are — ${shown}${more}. ${C.b}seisin scan --all${C.off}${C.dim} walks the whole folder${C.off}\n`);
+  }
+  lines.push("\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`);
+  // A pruned checkout is part of what a clean result means, so it is said
+  // even when there is nothing else to say — in yellow, not dim: every role
+  // can still read it, and a dim line under a green verdict read as clean.
+  const paths = result.nestedPaths ?? [];
+  let nested = "";
+  if (skipped.nested) {
+    nested = `  ${C.yellow}not scanned: ${skipped.nested} nested checkout(s)${C.off} — another repository each; every role can still read them. Scan one with ${C.b}cd <dir> && seisin scan${C.off}\n`;
+    for (const p of paths.slice(0, 15)) nested += `    ${safe(p)}\n`;
+    if (paths.length > 15) nested += `    ${C.dim}… and ${paths.length - 15} more${C.off}\n`;
+    nested += "\n";
+  }
+  const named = result.named ?? [];
+  if (certain.length === 0 && review.length === 0 && links.length === 0 && named.length === 0) {
+    lines.push(skipped.nested
+      ? `  nothing credential-shaped in what was scanned ${C.dim}(outside the declared directories)${C.off}\n\n`
+      : `  ${C.green}nothing credential-shaped outside the declared directories${C.off}\n\n`, nested);
     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(`  ${C.red}${certain.length} credential(s)${C.off} — issued shapes, or a password in a URL: a credential, not a word that mentions one\n\n`);
+    for (const h of certain) {
+      const whose = h.owners?.length ? `  ${C.dim}in ${h.owners.map(safe).join(", ")}'s territory${C.off}` : "";
+      lines.push(`    ${C.b}${safe(h.file)}${C.off}${C.dim}:${h.line}${C.off}  ${h.shape}${whose}\n`);
+    }
     lines.push("\n");
   }
 
@@ -200,6 +244,18 @@ export function renderScan(result, keyDirs) {
     lines.push("\n");
   }
 
+  // By name, not by content, and said that way: a .env of DEBUG=1 is on this
+  // list too. What it is for is the .env nobody declared.
+  if (named.length) {
+    lines.push(`  ${C.yellow}${named.length} file(s) that usually hold secrets${C.off} — by their name, not certain; every role reads them\n\n`);
+    for (const h of named.slice(0, 15)) {
+      const whose = h.owners?.length ? `  ${C.dim}in ${h.owners.map(safe).join(", ")}'s territory${C.off}` : "";
+      lines.push(`    ${C.b}${safe(h.file)}${C.off}${whose}\n`);
+    }
+    if (named.length > 15) lines.push(`    ${C.dim}… and ${named.length - 15} more${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.
@@ -217,7 +273,9 @@ export function renderScan(result, keyDirs) {
   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`);
+  // Only the ones to review are capped; a certain hit is always listed above.
+  if (truncated) lines.push(`  ${C.yellow}${result.omitted ?? "more"} more to review were not listed — the cap applies to review, never to certain hits${C.off}\n`);
+  if (nested) lines.push(nested);
   lines.push(`  ${C.dim}seisin does not move these. Where a credential lives is your call.${C.off}\n\n`);
   return lines.join("");
 }