vigiles 32.1.0 → 33.0.0

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -1,3 +1,16 @@
+/**
+ * vigiles — run harness-test / eval script files via the CLI.
+ *
+ * `vigiles test` and `vigiles eval` discover `*.harness.*` / `*.eval.*`
+ * scripts and run each as a child `node` process, so the two-tier
+ * harness-testing API (`src/harness-test.ts`, `src/eval.ts`) works as a CI
+ * command, not just `node x.mjs`. Scripts may be authored in **JavaScript**
+ * (`.mjs` / `.cjs` / `.js`) **or TypeScript** (`.ts` / `.mts` / `.cts`) — a TS
+ * script is run through `tsx` when installed, else Node's built-in type
+ * stripping (Node >= 22.6). The scripts import from the built `dist/`, so they
+ * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
+ */
+import { type TestTier } from "../../source-kinds.js";
 import { type SurfaceProbe } from "../../check-count.js";
 /**
  * The outcome of running one script.
@@ -102,10 +115,13 @@ export declare function statusFor(code: number, checks: number | undefined, load
  * retracting silently with no type error.
  */
 export declare function loadFailed(r: ScriptRunResult): boolean;
-/** Filename extensions accepted for harness/eval scripts (JS and TS). */
+/**
+ * Filename extensions accepted for harness/eval scripts (JS and TS). The table
+ * lives in `source-kinds.ts`; this re-export keeps the runner's name for it.
+ */
 export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
-/** Glob suffix matching every accepted script extension, e.g. `harness`. */
-export declare function scriptGlob(kind: "harness" | "eval"): string;
+/** The glob that discovers one tier's scripts, derived from the same table as everything else that names a test. */
+export declare function scriptGlob(kind: TestTier): string;
 export { detectNodeCaps, canRunTypeScript, type NodeCaps, } from "../../ts-runner-caps.js";
 import type { NodeCaps } from "../../ts-runner-caps.js";
 import { type GlobIgnore } from "../../core/glob-ignore.js";

package/dist/adapters/claude-code/run-scripts.js

@@ -22,6 +22,7 @@ exports.formatScriptSummary = formatScriptSummary;
  * stripping (Node >= 22.6). The scripts import from the built `dist/`, so they
  * also run standalone — the CLI just discovers, runs, and aggregates exit codes.
  */
+const source_kinds_js_1 = require("../../source-kinds.js");
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -103,11 +104,14 @@ function statusFor(code, checks, load) {
 function loadFailed(r) {
     return r.status === "skip" && r.code !== exports.SKIP_EXIT_CODE;
 }
-/** Filename extensions accepted for harness/eval scripts (JS and TS). */
-exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
-/** Glob suffix matching every accepted script extension, e.g. `harness`. */
+/**
+ * Filename extensions accepted for harness/eval scripts (JS and TS). The table
+ * lives in `source-kinds.ts`; this re-export keeps the runner's name for it.
+ */
+exports.SCRIPT_EXTS = source_kinds_js_1.RUNNABLE_EXTS;
+/** The glob that discovers one tier's scripts, derived from the same table as everything else that names a test. */
 function scriptGlob(kind) {
-    return `**/*.${kind}.{${exports.SCRIPT_EXTS.join(",")}}`;
+    return (0, source_kinds_js_1.testGlob)(kind);
 }
 const TS_EXT = /\.(?:m|c)?ts$/;
 // The capability probe lives in `src/ts-runner-caps.ts` so the SUGGESTER
@@ -194,6 +198,10 @@ function discoverScripts(patterns, defaultGlob, cwd, ignore) {
             ignore: (0, glob_ignore_js_1.withIgnored)([], ignore),
             dot: true,
             nodir: true,
+            // `glob` defaults this to TRUE on macOS and Windows, which made
+            // `a.hook.HARNESS.mjs` a test there and nothing on Linux. The kind of a
+            // name is decided case-sensitively (`source-kinds.ts`); the glob agrees.
+            nocase: false,
         })) {
             found.add(m);
         }

package/dist/cli-main.js

@@ -69,6 +69,7 @@ const action_gate_js_1 = require("./action-gate.js");
 const guards_js_1 = require("./core/guards.js");
 const hook_program_js_1 = require("./core/hook-program.js");
 const hook_install_js_1 = require("./hook-install.js");
+const hook_check_install_js_1 = require("./hook-check-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
 // The named-state STORE. Lifted out of this file so a TEST can seed a fact
@@ -5980,7 +5981,16 @@ async function refsHookCommand() {
  */
 async function compileProviders() {
     const names = [];
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+    const { claimed, unclaimed } = (0, hook_install_js_1.discoverProviderFiles)(process.cwd());
+    // A provider that lost (or never had) its marker is not silently skipped: a
+    // hook's `provider()` ref to it would then fail to resolve with a message
+    // about the REF, far from the cause.
+    if (unclaimed.length > 0) {
+        // Every one gets the ✗ (the catch adds the first): the others used to read
+        // as a continuation of the first message.
+        throw new hook_program_js_1.HookCompileError(unclaimed.map((f) => (0, hook_install_js_1.unclaimedReport)(f, "provider")).join("\n✗ "));
+    }
+    for (const file of claimed) {
         const def = await (0, hook_runtime_js_1.loadProvider)(file);
         if ((0, hook_providers_js_1.unsafeProvider)(def)) {
             throw new hook_program_js_1.HookCompileError(`provider ${file} ("${def.run}") is not provably read-only — ` +
@@ -6017,12 +6027,11 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // cannot load must block — the repo seized, every command refused including the repair.
         //
         // 🔴 AND LAUNCHED LOCALLY, NOT THROUGH `npx` — 193 ms against 2545 ms on a warm
-        // cache, thirteen times, on every tool call. The trailing `|| exit N` is what the
-        // shell does when that binary cannot start at all, and N is decided by the hook's
-        // ROLE: see `hookRuntimeRef` and `hookRuntimeMissingExit` for both measurements
-        // and for why a gate and a nudge must answer differently.
+        // cache, thirteen times, on every tool call. The `|| exit N` ending is what
+        // the shell does when that file cannot start at all. `compileHookProgram`
+        // adds it (see `hookRuntimeMissingExit`), so it is not written here.
         gateCommand: `${(0, hook_install_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens)} hook-runtime run-program ` +
-            `${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)} || exit ${(0, hook_install_js_1.hookRuntimeMissingExit)((0, hook_program_js_1.dispatchKind)(program))}`,
+            (0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens),
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settings: adapter.layout.settings,
@@ -6117,8 +6126,8 @@ async function installHookFile(file, adapter, registeredProviders = []) {
  * resolved from the `--harness=` flag, else `.vigilesrc.json#harnesses`, else auto-detect.
  * Returns false if any hook failed to compile for any harness.
  */
-async function installHooks(hookFiles, harnessFlag, configHarness) {
-    if (hookFiles.length === 0)
+async function installHooks(hookFiles, harnessFlag, configHarness, validateProvidersAnyway = false) {
+    if (hookFiles.length === 0 && !validateProvidersAnyway)
         return true;
     const adapters = (0, adapter_registry_js_1.resolveHarnessAdapters)({
         root: process.cwd(),
@@ -6138,6 +6147,8 @@ async function installHooks(hookFiles, harnessFlag, configHarness) {
         }
         throw e;
     }
+    if (hookFiles.length === 0)
+        return true; // providers validated; nothing to wire
     let ok = true;
     for (const file of hookFiles) {
         try {
@@ -6171,6 +6182,7 @@ async function installHooks(hookFiles, harnessFlag, configHarness) {
             }
         }
     }
+    (0, hook_check_install_js_1.installHookCheck)(adapters);
     return ok;
 }
 /**
@@ -6644,15 +6656,40 @@ async function main() {
                     .filter((f) => f.endsWith(".spec.ts"))
                     .map((f) => noteExplicitOverride(excludes, f, "compiling"))
                 : findSpecs(excludes);
-            const hooks = restArgs.length > 0
-                ? restArgs.filter((f) => !f.endsWith(".spec.ts"))
-                : (0, hook_install_js_1.discoverHookFiles)(process.cwd());
-            if (specs.length === 0 && hooks.length === 0) {
+            // WHAT A HOOK IS is decided once, in `source-kinds.ts`: a bare `compile`
+            // and `compile <file>` ask the same classifier, so they cannot disagree.
+            // Only `.hook.` files are compiled; a runnable file that carries no marker
+            // is refused below, out loud, with the command that fixes it.
+            const found = restArgs.length > 0
+                ? (0, hook_install_js_1.partitionHookArgs)(restArgs.filter((f) => !f.endsWith(".spec.ts")))
+                : (0, hook_install_js_1.discoveredHookArgs)(process.cwd());
+            const hooks = [...found.hooks];
+            const unclaimed = found.unclaimed;
+            if (specs.length === 0 &&
+                hooks.length === 0 &&
+                unclaimed.length === 0 &&
+                found.skipped.length === 0 &&
+                found.invalid.length === 0) {
                 console.log("No .spec.ts or .vigiles/hooks/ hook files found.");
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
             let valid = true;
+            // Refused files FIRST and on stderr: they are the news in this run, and a
+            // line that scrolled past under forty `✓` lines is a silent skip with
+            // extra steps. Compiling the rest still proceeds — one stray file must
+            // not stop the hooks that are fine.
+            for (const f of unclaimed) {
+                console.error(`✗ ${(0, hook_install_js_1.unclaimedReport)(f, "hook")}`);
+                valid = false;
+            }
+            for (const bad of found.invalid) {
+                console.error(`✗ ${(0, hook_install_js_1.invalidArgMessage)(bad.path, bad.reason)}`);
+                valid = false;
+            }
+            for (const s of found.skipped) {
+                console.log(`- ${s.path} skipped: a ${s.kind}, not a hook.`);
+            }
             if (specs.length > 0)
                 valid =
                     (await compile(specs, config, excludes, { harnessFlag })) && valid;
@@ -6669,13 +6706,21 @@ async function main() {
                     console.log(`\n${weightLine}`);
             }
             valid =
-                (await installHooks(hooks, harnessFlag, (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses))) && valid;
+                (await installHooks(hooks, harnessFlag, (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses), 
+                // A hook-side compile is under way even when every hook was refused:
+                // validate the providers too, so ONE run shows every problem.
+                unclaimed.length > 0)) && valid;
             // Keep an existing whole-harness registry in sync (cheap, opt-in) so the
             // user never hand-runs `generate-harness`. Skipped when no harness.gen.ts.
             if (specs.length > 0)
                 valid = (await refreshHarnessGenIfPresent(harnessFlag)) && valid;
             console.log("");
-            if (valid) {
+            if (valid && specs.length === 0 && hooks.length === 0) {
+                // Skipped paths are not errors, but a run that compiled nothing must not
+                // read like one that did.
+                console.log("Nothing was compiled: every path given was skipped.");
+            }
+            else if (valid) {
                 console.log("Compilation complete.");
             }
             else {

package/dist/core/hook-program.d.ts

@@ -408,7 +408,11 @@ export interface CompiledHookProgram {
  * core depends only on these interfaces, never an adapter (core ⊄ adapter).
  */
 export interface CompileHookOptions {
-    /** The command the emitted block routes the event to. */
+    /**
+     * The command the emitted block runs. The compiler adds `|| exit 2` (a hook
+     * that can block) or `|| exit 0` (a reminder-only hook) at the end; one that is
+     * already there is replaced.
+     */
     readonly gateCommand?: string;
     /** Validate `hook.on` against this harness's hook-event catalog (a typo won't compile). */
     readonly dialect?: HarnessDialect;
@@ -451,6 +455,45 @@ export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | Pro
  */
 export type DispatchKind = "bash-gate" | "file-gate" | "prompt-gate" | "stop-gate" | "inject" | "react";
 export declare function dispatchKind(hook: AnyHook): DispatchKind;
+/**
+ * What the shell should do when a hook's command fails before the hook gives an
+ * answer: the runtime is not installed, or it starts but cannot load the hook.
+ * No hook code ran, so the hook cannot be asked. The answer has to be written
+ * into the command itself, and this function is the one place that decides it.
+ *
+ * There are two kinds of hook and they need different answers:
+ *
+ * - A gate (it can block a tool call) must exit 2. A gate that cannot run must
+ *   not let calls through: a protection that silently stops working is worse
+ *   than one that is known to be missing.
+ * - A nudge (it only adds a reminder: an inject or a react) must exit 0. If it
+ *   blocked, one missing file could stop the whole session. This happened on
+ *   2026-08-10: merge-conflict markers in `package.json` stopped every hook from
+ *   loading, the Bash gate then refused `git merge --abort` (the command that
+ *   undoes the damage), and the session could not be repaired from inside.
+ *
+ * The kind is fixed by the type the author picked: a react hook has no `deny`,
+ * and an inject hook only returns text.
+ *
+ * Only this function decides. The runtime used to guess a second time, from the
+ * hook's file name ("inject" in the name meant nudge), and the two guesses
+ * disagreed (#312). Now the runtime always exits 2 when a hook cannot load, and
+ * the `|| exit N` ending (see {@link withRoleExit}) is the only thing that turns
+ * that 2 into a 0. It is shell, so a different runtime version cannot change it.
+ *
+ * This does not rescue a gate that cannot load: it still refuses every command,
+ * including the install that would fix it. It only stops a nudge doing the same.
+ *
+ * (Other tools disagree on this too: husky and lefthook skip, pre-commit fails.)
+ */
+export declare function hookRuntimeMissingExit(kind: DispatchKind): 0 | 2;
+/**
+ * `command` with `|| exit 0` or `|| exit 2` (chosen by the kind of hook) as its
+ * last words. A `|| exit N` already there is replaced, not added to: the shell
+ * stops at the first `exit` it reaches, so a nudge wired `|| exit 2 || exit 0`
+ * would still block. Applying it twice gives the same result as applying it once.
+ */
+export declare function withRoleExit(command: string, kind: DispatchKind): string;
 /** A gate's {@link HookMode} (`enforce` default); non-gate roles report `enforce` too. */
 export declare function hookMode(hook: AnyHook): HookMode;
 /** The context providers a hook declared via `needs` ([] if none / not a gate). */
@@ -1109,6 +1152,29 @@ export declare function isStampRepairEvent(event: RawHookEvent, hookFile: string
  * loads, the gate decides normally and `git merge --abort` is an ordinary allowed
  * command — through the gate, not around it.
  *
+ * ## Why running an install is not allowed either (#312, considered and rejected)
+ *
+ * The usual reason a hook cannot load is that nothing is installed yet (a fresh
+ * container, or a merge that brought the wiring but not the package). The cure
+ * is `npm ci`, which is exactly what the gate refuses. Letting a lockfile
+ * install through was proposed and rejected, for four reasons:
+ *
+ * - Like `git merge --abort` and `vigiles compile` above, it would be allowed for
+ *   what it is meant to do, not for what it can do. An install runs the
+ *   lifecycle scripts of every package in the lockfile, which is more than the
+ *   `.git/hooks/*` scripts that got the git commands removed.
+ * - "The gate is not running anyway" would equally justify allowing `ls`. It
+ *   does not single out `npm ci`.
+ * - On a fresh container the runtime itself is missing, so none of this code
+ *   runs; the command's own `|| exit 2` decides.
+ * - `npm ci` fails when the lockfile is behind `package.json`. Fixing that needs
+ *   plain `npm install`, which fetches versions the repo has not pinned.
+ *
+ * So the way out stays a file write. What is left over is described in
+ * `docs/compiled-hooks.md` ("When a hook cannot load"). Removing the cause would
+ * need hook files that live in the same git commit as their wiring; that is a
+ * separate decision (#312).
+ *
  * ## What is accepted
  *
  * A write to the hook's own source, its stamp sidecar, or one of

package/dist/core/hook-program.js

@@ -12,6 +12,8 @@ exports.decideProgram = decideProgram;
 exports.decisionExitCode = decisionExitCode;
 exports.checkHookImports = checkHookImports;
 exports.dispatchKind = dispatchKind;
+exports.hookRuntimeMissingExit = hookRuntimeMissingExit;
+exports.withRoleExit = withRoleExit;
 exports.hookMode = hookMode;
 exports.hookNeeds = hookNeeds;
 exports.hookRouting = hookRouting;
@@ -513,7 +515,7 @@ function commandView(raw, root) {
             // uses, and for the same reason. This matcher read only `leaves` (raw), so
             // three ordinary rewrites walked past a guard that blocks the plain form.
             // MEASURED 2026-09-02 on the shipped dogfood artifact behind the public
-            // 7/7 claim (`examples/harness/safe-bash-guard.mjs`):
+            // 7/7 claim (`examples/harness/safe-bash-guard.hook.mjs`):
             //   git push --force origin main            exit 2  blocked
             //   git push "--force" origin main          exit 0  ALLOWED
             //   sudo git push --force origin main       exit 0  ALLOWED
@@ -686,6 +688,51 @@ function dispatchKind(hook) {
         return hook.role === "gate" ? "file-gate" : hook.role;
     return "bash-gate";
 }
+/**
+ * What the shell should do when a hook's command fails before the hook gives an
+ * answer: the runtime is not installed, or it starts but cannot load the hook.
+ * No hook code ran, so the hook cannot be asked. The answer has to be written
+ * into the command itself, and this function is the one place that decides it.
+ *
+ * There are two kinds of hook and they need different answers:
+ *
+ * - A gate (it can block a tool call) must exit 2. A gate that cannot run must
+ *   not let calls through: a protection that silently stops working is worse
+ *   than one that is known to be missing.
+ * - A nudge (it only adds a reminder: an inject or a react) must exit 0. If it
+ *   blocked, one missing file could stop the whole session. This happened on
+ *   2026-08-10: merge-conflict markers in `package.json` stopped every hook from
+ *   loading, the Bash gate then refused `git merge --abort` (the command that
+ *   undoes the damage), and the session could not be repaired from inside.
+ *
+ * The kind is fixed by the type the author picked: a react hook has no `deny`,
+ * and an inject hook only returns text.
+ *
+ * Only this function decides. The runtime used to guess a second time, from the
+ * hook's file name ("inject" in the name meant nudge), and the two guesses
+ * disagreed (#312). Now the runtime always exits 2 when a hook cannot load, and
+ * the `|| exit N` ending (see {@link withRoleExit}) is the only thing that turns
+ * that 2 into a 0. It is shell, so a different runtime version cannot change it.
+ *
+ * This does not rescue a gate that cannot load: it still refuses every command,
+ * including the install that would fix it. It only stops a nudge doing the same.
+ *
+ * (Other tools disagree on this too: husky and lefthook skip, pre-commit fails.)
+ */
+function hookRuntimeMissingExit(kind) {
+    return kind === "inject" || kind === "react" ? 0 : 2;
+}
+/** A trailing `|| exit <number>`, the only ending this module writes. */
+const ROLE_EXIT_SUFFIX = /\s*\|\|\s*exit\s+\d+\s*$/;
+/**
+ * `command` with `|| exit 0` or `|| exit 2` (chosen by the kind of hook) as its
+ * last words. A `|| exit N` already there is replaced, not added to: the shell
+ * stops at the first `exit` it reaches, so a nudge wired `|| exit 2 || exit 0`
+ * would still block. Applying it twice gives the same result as applying it once.
+ */
+function withRoleExit(command, kind) {
+    return `${command.replace(ROLE_EXIT_SUFFIX, "")} || exit ${hookRuntimeMissingExit(kind)}`;
+}
 /** A gate's {@link HookMode} (`enforce` default); non-gate roles report `enforce` too. */
 function hookMode(hook) {
     return "mode" in hook && hook.mode ? hook.mode : "enforce";
@@ -942,7 +989,9 @@ function compileHookProgram(source, hook, opts = {}) {
             .map((u) => `${u.name} ("${u.run}")`)
             .join(", ")} — use dangerously(name, cmd) to acknowledge a side-effecting/undecidable command, or keep provide() only for a read-only one.`);
     }
-    const gateCommand = opts.gateCommand ?? "npx vigiles hook-runtime run-program";
+    // The `|| exit N` ending is added here, not by the caller, so every caller gets
+    // the right one and none can forget it (#312).
+    const gateCommand = withRoleExit(opts.gateCommand ?? "npx vigiles hook-runtime run-program", dispatchKind(hook));
     const matcher = styleMatcher(rawMatcher, opts.hookProtocol);
     const entry = matcher === undefined
         ? { hooks: [{ type: "command", command: gateCommand }] }
@@ -1759,6 +1808,29 @@ function isStampRepairEvent(event, hookFile, repoRoot) {
  * loads, the gate decides normally and `git merge --abort` is an ordinary allowed
  * command — through the gate, not around it.
  *
+ * ## Why running an install is not allowed either (#312, considered and rejected)
+ *
+ * The usual reason a hook cannot load is that nothing is installed yet (a fresh
+ * container, or a merge that brought the wiring but not the package). The cure
+ * is `npm ci`, which is exactly what the gate refuses. Letting a lockfile
+ * install through was proposed and rejected, for four reasons:
+ *
+ * - Like `git merge --abort` and `vigiles compile` above, it would be allowed for
+ *   what it is meant to do, not for what it can do. An install runs the
+ *   lifecycle scripts of every package in the lockfile, which is more than the
+ *   `.git/hooks/*` scripts that got the git commands removed.
+ * - "The gate is not running anyway" would equally justify allowing `ls`. It
+ *   does not single out `npm ci`.
+ * - On a fresh container the runtime itself is missing, so none of this code
+ *   runs; the command's own `|| exit 2` decides.
+ * - `npm ci` fails when the lockfile is behind `package.json`. Fixing that needs
+ *   plain `npm install`, which fetches versions the repo has not pinned.
+ *
+ * So the way out stays a file write. What is left over is described in
+ * `docs/compiled-hooks.md` ("When a hook cannot load"). Removing the cause would
+ * need hook files that live in the same git commit as their wiring; that is a
+ * separate decision (#312).
+ *
  * ## What is accepted
  *
  * A write to the hook's own source, its stamp sidecar, or one of

package/dist/core/hook-providers.d.ts

@@ -54,7 +54,7 @@ export declare const provide: <const Name extends string>(name: Name, run: strin
 export declare const dangerously: <const Name extends string>(name: Name, run: string) => InlineProvider<Name>;
 /**
  * A REGISTERED provider — a reusable, named fact authored once in
- * `.vigiles/providers/<name>.{mjs,ts}` (default-exported via {@link defineProvider})
+ * `.vigiles/providers/<name>.provider.{mjs,ts}` (default-exported via {@link defineProvider})
  * and referenced from many hooks by {@link provider} name. The reusable sibling of
  * the one-off inline {@link provide}; same read-only-by-default rule.
  */

package/dist/coverage-evidence.d.ts

@@ -64,9 +64,7 @@ export interface PreparedTest {
 export declare function isColocatedTest(surface: Pick<CoverableSurface, "name" | "path">, testPath: string): boolean;
 /** Wrap a discovered path. Kept as a function so both twins share one shape. */
 export declare function prepareTest(path: string): PreparedTest;
-/** @param filename a BASENAME — callers strip the directory with their own path
- * helper (`node:path` on disk, `posix-path` in the browser twin). */
-export declare function isEvalScript(filename: string): boolean;
+export { isEvalScript } from "./source-kinds.js";
 /**
  * The root variables a hook command may be written against — the structural
  * slice of `PluginLayout` this needs, taken by SHAPE so the browser twin does

package/dist/coverage-evidence.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SURFACE_TOKEN = void 0;
+exports.SURFACE_TOKEN = exports.isEvalScript = void 0;
 exports.strongerEvidence = strongerEvidence;
 exports.isColocatedTest = isColocatedTest;
 exports.prepareTest = prepareTest;
-exports.isEvalScript = isEvalScript;
 exports.hookScriptRefs = hookScriptRefs;
 exports.evidenceFor = evidenceFor;
 exports.hasSurfaceToken = hasSurfaceToken;
@@ -185,39 +184,12 @@ function prepareTest(path) {
  * mode here is under-counting, not accusation.
  */
 const SCRIPT_RE = (0, source_refs_js_1.scriptRefPattern)();
-/**
- * Is this filename one the PAID real-model runner would actually run?
- *
- * The tier split decides which of two runners owns a test file, and it is the
- * only thing standing between a scheduled paid run and a per-push one. It has
- * now been wrong in both directions:
- *
- * - As the full suffix `.eval.mjs` it was a MONEY HAZARD — `foo.eval.ts` fell
- *   into the free branch and would have spent real model calls on every push.
- * - As the bare INFIX `.eval.` it made a FALSE GRANT — `parser.eval.test.ts`,
- *   an ordinary deterministic test discovered by an `include` of
- *   `**\/*.test.ts`, was credited to the paid tier and dropped from the free
- *   one. `vigiles eval` globs `**\/*.eval.{mjs,cjs,js,mts,cts,ts}`, so that name
- *   is not discoverable by the eval runner at all: the surface was reported
- *   covered by the tier that cannot run it, and uncovered by the tier that does.
- *
- * The rule that is wrong in neither direction is the one the runner itself uses:
- * `.eval.` followed by a runnable extension AT THE END of the name. Anything
- * else — including a name that merely contains `.eval.` — is deterministic, or
- * is not a script at all.
- *
- * ⚠️ The extension list is RE-DECLARED, not imported: the authority is
- * `SCRIPT_EXTS` in adapters/claude-code/run-scripts.ts, which pulls in
- * `node:child_process` and `glob` and so cannot be imported by this
- * browser-safe module. A test in test-coverage.test.ts asserts the two agree,
- * so an extension added to the runner cannot silently fail to be billed here.
- */
-const EVAL_SCRIPT_RE = /\.eval\.(?:mjs|cjs|js|mts|cts|ts)$/;
-/** @param filename a BASENAME — callers strip the directory with their own path
- * helper (`node:path` on disk, `posix-path` in the browser twin). */
-function isEvalScript(filename) {
-    return EVAL_SCRIPT_RE.test(filename);
-}
+// Which runner owns a test file — the paid real-model one or the free one — is
+// answered by the shared source-kind table (`source-kinds.ts`), which this
+// browser-safe module can import because it imports nothing. See `isEvalScript`
+// there for the two ways this question has been answered wrongly before.
+var source_kinds_js_1 = require("./source-kinds.js");
+Object.defineProperty(exports, "isEvalScript", { enumerable: true, get: function () { return source_kinds_js_1.isEvalScript; } });
 /**
  * The hook-script paths a manifest's `hooks` block names, repo-relative.
  *

package/dist/coverage-probe.d.ts

@@ -106,6 +106,21 @@ import { type SurfaceProbe } from "./check-count.js";
  * runner resolves refs against real discovered surfaces or drops them.
  */
 export declare function commandRefs(command: string, env?: Record<string, string>): string[];
+/**
+ * The files that a `hook-runtime run-program` command needs to exist: the hook
+ * file it names, and the runtime script when the command starts it by path
+ * (`node "$DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program …`).
+ *
+ * Narrower than {@link commandRefs}, which lists every program a command runs.
+ * This lists only what a compiled hook depends on, because the start-of-session
+ * check (`hook-check.ts`) reports these files as missing. `bash scripts/build.sh`
+ * is not one of them; reporting it missing in a fresh clone would be a false
+ * alarm that `npm install` does not fix.
+ *
+ * Like `commandRefs`, it only counts a command that really starts vigiles, so
+ * `echo vigiles hook-runtime run-program x.mjs` names nothing.
+ */
+export declare function runProgramFiles(command: string): string[];
 /** The transcript shape this module reads — structural, so it imports no tier. */
 export interface ProbeableTrace {
     readonly toolCalls: readonly {

package/dist/coverage-probe.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commandRefs = commandRefs;
+exports.runProgramFiles = runProgramFiles;
 exports.traceRefs = traceRefs;
 exports.probeCommand = probeCommand;
 exports.probeTrace = probeTrace;
@@ -586,6 +587,34 @@ function commandRefs(command, env) {
     }
     return [...out];
 }
+/**
+ * The files that a `hook-runtime run-program` command needs to exist: the hook
+ * file it names, and the runtime script when the command starts it by path
+ * (`node "$DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program …`).
+ *
+ * Narrower than {@link commandRefs}, which lists every program a command runs.
+ * This lists only what a compiled hook depends on, because the start-of-session
+ * check (`hook-check.ts`) reports these files as missing. `bash scripts/build.sh`
+ * is not one of them; reporting it missing in a fresh clone would be a false
+ * alarm that `npm install` does not fix.
+ *
+ * Like `commandRefs`, it only counts a command that really starts vigiles, so
+ * `echo vigiles hook-runtime run-program x.mjs` names nothing.
+ */
+function runProgramFiles(command) {
+    const out = new Set();
+    for (const argv of (0, bash_effects_js_1.leafArgvSource)(command)) {
+        const head = argv[0] ?? "";
+        const entry = SCRIPT_RE.test(head) ? head : interpretedScript(argv);
+        const hook = runProgramRef(argv, entry);
+        if (hook === undefined)
+            continue;
+        if (entry !== undefined)
+            out.add(entry);
+        out.add(hook);
+    }
+    return [...out];
+}
 /**
  * The tools that DISPATCH a subagent. Both spellings, because the live CLI names
  * it `Agent` and older docs name it `Task` — the same pair `parseSubagents`

package/dist/eval-define.js

@@ -60,6 +60,7 @@ exports.defineEval = defineEval;
  * never executes, so it is untouched.
  */
 const node_path_1 = require("node:path");
+const source_kinds_js_1 = require("./source-kinds.js");
 /**
  * Brand marking a value as built by {@link defineEval}. A registered symbol, so
  * a descriptor still reads as one across two copies of the package on disk —
@@ -128,8 +129,6 @@ function moduleDefault(mod) {
     const inner = outer?.default;
     return isEvalDefinition(inner) ? inner : outer;
 }
-/** Filenames vigiles runs as evals — the runner's own glob, as a pattern. */
-const EVAL_FILE = /\.eval\.(?:m|c)?[jt]s$/;
 /**
  * Was node pointed STRAIGHT at an eval file? `argv1` is `process.argv[1]`: the
  * path node was started with, which no stray configuration can forge.
@@ -142,7 +141,8 @@ const EVAL_FILE = /\.eval\.(?:m|c)?[jt]s$/;
  * Pure: a fact in, a boolean out.
  */
 function ranAsEntry(argv1) {
-    return argv1 !== undefined && EVAL_FILE.test(argv1.replaceAll("\\", "/"));
+    return (argv1 !== undefined &&
+        (0, source_kinds_js_1.isEvalScript)(argv1.replaceAll("\\", "/").split("/").pop() ?? ""));
 }
 /** The words shown when someone runs an eval file directly. Asserted by a test:
  *  a refusal that stops a run without saying what to do instead is a ticket. */

package/dist/eval-lock.js

@@ -58,6 +58,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./core/hash.js");
 const eval_cache_js_1 = require("./eval-cache.js");
+const source_kinds_js_1 = require("./source-kinds.js");
 /**
  * On-disk lock-format version, salted into nothing (the lock is keyed by name,
  * not by hash) but VALIDATED on read so an incompatible shape fails loud rather
@@ -162,7 +163,7 @@ function isEvalInputFile(path) {
     const p = path.replace(/\\/g, "/");
     if (/(^|\/)SKILL\.md$/.test(p))
         return true;
-    return /\.eval\.(mjs|cjs|js|mts|cts|ts)$/.test(p);
+    return (0, source_kinds_js_1.isEvalScript)(p.split("/").pop() ?? "");
 }
 /**
  * The NON-BLOCKING nudge to emit after an eval-input edit when committed locks

package/dist/hook-check-install.d.ts

@@ -0,0 +1,3 @@
+import type { HarnessAdapter } from "./core/adapter.js";
+export declare function installHookCheck(adapters: readonly HarnessAdapter[], cwd?: string): void;
+//# sourceMappingURL=hook-check-install.d.ts.map