vigiles 27.3.0 → 29.0.0

package/dist/core/validate.js

@@ -2,8 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_RULES = void 0;
 exports.findInstructionFiles = findInstructionFiles;
-exports.normalizeSeverity = normalizeSeverity;
-exports.asStringArray = asStringArray;
 exports.loadConfig = loadConfig;
 exports.parseRules = parseRules;
 exports.validate = validate;
@@ -14,6 +12,25 @@ const node_fs_1 = require("node:fs");
 const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 const cosmiconfig_1 = require("cosmiconfig");
+// 🔴 A TOP-LEVEL IMPORT, and the lazy `require` it replaced is recorded because
+// the instinct to reintroduce it is correct-sounding: Zod is a ~45 ms cold
+// import and this module is on the CLI's barrel. Two measured facts settle it.
+//
+// (1) It does not reach the HOT rail at all. A compiled hook's decision
+//     (`vigiles hook-runtime run-program`) never loads the verb barrel — the
+//     dispatcher shim in `src/cli.ts` branches before it, and
+//     `src/hook-runtime-graph.test.ts` fails the day that stops being true — so
+//     it never loads this file, lazily or otherwise.
+// (2) On the rails that DO load the barrel (the PostToolUse `refs` and
+//     `eval-lock-nudge` nudges) the floor is ~316 ms of Node startup plus ~85
+//     existing requires, against which 45 ms is ~13%, not a breach.
+//
+// And the attempt is on record as well: an in-body `require("./config-schema")`
+// resolves in `dist` (CommonJS) and NOT under vitest, which imports the `.ts`
+// sources — it failed every suite that touches `loadConfig`. A deferral that
+// only works in one of the two worlds the code runs in is not one line of
+// hygiene, it is a second module system.
+const config_schema_js_1 = require("./config-schema.js");
 // ---------------------------------------------------------------------------
 // Constants & regex
 // ---------------------------------------------------------------------------
@@ -21,7 +38,6 @@ const GUIDANCE_RE = /\*\*Guidance only\*\*/;
 const DISABLE_RE = /<!--\s*vigiles-disable\s*-->/;
 const RULE_HEADER_RE = /^###\s+(.+)$/;
 const CHECKBOX_RE = /^- \[([ xX])\]\s+(.+)$/;
-const VALID_MARKERS = ["headings", "checkboxes"];
 // ---------------------------------------------------------------------------
 // Default config
 // ---------------------------------------------------------------------------
@@ -31,103 +47,25 @@ const VALID_MARKERS = ["headings", "checkboxes"];
 const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
-exports.DEFAULT_RULES = {
-    // 🔴 BOTH DROP TO "warn", and that is a deliberate behaviour change.
-    //
-    // They used to feed the exit code directly and could not be tiered at all
-    // (#181), so a single unreferenced doc turned a PR red with no way to say
-    // "report it, do not block". Naming them as rules made the contradiction
-    // visible: both are HEURISTIC-BEHAVIORAL (an NCD similarity proxy, an
-    // "unreferenced" guess that an OSS sweep measured at ~100% false positives on
-    // nav-managed doc sites), and this repo's own calibration rule is that a
-    // heuristic never defaults to `error` because it cries wolf. `orphan-docs`
-    // already DECLARED `warn` in its meta while behaving as `error` — the gate
-    // caught that disagreement the moment the rule was registered properly.
-    //
-    // Set either to `"error"` to keep the old blocking behaviour.
-    // Hard error, like `compile` itself: a dead reference is decidable from the
-    // filesystem, not a proxy — the calibration rule's `external-decidable` tier.
-    "spec-refs": "error",
-    "orphan-docs": "warn",
-    "duplicate-rules": "warn",
-    "require-instructions-spec": "warn",
-    // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
-    // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong
-    // default (it would nag about vendored/fixture/bench skills); the coverage that
-    // matters is the `untested-*` rules ("every skill/agent/hook ships with a test
-    // or eval"). Set `require-skill-spec` explicitly if your team wants every skill
-    // spec-managed.
-    "require-skill-spec": false,
-    integrity: "warn",
-    coverage: false,
-    // Per-kind surface-coverage: a skill/agent/hook must ship with a test or eval.
-    "untested-skill": "warn",
-    "untested-subagent": "warn",
-    "untested-hook": "warn",
-    "unmarked-refs": "warn",
-    // High-precision (never-available + close typos only), so on by default at warn.
-    "subagent-tool-contract": "warn",
-    // High-precision (close typos only), on by default at warn.
-    "hook-events": "warn",
-    // Missing required frontmatter (name/description) — on by default at warn.
-    "subagent-frontmatter": "warn",
-    // A declared MCP server with no command/url can't start — on by default at warn.
-    "mcp-config": "warn",
-    // Best-practice nudge (skills load without frontmatter) — warn, not error.
-    "skill-frontmatter": "warn",
-    // High-precision (gated on a declared MCP set; built-ins allowlisted) — warn.
-    "mcp-tool-resolves": "warn",
-    // A hook script referenced but missing never runs — on by default at warn.
-    "hook-script-exists": "warn",
-    // Discovery nudge toward compiled hooks (one finding) — default OFF: it's a
-    // recommendation, not a defect (the hand-written shell lane stays first-class),
-    // so it shouldn't fire unasked. Set "warn"/"error" to opt in.
-    "prefer-compiled-hooks": false,
-    // High-precision (close-typo only) deny-list mirror of subagent-tool-contract.
-    "disallowed-tools-contract": "warn",
-    // Deterministic NCD precision proxy (near-identical skill descriptions) — warn.
-    "description-overlap": "warn",
-    // A model-invocable skill's description so long the trigger signal is buried —
-    // WARN only (heuristic proxy, generous 500-char budget); never gates.
-    "skill-description-budget": "warn",
-    // Malformed-YAML frontmatter — WARN only (js-yaml is stricter than some loaders).
-    "frontmatter-valid": "warn",
-    // A mcp_tool hook incomplete / targeting an undeclared server — on by default at warn.
-    "mcp-hook-target-resolves": "warn",
-    // Lethal-trifecta capability set-intersection (read-private + ingest-untrusted +
-    // exfiltrate in one unit) — WARN by default (don't-cry-wolf rollout); raise to error.
-    "lethal-trifecta": "warn",
-    // A SKILL.md body referencing a missing bundled resource — WARN by default
-    // (don't-cry-wolf rollout, FP-safe); raise to error to gate CI.
-    "skill-resource-resolves": "warn",
-    // A SKILL.md missing its opening `---` fence (invisible skill) — WARN by
-    // default (FP-safe key whitelist); raise to error to gate CI.
-    "skill-missing-fence": "warn",
-    // Functional dirs nested inside `.claude-plugin/` (invisible surfaces) — WARN
-    // by default; raise to error to gate CI.
-    "plugin-dir-layout": "warn",
-    // A lethal trifecta emerging across a delegation edge (combined blast radius) —
-    // WARN by default (don't-cry-wolf rollout); raise to error to gate CI.
-    "delegation-trifecta": "warn",
-    // A hook that looks like it blocks but silently doesn't (#19009) — WARN by
-    // default (FP-safe literal patterns); raise to error to gate CI.
-    "hook-block-ineffective": "warn",
-    // A hook matcher that doesn't fire as written (tool typo, an MCP pattern
-    // that matches no tool name, or one too narrow for real server names) — WARN
-    // by default (high-precision); raise to error to gate CI.
-    "hook-matcher": "warn",
-    // Builder calls quoted inside ```ts fences in markdown — default OFF. Measured
-    // over 2 582 markdown files across two repos: 52 refs, 0 true positives, and
-    // every error raised was a false one (a design sketch's `cmd("npm test")`, a
-    // vendored third-party CLAUDE.md). A fence in prose is a DRAWING of config;
-    // reading it as config is the defect. Opt in where markdown IS the source.
-    "doc-refs": false,
-};
-const DEFAULT_CONFIG = {
-    ruleMarkers: ["headings", "checkboxes"],
-    rules: exports.DEFAULT_RULES,
-    files: DEFAULT_FILES,
-};
+/**
+ * The shipped default severity of every rule — DERIVED from the schema, never
+ * listed twice.
+ *
+ * It used to be the literal beside the type, which is exactly the pair that
+ * drifts: `rule-meta.test.ts` already cross-checks each rule's documented
+ * `defaultSeverity` against this object, and it could only ever catch a doc that
+ * disagreed with the literal, never a literal that disagreed with what parsing
+ * actually produced. Reading it out of the parser closes that gap: this IS what
+ * a `{}` config loads as.
+ */
+exports.DEFAULT_RULES = defaultConfig()
+    .rules;
+/** The default rule markers — read from the schema, like every other default. */
+const DEFAULT_MARKERS = defaultConfig().ruleMarkers;
+/** A freshly parsed empty config — the defaults, straight from the schema. */
+function defaultConfig() {
+    return config_schema_js_1.vigilesConfigSchema.parse({});
+}
 // ---------------------------------------------------------------------------
 // Instruction file discovery
 // ---------------------------------------------------------------------------
@@ -139,92 +77,80 @@ function findInstructionFiles(cwd = process.cwd(), configFiles) {
 // Config loading
 // ---------------------------------------------------------------------------
 /**
- * ESLint users write `"off"` / `0` / `1` / `2` for severity; normalize to
- * vigiles's `"warn" | "error" | false` so a rule the user meant to DISABLE
- * (`"off"`) or GATE (`2`) actually does — instead of a truthy string / number
- * silently rendering as a non-gating warn (issue #112 + numeric severities). The
- * array form `[sev, opts]` recurses on the head. An unrecognized value is left
- * as-is (it renders as a warn, the pre-existing behavior).
+ * Read and VALIDATE `.vigilesrc.json`.
+ *
+ * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
+ * working directory and walks up — right for a CLI verb, where the user is
+ * standing in the project they mean, and wrong for a hook, whose process has no
+ * stable cwd. A hook rail that omits it reads a DIFFERENT project's config, or
+ * none, and the failure runs the wrong way: a missing file means defaults, so a
+ * rule the author switched OFF comes back on, silently, because the file saying
+ * "off" was never found. Nothing in the output distinguishes that from a project
+ * that never configured the rule.
+ *
+ * 🔴 `onInvalid` IS THE ONE PLACE THE CALL SITES DIFFER, AND IT IS NOT A SPLIT
+ * IN WHAT IS CHECKED. Every reader validates; they disagree only about what a
+ * bad config is allowed to do to them. A VERB is a human standing at a prompt
+ * having just edited the file — `"throw"`, so the line they typed is refused out
+ * loud. A HOOK RAIL is a fresh process inside somebody's editing session, and a
+ * hook that dies on a malformed config turns a typo in a JSON file into a failed
+ * edit, which is a worse outcome than the nudge not firing — `"warn"`, print the
+ * same lines to stderr and carry on with the defaults.
+ *
+ * The two hook rails are `refsHookCommand` and `evalLockNudgeHookCommand`
+ * (`vigiles hook-runtime refs` / `eval-lock-nudge`, both registered as
+ * PostToolUse `Edit|Write` in `.claude-plugin/plugin.json`). Every other reader
+ * is a verb.
+ *
+ * ⚠️ THE SCHEMA MODULE IS REQUIRED IN-BODY, and that is hygiene rather than an
+ * optimization worth a paragraph: Zod is a ~45 ms cold import, `tsc` emits
+ * CommonJS across 230 separate files, so a `require` in a function body genuinely
+ * does not execute until the function is called. A rail that never reads a
+ * config never pays for the validator.
  */
-function normalizeSeverity(v) {
-    if (Array.isArray(v))
-        return [normalizeSeverity(v[0]), v[1]];
-    if (v === "off" || v === 0 || v === false)
-        return false;
-    if (v === "error" || v === 2)
-        return "error";
-    if (v === "warn" || v === 1)
-        return "warn";
-    return v;
-}
-/**
- * Coerce a config value that should be a `string[]`: a bare STRING becomes a
- * one-element array (the natural first-value mistake), so `exclude` /
- * `orphans.include` don't silently iterate a string's CHARACTERS as globs — a
- * no-op at best, and garbage "orphan" matches (`.`, `/`, `README.md`) at worst.
- * A non-string/array value falls back with a warning (the `ruleMarkers` pattern).
- */
-function asStringArray(v, fallback, key) {
-    if (typeof v === "string")
-        return [v];
-    if (Array.isArray(v))
-        return v.filter((x) => typeof x === "string");
-    console.warn(`Invalid ${key} in config: expected a string or string[], got ${JSON.stringify(v)}. Ignoring.`);
-    return fallback;
-}
-function loadConfig() {
+function loadConfig(searchFrom, { onInvalid = "throw" } = {}) {
+    let raw;
     try {
         const explorer = (0, cosmiconfig_1.cosmiconfigSync)("vigiles", {
             searchPlaces: [".vigilesrc.json"],
             mergeSearchPlaces: false,
         });
-        const result = explorer.search();
-        if (!result?.config)
-            return { ...DEFAULT_CONFIG };
-        const userConfig = result.config;
-        const config = {
-            ...DEFAULT_CONFIG,
-            ...userConfig,
-            // Normalize ESLint-idiom severities ("off"/0/1/2) across the merged rules,
-            // so a config value coerces to a real gating decision instead of a truthy
-            // string silently downgrading to warn.
-            rules: Object.fromEntries(Object.entries({ ...exports.DEFAULT_RULES, ...userConfig.rules }).map(([k, v]) => [k, normalizeSeverity(v)])),
-            files: Array.isArray(userConfig.files) ? userConfig.files : DEFAULT_FILES,
-        };
-        // Parse-don't-validate the array-shaped keys ONCE here: a bare string is
-        // accepted as [string]; anything else warns + falls back. Downstream code
-        // then always sees a real string[] (no char-by-char glob spread).
-        if (userConfig.exclude !== undefined)
-            config.exclude = asStringArray(userConfig.exclude, [], "exclude");
-        if (userConfig.sharedDirs !== undefined)
-            config.sharedDirs = asStringArray(userConfig.sharedDirs, [], "sharedDirs");
-        if (config.orphans) {
-            config.orphans = {
-                ...config.orphans,
-                include: config.orphans.include === undefined
-                    ? undefined
-                    : asStringArray(config.orphans.include, [], "orphans.include"),
-                exclude: config.orphans.exclude === undefined
-                    ? undefined
-                    : asStringArray(config.orphans.exclude, [], "orphans.exclude"),
-            };
-        }
-        if (!Array.isArray(config.ruleMarkers) ||
-            !config.ruleMarkers.every((m) => VALID_MARKERS.includes(m))) {
-            console.warn(`Invalid ruleMarkers in config: ${JSON.stringify(config.ruleMarkers)}. Using default.`);
-            config.ruleMarkers = [...DEFAULT_CONFIG.ruleMarkers];
-        }
-        return config;
+        raw = explorer.search(searchFrom)?.config;
     }
     catch {
-        return { ...DEFAULT_CONFIG };
+        // No file, unreadable file, malformed JSON — the defaults, as always. A
+        // config we CAN read and refuse is a different thing and is handled below.
+        return defaultConfig();
+    }
+    if (raw === undefined || raw === null)
+        return defaultConfig();
+    // The replaced keys get their own message BEFORE the schema's, because the
+    // reader is someone whose config used to work: `.strict()` would tell them
+    // "unknown key harness", which is true and useless. See REPLACED_KEYS.
+    const problems = [];
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+        const present = config_schema_js_1.REPLACED_KEYS.filter((k) => k.key in raw);
+        if (present.length > 0)
+            problems.push((0, config_schema_js_1.replacedKeyMessage)(present));
+    }
+    if (problems.length === 0) {
+        const parsed = config_schema_js_1.vigilesConfigSchema.safeParse(raw);
+        if (parsed.success)
+            return parsed.data;
+        problems.push(...(0, config_schema_js_1.formatConfigIssues)(parsed.error.issues));
     }
+    if (onInvalid === "throw")
+        throw new config_schema_js_1.VigilesConfigError(problems.join("\n"));
+    for (const line of problems)
+        console.warn(`⚠ ${line}`);
+    console.warn("⚠ Using default configuration.");
+    return defaultConfig();
 }
 // ---------------------------------------------------------------------------
 // Parsing
 // ---------------------------------------------------------------------------
 function parseRules(content, { ruleMarkers } = {}) {
-    const markers = ruleMarkers ?? DEFAULT_CONFIG.ruleMarkers;
+    const markers = ruleMarkers ?? DEFAULT_MARKERS;
     const lines = content.split("\n");
     const rules = [];
     let currentRule = null;

package/dist/exclude.d.ts

@@ -22,4 +22,24 @@ export interface ExcludeSet {
 }
 /** Parse `.vigilesrc.json#exclude` once, against `root`. */
 export declare function excludeSet(root: string, patterns: readonly string[] | undefined): ExcludeSet;
+/**
+ * Is this ABSOLUTE path dropped by `.vigilesrc.json#exclude`?
+ *
+ * The PREDICATE face, for a hand-rolled recursive walk that has an absolute path
+ * in hand and no glob (`readTree` in `src/plugin-loader.ts`, the bounded root
+ * walk in `src/surface-discovery-fs.ts`). A predicate rather than an
+ * `ExcludeSet` so the walk never has to remember which root the patterns are
+ * relative to: {@link excludedBy} closes over `excludes.root`, which is the REPO
+ * root and NOT the audited dir — `vigiles audit some/dir` must still honour a
+ * root-relative `exclude`.
+ *
+ * Lives HERE, beside the other two faces, because this file is the one
+ * exclusion policy (#192) and this was its third face living in one caller's
+ * private scope — which is how a second walk ends up writing a fourth.
+ */
+export type Excluded = (absPath: string) => boolean;
+/** The default: exclude nothing (every caller that passes no `ExcludeSet`). */
+export declare const excludesNothing: Excluded;
+/** The {@link Excluded} face of an `ExcludeSet`, or {@link excludesNothing}. */
+export declare function excludedBy(excludes: ExcludeSet | undefined): Excluded;
 //# sourceMappingURL=exclude.d.ts.map

package/dist/exclude.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXCLUDE_FLOOR = void 0;
+exports.excludesNothing = exports.EXCLUDE_FLOOR = void 0;
 exports.excludeSet = excludeSet;
+exports.excludedBy = excludedBy;
 /**
  * The ONE exclusion policy for every walk that polices the user's repository (#192) — the parsed `.vigilesrc.json#exclude` as an `ExcludeSet`, built ONCE where `loadConfig()` runs and taken as a REQUIRED parameter by every in-scope discovery (`findSpecs`, `findInstructionFiles`, `discoverNestedBundles`, `collectDocumentedRules`, `gatherInstructionFiles` in cli.ts; the string face handed to `findDocRefs`, `findOrphanDocs` (`repoExclude`), `findUntestedSurfaces`/`skillTestNudge`, `discoverScripts`, `computeScriptCoverage`).
  * Two faces: `globIgnore` (an `IgnoreLike` keyed on the path's position relative to the REPO root, so a glob rooted below it — `vigiles lint some/dir` — still applies a root-relative exclude) and `ignore` (the normalized string list for pure core detectors that glob from the root).
@@ -65,4 +66,13 @@ function excludeSet(root, patterns) {
         explain,
     };
 }
+/** The default: exclude nothing (every caller that passes no `ExcludeSet`). */
+const excludesNothing = () => false;
+exports.excludesNothing = excludesNothing;
+/** The {@link Excluded} face of an `ExcludeSet`, or {@link excludesNothing}. */
+function excludedBy(excludes) {
+    if (!excludes)
+        return exports.excludesNothing;
+    return (abs) => excludes.matches((0, node_path_1.relative)(excludes.root, abs));
+}
 //# sourceMappingURL=exclude.js.map

package/dist/harness-test.js

@@ -430,7 +430,7 @@ async function runHarnessTest(spec, opts = {}) {
     // Default (no adapter): the unchanged Claude Code driver — keeps the
     // sandbox/confined path and behaviour byte-for-byte identical.
     const driver = adapter
-        ? requireDriver(adapter)
+        ? await requireDriver(adapter)
         : exports.claudeCodeDriver;
     const isClaudeCode = driver.runtime.name === runtime_js_1.claudeCodeRuntime.name;
     const decision = (0, sandbox_js_1.decideSandbox)({
@@ -528,12 +528,12 @@ async function runHarness(spec, opts = {}) {
     return runHarnessTest(spec, opts);
 }
 /** Pull the pillar-2 driver off an adapter, asserting it supports testing. */
-function requireDriver(adapter) {
+async function requireDriver(adapter) {
     (0, adapter_conformance_js_1.assertHarnessTestable)(adapter);
     if (!adapter.harnessTestDriver) {
         throw new Error(`Adapter "${adapter.name}" declares harnessTesting but carries no harnessTestDriver — it cannot drive runHarnessTest.`);
     }
-    return adapter.harnessTestDriver;
+    return await adapter.harnessTestDriver();
 }
 /* v8 ignore stop */
 //# sourceMappingURL=harness-test.js.map

package/dist/hook-install.d.ts

@@ -1,3 +1,4 @@
+import type { DispatchKind } from "./core/hook-program.js";
 /** The agnostic, committed home for hook SOURCE — one dir, cross-adapter. */
 export declare const HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
@@ -55,6 +56,58 @@ export declare function normalizeHookRef(hookPath: string, cwd?: string): string
  * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
  * it is asserted directly rather than left to inspection.
  */
+/**
+ * Where the hook runtime lives, spelled so the shell can find it WITHOUT `npx`.
+ *
+ * 🔴 MEASURED 2026-09-19, warm cache, five runs each:
+ *
+ *     node <local>/dist/cli.js hook-runtime run-program …   193 ms
+ *     npx vigiles              hook-runtime run-program …  2545 ms
+ *
+ * Thirteen times, on every tool call, because `npx` re-resolves the package on
+ * each invocation — local, then global, then the registry. That search is the
+ * single largest cost in a hook's life; everything the runtime does inside adds
+ * up to less than a fifth of it.
+ *
+ * A harness with no project-root token gets the relative spelling, which is all
+ * it can be given — see {@link hookGateRef} for the same fallback.
+ */
+export declare function hookRuntimeRef(projectRootTokens: readonly string[] | undefined): string;
+/**
+ * What the shell must do when the runtime above CANNOT START — a missing
+ * `node_modules/vigiles`, an unreadable file, an interpreter that dies before a
+ * single line of ours runs. No code of ours executes in that case, so the policy
+ * has to be expressed in the emitted command or not at all.
+ *
+ * 🔴 THIS IS NOT A NEW POLICY. `runHookProgramCommand`'s load-failure branch has
+ * decided it since 2026-08: *"an inject's purpose is to ADD context, not to
+ * ENFORCE a decision … Gates (file, bash, prompt, stop) remain conservative and
+ * fail closed."* That branch only reaches failures that happen AFTER the runtime
+ * starts. This carries the same rule one layer out, to the failures that happen
+ * before it.
+ *
+ * WHY THE SPLIT, RATHER THAN ONE ANSWER FOR EVERYTHING — the two failures are
+ * not comparable:
+ *
+ *   A GATE THAT SILENTLY PASSES IS WORSE THAN NO GATE. Its whole value is the
+ *   refusal, and a harness that reports protection it is not providing is the
+ *   one state worse than admitting it has none. So a gate whose runtime is
+ *   missing exits 2: loud, blocking, and the cause is on stderr.
+ *
+ *   A NUDGE THAT BLOCKS COSTS THE WHOLE REPOSITORY. Measured here 2026-08-10:
+ *   merge-conflict markers in `package.json` stopped every hook loading, the
+ *   Bash gate then refused `git merge --abort` — the one command that undoes the
+ *   cause — and the session could not be repaired from inside. A reminder is
+ *   never worth that, so a nudge exits 0 and says nothing it cannot say.
+ *
+ * The role is not a flag someone can flip: `Reaction` has no `deny` and an
+ * inject returns context, so "nudge" is a fact about the TYPE the author chose.
+ *
+ * (Industry does not agree on one answer either — husky and lefthook skip,
+ * pre-commit fails. Which is itself the argument for deciding by role instead
+ * of picking one and imposing it on both.)
+ */
+export declare function hookRuntimeMissingExit(kind: DispatchKind): 0 | 2;
 export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`

package/dist/hook-install.js

@@ -4,6 +4,8 @@ exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
 exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
 exports.normalizeHookRef = normalizeHookRef;
+exports.hookRuntimeRef = hookRuntimeRef;
+exports.hookRuntimeMissingExit = hookRuntimeMissingExit;
 exports.hookGateRef = hookGateRef;
 exports.mergeHooksJson = mergeHooksJson;
 exports.mergeHooksToml = mergeHooksToml;
@@ -99,6 +101,64 @@ function normalizeHookRef(hookPath, cwd = process.cwd()) {
  * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
  * it is asserted directly rather than left to inspection.
  */
+/**
+ * Where the hook runtime lives, spelled so the shell can find it WITHOUT `npx`.
+ *
+ * 🔴 MEASURED 2026-09-19, warm cache, five runs each:
+ *
+ *     node <local>/dist/cli.js hook-runtime run-program …   193 ms
+ *     npx vigiles              hook-runtime run-program …  2545 ms
+ *
+ * Thirteen times, on every tool call, because `npx` re-resolves the package on
+ * each invocation — local, then global, then the registry. That search is the
+ * single largest cost in a hook's life; everything the runtime does inside adds
+ * up to less than a fifth of it.
+ *
+ * A harness with no project-root token gets the relative spelling, which is all
+ * it can be given — see {@link hookGateRef} for the same fallback.
+ */
+function hookRuntimeRef(projectRootTokens) {
+    const rel = "node_modules/vigiles/dist/cli.js";
+    const token = projectRootTokens?.[0];
+    return token === undefined ? `node ${rel}` : `node "${token}/${rel}"`;
+}
+/**
+ * What the shell must do when the runtime above CANNOT START — a missing
+ * `node_modules/vigiles`, an unreadable file, an interpreter that dies before a
+ * single line of ours runs. No code of ours executes in that case, so the policy
+ * has to be expressed in the emitted command or not at all.
+ *
+ * 🔴 THIS IS NOT A NEW POLICY. `runHookProgramCommand`'s load-failure branch has
+ * decided it since 2026-08: *"an inject's purpose is to ADD context, not to
+ * ENFORCE a decision … Gates (file, bash, prompt, stop) remain conservative and
+ * fail closed."* That branch only reaches failures that happen AFTER the runtime
+ * starts. This carries the same rule one layer out, to the failures that happen
+ * before it.
+ *
+ * WHY THE SPLIT, RATHER THAN ONE ANSWER FOR EVERYTHING — the two failures are
+ * not comparable:
+ *
+ *   A GATE THAT SILENTLY PASSES IS WORSE THAN NO GATE. Its whole value is the
+ *   refusal, and a harness that reports protection it is not providing is the
+ *   one state worse than admitting it has none. So a gate whose runtime is
+ *   missing exits 2: loud, blocking, and the cause is on stderr.
+ *
+ *   A NUDGE THAT BLOCKS COSTS THE WHOLE REPOSITORY. Measured here 2026-08-10:
+ *   merge-conflict markers in `package.json` stopped every hook loading, the
+ *   Bash gate then refused `git merge --abort` — the one command that undoes the
+ *   cause — and the session could not be repaired from inside. A reminder is
+ *   never worth that, so a nudge exits 0 and says nothing it cannot say.
+ *
+ * The role is not a flag someone can flip: `Reaction` has no `deny` and an
+ * inject returns context, so "nudge" is a fact about the TYPE the author chose.
+ *
+ * (Industry does not agree on one answer either — husky and lefthook skip,
+ * pre-commit fails. Which is itself the argument for deciding by role instead
+ * of picking one and imposing it on both.)
+ */
+function hookRuntimeMissingExit(kind) {
+    return kind === "inject" || kind === "react" ? 0 : 2;
+}
 function hookGateRef(ref, projectRootTokens) {
     const token = projectRootTokens?.[0];
     return token === undefined ? ref : `"${token}/${ref}"`;

package/dist/hook-runtime.d.ts

@@ -45,9 +45,9 @@ import { loadHook } from "./load-hook.js";
  */
 export declare const loadHookProgram: typeof loadHook;
 /** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
-export declare function loadProvider(file: string): Promise<RegisteredProvider>;
+export declare function loadProvider(file: string, root?: string): Promise<RegisteredProvider>;
 /** Path of the tamper-evident stamp sidecar for a hook file. */
-export declare function hookStampPath(file: string): string;
+export declare function hookStampPath(file: string, root?: string): string;
 /**
  * `vigiles hook-runtime run-program <file>` — the runtime the compiled hooks block
  * points at. Reads the live event on stdin, loads the typed program, verifies