seisin 0.4.2 → 0.6.0

package/src/inspect/layout.js

@@ -0,0 +1,258 @@
+import { resolve, dirname, basename, relative, join } from "node:path";
+import { existsSync } from "node:fs";
+import { territoryOf, implicitSidecar, under, regularFilesIn } from "./files.js";
+import { covers } from "../owners.js";
+
+export function layoutWarnings(config, roles, scoped) {
+  const warnings = [];
+  // A territory that leaves the repo is supported — a role can own its handover
+  // note one level up — but it is a different promise from "this repo, divided",
+  // and it should be a sentence somebody chose rather than a line that drifted.
+  const loose = [];      // roles granting individual files
+  const listed = [];     // role + folder pairs that enumerate
+
+  /**
+   * A private folder inside another role's territory. Allowed — it is how a
+   * folder is taken out of a wide `writes = ["**"]` — but that role loses it,
+   * reading included, and nothing in its own table says so.
+   */
+  for (const r of roles)
+    for (const p of r.private ?? []) {
+      const dir = p.replace(/\/\*\*$/, "").replace(/\/+$/, "").replace(/^\.\//, "");
+      for (const o of Object.values(config.roles)) {
+        if (o.name === r.name) continue;
+        const g = (o.writesDeclared ?? o.writes).find((w) => covers(w, dir));
+        if (g)
+          warnings.push({
+            kind: "private-inside-territory",
+            headline: `${r.name}: private "${p}" is inside ${o.name}'s writes ("${g}") — ${o.name} can neither read nor write it`,
+            detail: `Every role but ${r.name} is denied the folder, and the deny wins over ${o.name}'s territory. ` +
+              `If ${o.name} needs what is in it, it asks ${r.name}; if it should keep it, the folder is not private.`,
+          });
+      }
+    }
+
+  for (const r of roles) {
+    const out = r.writes.filter((w) => w.startsWith("/") || w.startsWith("../"));
+    if (out.length)
+      warnings.push({
+        kind: "territory-outside-repo",
+        headline: `${r.name} writes outside this repo: ${out.join(" ")}`,
+        detail: "the sandbox will grant it. Nothing here checks what lives there.",
+      });
+  }
+
+  /**
+   * A territory that is not on disk.
+   *
+   * A proposal written for another repo — or one typo — reads as a working
+   * policy: `check` printed the map and the first sign of anything wrong was a
+   * denial inside the agent. Said per glob, as a warning and never a failure:
+   * a role can own a folder it is about to create.
+   */
+  for (const r of roles) {
+    for (const g of r.writes) {
+      if (g === "**" || g.startsWith("/") || g.startsWith("../")) continue;
+      // A database's sidecars come with it (config.js) and exist only while it
+      // is open: absent on disk is their normal state, not a typo to report.
+      if (implicitSidecar(r, g)) continue;
+      const fixed = [];
+      for (const part of g.split("/")) {
+        if (/[*?[\]]/.test(part)) break;
+        fixed.push(part);
+      }
+      if (!fixed.length || existsSync(join(config.root, ...fixed))) continue;
+      warnings.push({
+        kind: "writes-match-nothing",
+        headline: `${r.name} writes ${g} — matches nothing in this repo`,
+        detail: "fine if the role is about to create it; otherwise the territory points at a folder that is not there.",
+      });
+    }
+  }
+
+  /**
+   * A territory inside a key directory.
+   *
+   * Seen in use: a role's whole territory sat under the folder declared as
+   * `[keys] dir`, which is closed to every role, so the role could write
+   * nothing at all — and `check` printed its territory as if it held. A key
+   * directory is read by the roles that declare a key in it and written by
+   * none; a folder a role must write belongs somewhere else.
+   */
+  const keyRoots = (config.keyDirs ?? []).map((d) => d.replace(/\/+$/, "")).filter(Boolean);
+  for (const r of roles) {
+    for (const g of r.writes) {
+      const fixed = [];
+      for (const part of g.split("/")) {
+        if (/[*?[\]]/.test(part)) break;
+        fixed.push(part);
+      }
+      const at = fixed.join("/");
+      const dir = at && keyRoots.find((d) => at === d || at.startsWith(d + "/"));
+      if (!dir) continue;
+      warnings.push({
+        kind: "territory-in-key-dir",
+        headline: `${r.name} writes ${g} — inside the key directory ${dir}, which no role can write`,
+        detail: "a key directory is read by the roles that declare its keys and written by none. Move what this role writes out of it, or drop the territory.",
+      });
+    }
+  }
+
+  /**
+   * A file granted by name does not come with its neighbours.
+   *
+   * Measured, in production, and it survived two reviews of the policy by people:
+   * a role was granted its database file and still could not write the
+   * database. The database opens a second file beside the first — a journal —
+   * and the sibling was outside the grant, so the write failed in the
+   * database's own words ("readonly") rather than as a permission error.
+   *
+   * What is deliberately NOT here: a list of which programs write which
+   * siblings. That would ask seisin to know about databases, and the next
+   * question is why it does not know about a lock file, the temporary file of
+   * an atomic write, or an editor's backup. The list has no end and every entry
+   * is a guess about a repo nobody foresaw. The general form needs no list: the
+   * kernel grants a path and everything under it, so a grant on a file covers
+   * the file and nothing else. Whether a tool will want a neighbour is the
+   * reader's to know; that the neighbour is not granted is arithmetic.
+   */
+  for (const r of roles) {
+    const { files, subtrees } = territoryOf(config, r);
+    // A file inside one of the role's own subtrees has its siblings covered by
+    // that subtree, so naming it changes nothing and warns about nothing.
+    const alone = files.filter((f) => !subtrees.some((s) => under(dirname(f.abs), s)));
+    if (alone.length)
+      loose.push({ role: r.name, n: alone.length, of: r.writes.filter((g) => !implicitSidecar(r, g)).length,
+                   globs: alone.map((f) => f.glob) });
+
+
+    /**
+     * A territory written as a list of files is a photograph of the folder.
+     *
+     * A sandbox cannot say "the source files in this folder" — one level down
+     * is not a prefix, and `src/*` is refused above for exactly that reason,
+     * correctly. So a territory that means that has to be written as the files
+     * that exist today, and the day a file is added the policy is one behind:
+     * the owning role cannot write its own new file, and nothing fails loudly.
+     *
+     * Reported as a count, never as a verdict. "Comparable" here means only
+     * "a regular file in the same folder" — not the same extension, not the
+     * same shape of name, because either of those is a guess about what the
+     * territory *meant*, and a guess about intent is the thing this check
+     * exists to avoid. The unnamed files are listed by name instead, so the
+     * reader can see in one glance whether the gap is an oversight or a
+     * decision. seisin cannot tell, and does not pretend to.
+     *
+     * Silent when a folder has fewer than two named files (one file is a
+     * grant, not an enumeration) and when the folder is also granted as a
+     * subtree (then the list is decorative).
+     */
+    const byDir = new Map();
+    for (const f of alone) {
+      const dir = dirname(f.abs);
+      if (!byDir.has(dir)) byDir.set(dir, []);
+      byDir.get(dir).push(basename(f.abs));
+    }
+    for (const [dir, named] of byDir) {
+      if (named.length < 2) continue;
+      const onDisk = regularFilesIn(dir);
+      const unnamed = onDisk.filter((n) => !named.includes(n));
+      if (!unnamed.length) continue;
+      const shown = relative(resolve(config.root), dir);
+      listed.push({ role: r.name, named: named.length, total: onDisk.length,
+                    where: shown ? shown + "/" : "the repo root", unnamed });
+
+    }
+  }
+
+  /**
+   * One warning per finding, not one per role.
+   *
+   * These were emitted inside the role loop, which reads fine on the two-role
+   * fixture they were written against and falls apart on a real policy: 30
+   * roles produced 39 of these lines and took `seisin check` from 30 lines to
+   * **297**. That is the defect the detail text below is about — a check nobody
+   * finishes reading protects nobody — reached from the other side.
+   *
+   * So the count leads and a few examples follow. Whoever wants the full list
+   * has `seisin check <role>`, which is the question they were asking anyway.
+   */
+  if (loose.length) {
+    const shown = loose.slice(0, 3).map((l) => `${l.role} (${l.n} of ${l.of})`).join(", ");
+    const more = loose.length > 3 ? `, and ${loose.length - 3} more` : "";
+    warnings.push({
+      kind: "siblings-uncovered",
+      headline:
+        `${loose.length} role(s) grant individual files rather than folders: ${shown}${more}`,
+      detail:
+        "the kernel grants exactly that path. Anything a tool creates beside it — a " +
+        "database's journal, a lock file, the temporary file of an atomic write — is a " +
+        "sibling, and a sibling is outside the grant; the failure arrives in the tool's " +
+        "own words, not as a permission error. Grant the folder where the tool needs " +
+        "neighbours. " +
+        (scoped
+          ? `The files: ${loose[0].globs.join(" ")}.`
+          : "`seisin check <role>` names the files for one role."),
+    });
+  }
+
+  /**
+   * The one sibling that is not a guess: Claude Code's own.
+   *
+   * Claude Code's Edit and Write do not write the file. They write
+   * `<file>.tmp.<pid>.<12 hex>` beside it and rename it over, so a role that
+   * holds a file by name and not its folder is refused at the temporary file
+   * on every edit — EPERM, and the agent goes around it with a shell (measured:
+   * 4 EPERM in one real run). No grant can name that file: its name changes on
+   * every edit, and a write grant takes no glob (the runtime drops them; seisin
+   * refuses one above). So the choice is the folder, or the shell — said per
+   * role, which is where the decision is made.
+   *
+   * Said whatever agent the role runs: check cannot know, and a role that runs
+   * something else reads one line it can skip. Three roles by name and the rest
+   * as a count, for the reason the warning above gives.
+   */
+  for (const l of loose.slice(0, 3)) {
+    // A file at the root has the whole repo for a folder, which is not a
+    // suggestion: then the move is to put it in a folder of its own.
+    const dirs = [...new Set(l.globs.map((g) => dirname(g)).filter((d) => d !== "."))].map((d) => `${d}/**`);
+    const fix = dirs.length
+      ? `Either grant the folder (${dirs.join(", ")})`
+      : "Its folder is the repo root, so either move it into a folder the role can own whole and grant that";
+    warnings.push({
+      kind: "claude-atomic-write",
+      headline: `${l.role}: writes ${l.globs.slice(0, 3).join(" ")}${l.globs.length > 3 ? ` +${l.globs.length - 3}` : ""} by name — ` +
+        "Claude Code's Edit and Write on it fail (EPERM)",
+      detail:
+        "Claude Code edits a file by writing <file>.tmp.<pid>.<random> beside it and renaming it over; " +
+        "the temporary file is outside a grant on the file, and no grant can name it — its name changes " +
+        `on every edit and a write grant takes no glob. ${fix}, ` +
+        "or accept that the agent writes it with its shell (a redirect writes the file itself) instead of Edit. " +
+        "A role that does not run Claude Code can ignore this.",
+    });
+  }
+  if (loose.length > 3)
+    warnings.push({
+      kind: "claude-atomic-write",
+      headline: `${loose.length - 3} more role(s) write files by name, where Claude Code's Edit and Write fail: seisin check <role>`,
+      detail: "",
+    });
+
+  if (listed.length) {
+    const shown = listed.slice(0, 3)
+      .map((l) => `${l.role} names ${l.named} of ${l.total} in ${l.where}`).join("; ");
+    const more = listed.length > 3 ? `; and ${listed.length - 3} more` : "";
+    warnings.push({
+      kind: "enumerated-territory",
+      headline: `${listed.length} territory(ies) list some files of a folder: ${shown}${more}`,
+      detail:
+        `not named, in the first of them: ${listed[0].unnamed.slice(0, 8).join(" ")}` +
+        `${listed[0].unnamed.length > 8 ? ` … and ${listed[0].unnamed.length - 8} more` : ""}` +
+        `. A sandbox grants a path, ` +
+        `not "the files of this kind here", so a territory that means that is the list of files ` +
+        `that existed when it was written — the next one added lands outside it, and nothing ` +
+        `fails loudly. Whether these are left out on purpose is not something a count can tell.`,
+    });
+  }
+  return warnings;
+}

package/src/inspect/limits.js

@@ -0,0 +1,98 @@
+/**
+ * What the tool cannot do at all — as opposed to `warnings`, which are things
+ * wrong with *this* config.
+ *
+ * Kept apart on purpose. A limit printed as a warning reads as something a
+ * person could fix, and after the third run it reads as nothing at all.
+ *
+ * They used to close `check --verbose`, six paragraphs under every repo's
+ * findings, identical in each one — so the part of the output about *this*
+ * repo was the part nobody reached. `check` now names how many there are and
+ * where to read them: `seisin help limits` (help.js prints this list).
+ * `inspect()` still returns them, so the MCP hands them out with the map.
+ */
+export const LIMITS = [
+  ...(process.platform !== "darwin" ? [] : [{
+    kind: "kernel-denials-can-drop",
+    headline: "a flooded system log loses kernel denials before seisin reads them",
+    detail:
+      "the kernel's denials reach `seisin run` through `log stream`, and when something floods " +
+      "the unified log (thousands of lines a second) the stream drops messages before it filters " +
+      "them. The boundary holds; the denial files no request and is not in `seisin log`. A run that " +
+      "lost messages says so when it ends and logs `log-dropped`; `seisin check --system-log` " +
+      "measures it now and names who writes the most. The system's own copy (`log show`) does not " +
+      "help: it lacks the tag that ties a denial to its run.",
+  }]),
+  ...(process.platform === "darwin" ? [] : [{
+    kind: "kernel-denials-unreadable",
+    headline: "denials by the kernel are not recorded on this platform",
+    detail:
+      "on macOS `seisin run` reads them out of the system log, so a denial the hook never " +
+      "saw still lands in `seisin log` with its owner and still queues a request. There is no " +
+      "equivalent to read here — bubblewrap does not log denials, 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/carlostapiacl/seisin/blob/main/docs/upstream/cli-violations.md",
+  }]),
+  {
+    kind: "keys-only-what-you-declared",
+    headline: "key isolation covers the directory you declared, and nothing else",
+    detail:
+      "a credential sitting in the repo outside [keys] dir is ordinary readable " +
+      "content to every role. Run `seisin scan` to find them — check does not, " +
+      "because reading the whole tree on every invocation is how a command stops " +
+      "being run.",
+  },
+  {
+    kind: "observe-cannot-see-the-network",
+    headline: "`--observe` opens the filesystem, never the network",
+    detail:
+      "so it cannot tell you which domains an agent needs. The runtime does record every " +
+      "denial the proxy makes — host, port and reason — but only a caller that embeds the " +
+      "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/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 " +
+      "denies 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 sandbox 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: "agent-sign-in",
+    headline: "~/.claude goes only to runs of claude, ~/.codex only to runs of codex",
+    detail:
+      "seisin reads the agent off the command after `--`, and a run is denied the other " +
+      "agents' sign-in files (~/.codex/auth.json, ~/.claude/.credentials.json). What a run " +
+      "of an agent can still read is its own: Codex and every command Codex runs share one " +
+      "sandbox, so with a ChatGPT sign-in kept in ~/.codex/auth.json they can read those tokens. " +
+      "Codex keeps them in the keychain instead with cli_auth_credentials_store = \"keyring\" " +
+      "in its config. A wrapper script is not followed: `seisin run <role> --agent codex -- ./script` " +
+      "names it. The protected paths `seisin check --verbose` lists are for every agent at once, " +
+      "because a role can be run as any of them.",
+  },
+  {
+    kind: "unlink-uncovered",
+    headline: "a role can delete inside its own territory",
+    detail:
+      // The path that used to be here ships with the repo and not with the npm
+      // 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/carlostapiacl/seisin#how-it-holds",
+  },
+];

package/src/inspect/machine.js

@@ -0,0 +1,107 @@
+import { resolve, delimiter, join } from "node:path";
+import { realOrSelf, runtimeWritesFor, toWritePath } from "../grants.js";
+import { realAncestor } from "../paths.js";
+import { wired, broadlyWired } from "../commands/wire.js";
+
+export function relativePathWarnings() {
+  const warnings = [];
+  // 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 sandbox; 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 sandbox.",
+    });
+  return warnings;
+}
+
+export function scratchWarnings(config) {
+  const warnings = [];
+  // Scratch is granted to every role, so a repo sitting inside it is writable
+  // by all of them no matter what the territory says. Saying so is the
+  // difference between a limitation and a trap — and it is not hypothetical:
+  // the test fixture lived in the temp dir and made a boundary test pass for
+  // the wrong reason, and a role in a toy repo under /tmp wrote outside its
+  // `writes` with nothing on screen to say why.
+  // Both sides resolved, or the comparison is a coin flip. `expand()` follows
+  // symlinks — it has to, because on macOS /tmp is a link to /private/tmp and a
+  // grant written as /tmp grants nothing — so the root has to be followed too.
+  // Without this a repo at /tmp/x is never reported as sitting in scratch,
+  // which is the one case where the warning matters most.
+  //
+  // The scratch a role is really given, not the default list: `[runtime]
+  // writes` when the policy sets it, and none of it under `isolate = "home"`,
+  // where each role gets a home of its own instead (grants.js, writePathsOf).
+  const level = config.isolate === true ? "home" : config.isolate;
+  const scratch = level === "home" ? [] : runtimeWritesFor(config, undefined);
+  const under = (p) => scratch.find((s) => p === s || p.startsWith(s + "/"));
+  const fix = (s) => `Move it out of ${s}, or set [runtime] writes to a list that leaves ${s} out ` +
+    `(\`[runtime] writes = []\` gives no role any shared scratch).`;
+  const root = realOrSelf(resolve(config.root));
+  const around = under(root);
+  if (around) {
+    warnings.push({
+      kind: "scratch",
+      headline: `every role can write the whole repo: it lives inside ${around}, which every role gets as scratch`,
+      detail: "Territory does not hold here — a role's writes is no limit when the directory around the repo " +
+        `is granted to all of them. ${fix(around)}`,
+    });
+    return warnings;
+  }
+  /**
+   * The repo is outside scratch, and part of a territory still is: a `writes`
+   * entry that goes through a symlink (`out -> /tmp/out`) or up and out with
+   * `..`. The kernel enforces on the real path, so that part of the role's
+   * territory is every role's. Said per resolved path, once.
+   */
+  const seen = new Set();
+  for (const r of Object.values(config.roles)) {
+    for (const g of r.writes ?? []) {
+      let real;
+      try { real = realAncestor(join(config.root, toWritePath(g))); } catch { continue; }
+      const s = under(real);
+      if (!s || seen.has(real)) continue;
+      seen.add(real);
+      warnings.push({
+        kind: "territory-in-scratch",
+        headline: `every role can write ${r.name}'s ${g}: it resolves to ${real}, inside ${s}, which every role gets as scratch`,
+        detail: `That part of ${r.name}'s territory does not hold — the kernel enforces on the real path. ${fix(s)}`,
+      });
+    }
+  }
+  return warnings;
+}
+
+export function hookWarnings(config) {
+  const warnings = [];
+  if (!wired(config.root))
+    warnings.push({
+      kind: "hook-not-wired",
+      headline: "only denials are being recorded: the agent has not been told to run the hook",
+      detail:
+        process.platform === "darwin"
+          ? "the boundary holds either way, and denials are still logged and still queue a " +
+            "request — `seisin run` reads them from the kernel. What is missing is every " +
+            "action that was allowed, so `review` cannot tell you which grants are unused and " +
+            "`init --from-observations` has nothing to build from. Run `seisin wire` once in " +
+            "this repo."
+          : "the boundary holds either way — but on this platform the kernel's denials are " +
+            "not readable either, so log, watch, requests, grant and review all read a record " +
+            "that nobody is writing. Run `seisin wire` once in this repo.",
+    });
+
+  else if (broadlyWired(config.root))
+    warnings.push({
+      kind: "hook-matcher-broad",
+      headline: "the hook runs on every tool call: it was wired before 0.5.0 with the matcher \"*\"",
+      detail:
+        "nothing is lost — every tool the hook reads is still covered — but each Read, Glob " +
+        "and TodoWrite starts a process that has nothing to say. Run `seisin wire` again: it " +
+        "narrows seisin's own entry in place and leaves everyone else's hooks alone.",
+    });
+  return warnings;
+}

package/src/inspect/network.js

@@ -0,0 +1,37 @@
+export function modelEndpointWarnings(config, roles) {
+  const warnings = [];
+  /**
+   * A role that can write code and cannot reach any inference API.
+   *
+   * Reported three separate times, by three different people, with the same
+   * shape each time: a list of what agents need, written somewhere that does
+   * not know which agent will run. The last instance cost six bench runs that
+   * finished in eight seconds with `403 Connection blocked by network
+   * allowlist` — which in a results table reads as "this model cannot do the
+   * task", not as a policy error.
+   *
+   * What is deliberately NOT here: a registry of agents and their endpoints.
+   * That is the same defect in a new place, and the reporter said so before I
+   * could. The list below is only ever consulted to decide whether to print a
+   * sentence, so being wrong about it costs a false warning — never a broken
+   * run. That asymmetry is the whole reason it is allowed to exist, and the
+   * warning says out loud that the list is ours and may not know your agent.
+   */
+  const INFERENCE = /(anthropic|openai|googleapis|generativelanguage|bedrock|azure|openrouter|mistral|groq|together|deepseek|x\.ai|cohere|ollama|localhost|127\.0\.0\.1)/i;
+  for (const r of roles) {
+    const domains = r.network ?? config.allowedDomains ?? [];
+    if (domains.some((d) => INFERENCE.test(d))) continue;
+    warnings.push({
+      kind: "no-model-endpoint",
+      headline: domains.length
+        ? `${r.name} has ${domains.length} allowed domain(s) and none looks like a model API`
+        : `${r.name} may reach no network at all`,
+      detail:
+        "an agent that cannot reach its own model fails at startup with a 403 from the " +
+        "egress proxy, which reads as a broken install or a bad model rather than a policy. " +
+        "This check knows a handful of providers and will not know yours — it is a question, " +
+        "not a verdict.",
+    });
+  }
+  return warnings;
+}

package/src/inspect/providers.js

@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import { entriesOf } from "../keys.js";
+import { resolveExecutable } from "../surface.js";
+
+/**
+ * Would the parent find this command? The same lookup `run` makes
+ * (resolveExecutable), so check does not call "missing" a program that is
+ * only in a directory a role writes — that has its own warning, above.
+ */
+function onPath(cmd, config) {
+  try {
+    // A path is resolved against the policy and not looked up, so it is there
+    // only if it exists.
+    return existsSync(resolveExecutable(cmd, config));
+  } catch (e) {
+    return /a role can write/.test(e.message);
+  }
+}
+
+export function providerInTerritoryWarnings(config) {
+  const warnings = [];
+  // 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(" "),
+      });
+    }
+  }
+  return warnings;
+}
+
+export function providerMissingWarnings(config) {
+  const warnings = [];
+  /**
+   * 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], config)) 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 run, not here.",
+    });
+  }
+  return warnings;
+}