vigiles 32.1.1 → 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

@@ -5981,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 — ` +
@@ -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 {
@@ -6645,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;
@@ -6670,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.js

@@ -515,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

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/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-install.d.ts

@@ -1,11 +1,100 @@
+import { type CompilableMarker, type SourceKind } from "./source-kinds.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). */
 export declare const PROVIDERS_DIR = ".vigiles/providers";
-/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
-export declare function discoverHookFiles(cwd: string): string[];
-/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
-export declare function discoverProviderFiles(cwd: string): string[];
+/** What discovery found in one source directory, split by what `compile` owes each part. */
+export interface Discovered {
+    /** Files this directory's role compiles: `.hook.` files in `.vigiles/hooks/`, `.provider.` files in `.vigiles/providers/`. */
+    readonly claimed: readonly string[];
+    /**
+     * Runnable files nothing claims here. `compile` REFUSES these out loud
+     * ({@link unclaimedMessage}); dropping them would make a hook that lost its
+     * marker vanish from the build without a word.
+     */
+    readonly unclaimed: readonly string[];
+}
+/** Discover hook sources under {@link HOOKS_DIR}: `.hook.` files, and the runnable files that are nobody's. */
+export declare function discoverHookFiles(cwd: string): Discovered;
+/** Discover registered-provider sources under {@link PROVIDERS_DIR}. */
+export declare function discoverProviderFiles(cwd: string): Discovered;
+/** Why an explicit `compile` argument is an error rather than a hook, a refusal or a skip. */
+export type InvalidArgReason = "missing" | "directory" | "not-a-source";
+/** What `vigiles compile <files…>` makes of the paths it was handed. */
+export interface HookArgs {
+    readonly hooks: readonly string[];
+    /** Runnable files nothing claims (or a marked file in the wrong directory): refused, with the fix. */
+    readonly unclaimed: readonly string[];
+    /** Named on purpose, not compilable (a test, a stamp…): said out loud, not an error. */
+    readonly skipped: readonly {
+        readonly path: string;
+        readonly kind: SourceKind["kind"];
+    }[];
+    /** Not a file at all, or not a source: an error, the way it always was. */
+    readonly invalid: readonly {
+        readonly path: string;
+        readonly reason: InvalidArgReason;
+    }[];
+}
+/** What the file system says a path is. Injected so the rules below stay pure. */
+export type PathProbe = (path: string) => "file" | "directory" | "missing" | "other";
+/**
+ * Sort explicit `compile` arguments by the same classifier discovery uses, so
+ * `compile guard.mjs` and a bare `compile` give the same answer about it — for a
+ * path ANYWHERE, not just under `.vigiles/hooks/`: `compile .claude/hooks/x.mjs`
+ * or a plugin's `hooks/guard.mjs` is refused unless it carries `.hook.`.
+ *
+ * A path that is missing, a directory or not a regular file is an error (it used
+ * to fail, and the first version of the marker rule turned it into a green run).
+ * The one lenient case exists for a shell glob (`compile .vigiles/hooks/*`): a
+ * test, declaration or stamp is reported as skipped, and so is a README or
+ * `.gitkeep` — but only inside the two vigiles source directories, where a glob
+ * would sweep one up. A `/etc/passwd` is not a README.
+ */
+export declare function partitionHookArgs(args: readonly string[], probe?: PathProbe): HookArgs;
+/** The line `compile` prints for an argument it cannot treat as a hook source at all. */
+export declare function invalidArgMessage(path: string, reason: InvalidArgReason): string;
+/**
+ * Discovery, shaped like {@link partitionHookArgs}'s answer, so `compile` handles
+ * "no arguments" and "these paths" through one code path afterwards.
+ */
+export declare function discoveredHookArgs(cwd: string): HookArgs;
+/**
+ * The ONE shell command that renames an unclaimed file to its marked name and
+ * (for a hook) recompiles it. Every path is single-quoted: this is printed by a
+ * tool and pasted by a person, and a repository can plant a file name that is a
+ * command.
+ *
+ * 🔴 THE HOOK COMMAND COPIES FIRST AND DELETES LAST, and that order is the
+ * point. Already-wired hooks keep running after an upgrade: the runtime loads
+ * whatever path `settings.json` names, and never asks what a file is called. So
+ * the break is the NEXT compile, and a plain `mv` + `compile` has one bad
+ * moment — the old path is gone and the wiring still names it. For a gate
+ * wired `|| exit 2` that is a hook that cannot load, which blocks every Bash
+ * call (the repair is a file write, not a command). Compiling the renamed copy
+ * while the old file still exists, and deleting the old one only after that
+ * compile succeeded, has no such moment: if anything fails the old hook is
+ * still on disk and still wired. `compile` replaces the old wiring itself
+ * ({@link ownedRefs}), so nothing is left naming the deleted path.
+ *
+ * 🔴 `cp -n`, because the marked name may already exist: a plain `cp` replaced
+ * an edited `guard.hook.mjs` with the stale `guard.mjs`, and the weaker hook
+ * became the wired gate. {@link unclaimedMessage} checks first and prints no
+ * command at all in that case; `-n` is for the file that appears in between.
+ */
+export declare function renameCommand(path: string, role: CompilableMarker): string;
+/**
+ * {@link unclaimedMessage} with the one fact it cannot know, read off the disk:
+ * whether the marked name is already there.
+ */
+export declare function unclaimedReport(path: string, role: CompilableMarker, cwd?: string): string;
+/**
+ * The text `compile` prints for one file it will not compile, with the exact
+ * command to fix it. `targetExists` is whether the marked name is already on
+ * disk: then there is nothing safe to copy, and the message says to merge by
+ * hand instead.
+ */
+export declare function unclaimedMessage(path: string, role: CompilableMarker, targetExists?: boolean): string;
 interface CommandHook {
     readonly type: "command";
     readonly command: string;

package/dist/hook-install.js

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
 exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
+exports.partitionHookArgs = partitionHookArgs;
+exports.invalidArgMessage = invalidArgMessage;
+exports.discoveredHookArgs = discoveredHookArgs;
+exports.renameCommand = renameCommand;
+exports.unclaimedReport = unclaimedReport;
+exports.unclaimedMessage = unclaimedMessage;
 exports.normalizeHookRef = normalizeHookRef;
 exports.hookRuntimeRef = hookRuntimeRef;
 exports.hookGateRef = hookGateRef;
@@ -17,7 +23,8 @@ exports.serializeConfig = serializeConfig;
  * The typed hook program is harness-NEUTRAL — it imports `vigiles/hook` and
  * compiles to whatever harness — so its SOURCE lives in the agnostic,
  * committed {@link HOOKS_DIR} (`.vigiles/hooks/`), never in a harness's own
- * `.claude/`. `compile` discovers each hook there, compiles it, and MERGES the
+ * `.claude/`. `compile` discovers each hook there — a hook is a `.hook.` file
+ * and nothing else, decided by `source-kinds.ts` — compiles it, and MERGES the
  * result into the active harness's native config (`.claude/settings.json` JSON
  * / `config.toml` TOML) — so the harness is actually wired, not handed a
  * paste-this block. The merge is idempotent: an entry is keyed by the runtime
@@ -29,6 +36,7 @@ exports.serializeConfig = serializeConfig;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const source_kinds_js_1 = require("./source-kinds.js");
 /**
  * Lazy for the same reason as in `core/hook-program.ts` — and this module is
  * reached from the hook runtime through `hook-state-store.ts` (`normalizeHookRef`),
@@ -40,25 +48,218 @@ const stringifyToml = (value) => require("@iarna/toml").stringify(value);
 exports.HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
 exports.PROVIDERS_DIR = ".vigiles/providers";
-/** A JS/TS hook source file (the `.json` stamp sidecar is never matched). */
-const HOOK_SOURCE_RE = /\.(?:mjs|cjs|js|mts|cts|ts)$/;
-/** List JS/TS source files under `dir` (relative to cwd), stamps excluded. */
-function discoverSources(cwd, dir) {
+/**
+ * The ONE place a directory's role meets {@link SourceKind}. The `switch` is
+ * exhaustive, so a kind added to the table in `source-kinds.ts` is a compile
+ * error here until someone decides what hooks and providers do with it.
+ *
+ * `leave` is for files that are in these directories on purpose and are none of
+ * `compile`'s business: tests, declarations, stamps, a README.
+ */
+function claimOf(role, found) {
+    switch (found.kind) {
+        case "hook":
+        case "provider":
+            // A provider in the hooks directory is as unclaimed as a stray helper:
+            // nothing here would ever load it, and saying so beats a silent miss.
+            return found.kind === role ? "claim" : "refuse";
+        case "unclaimed":
+            return "refuse";
+        case "vigiles-test":
+        case "declaration":
+        case "stamp":
+        case "non-source":
+            return "leave";
+    }
+}
+/** List the files under `dir` (relative to cwd), split by what `role` does with each. */
+function discoverSources(cwd, dir, role) {
     const abs = (0, node_path_1.join)(cwd, dir);
     if (!(0, node_fs_1.existsSync)(abs))
-        return [];
-    return (0, node_fs_1.readdirSync)(abs)
-        .filter((f) => HOOK_SOURCE_RE.test(f) && !f.endsWith(".d.ts"))
+        return { claimed: [], unclaimed: [] };
+    const verdicts = (0, node_fs_1.readdirSync)(abs)
         .sort()
-        .map((f) => (0, node_path_1.join)(dir, f));
+        .map((f) => ({
+        path: (0, node_path_1.join)(dir, f),
+        claim: claimOf(role, (0, source_kinds_js_1.classifySource)(f)),
+    }));
+    const pick = (want) => verdicts.filter((v) => v.claim === want).map((v) => v.path);
+    return { claimed: pick("claim"), unclaimed: pick("refuse") };
 }
-/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
+/** Discover hook sources under {@link HOOKS_DIR}: `.hook.` files, and the runnable files that are nobody's. */
 function discoverHookFiles(cwd) {
-    return discoverSources(cwd, exports.HOOKS_DIR);
+    return discoverSources(cwd, exports.HOOKS_DIR, "hook");
 }
-/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
+/** Discover registered-provider sources under {@link PROVIDERS_DIR}. */
 function discoverProviderFiles(cwd) {
-    return discoverSources(cwd, exports.PROVIDERS_DIR);
+    return discoverSources(cwd, exports.PROVIDERS_DIR, "provider");
+}
+const realProbe = (path) => {
+    const st = (0, node_fs_1.statSync)((0, node_path_1.resolve)(process.cwd(), path), { throwIfNoEntry: false });
+    if (st === undefined)
+        return "missing";
+    return st.isFile() ? "file" : st.isDirectory() ? "directory" : "other";
+};
+/** Is `path` directly inside `dir` (a repo-relative POSIX dir), either separator, any prefix? */
+function insideDir(path, dir) {
+    const parent = (0, source_kinds_js_1.dirName)(path)
+        .replace(/\\/g, "/")
+        .replace(/\/$/, "")
+        .replace(/^\.\//, "");
+    return parent === dir || parent.endsWith(`/${dir}`);
+}
+/**
+ * Sort explicit `compile` arguments by the same classifier discovery uses, so
+ * `compile guard.mjs` and a bare `compile` give the same answer about it — for a
+ * path ANYWHERE, not just under `.vigiles/hooks/`: `compile .claude/hooks/x.mjs`
+ * or a plugin's `hooks/guard.mjs` is refused unless it carries `.hook.`.
+ *
+ * A path that is missing, a directory or not a regular file is an error (it used
+ * to fail, and the first version of the marker rule turned it into a green run).
+ * The one lenient case exists for a shell glob (`compile .vigiles/hooks/*`): a
+ * test, declaration or stamp is reported as skipped, and so is a README or
+ * `.gitkeep` — but only inside the two vigiles source directories, where a glob
+ * would sweep one up. A `/etc/passwd` is not a README.
+ */
+function partitionHookArgs(args, probe = realProbe) {
+    const hooks = [];
+    const unclaimed = [];
+    const skipped = [];
+    const invalid = [];
+    for (const path of args) {
+        const what = probe(path);
+        if (what === "missing" || what === "directory") {
+            invalid.push({ path, reason: what });
+            continue;
+        }
+        if (what === "other") {
+            invalid.push({ path, reason: "not-a-source" });
+            continue;
+        }
+        const found = (0, source_kinds_js_1.classifySource)((0, source_kinds_js_1.baseName)(path));
+        switch (found.kind) {
+            case "hook":
+                hooks.push(path);
+                break;
+            case "unclaimed":
+                unclaimed.push(path);
+                break;
+            case "provider":
+                // Valid, and compile validates providers whenever it compiles a hook —
+                // except in the hooks directory, where nothing would ever load it.
+                if (insideDir(path, exports.HOOKS_DIR))
+                    unclaimed.push(path);
+                else
+                    skipped.push({ path, kind: found.kind });
+                break;
+            case "vigiles-test":
+            case "declaration":
+            case "stamp":
+                skipped.push({ path, kind: found.kind });
+                break;
+            case "non-source":
+                if (insideDir(path, exports.HOOKS_DIR) || insideDir(path, exports.PROVIDERS_DIR))
+                    skipped.push({ path, kind: found.kind });
+                else
+                    invalid.push({ path, reason: "not-a-source" });
+                break;
+        }
+    }
+    return { hooks, unclaimed, skipped, invalid };
+}
+/** The line `compile` prints for an argument it cannot treat as a hook source at all. */
+function invalidArgMessage(path, reason) {
+    switch (reason) {
+        case "missing":
+            return `${path} — no such file.`;
+        case "directory":
+            return `${path} — is a directory. Name hook files, or run \`vigiles compile\` with no arguments to discover them.`;
+        case "not-a-source":
+            return `${path} — not a hook source (a hook is a \`<name>.hook.<ext>\` file).`;
+    }
+}
+/**
+ * Discovery, shaped like {@link partitionHookArgs}'s answer, so `compile` handles
+ * "no arguments" and "these paths" through one code path afterwards.
+ */
+function discoveredHookArgs(cwd) {
+    const { claimed, unclaimed } = discoverHookFiles(cwd);
+    return { hooks: claimed, unclaimed, skipped: [], invalid: [] };
+}
+/** POSIX single-quote one word: safe for any file name, a newline and `$(…)` included. */
+const shq = (word) => `'${word.replace(/'/g, `'\\''`)}'`;
+/**
+ * The ONE shell command that renames an unclaimed file to its marked name and
+ * (for a hook) recompiles it. Every path is single-quoted: this is printed by a
+ * tool and pasted by a person, and a repository can plant a file name that is a
+ * command.
+ *
+ * 🔴 THE HOOK COMMAND COPIES FIRST AND DELETES LAST, and that order is the
+ * point. Already-wired hooks keep running after an upgrade: the runtime loads
+ * whatever path `settings.json` names, and never asks what a file is called. So
+ * the break is the NEXT compile, and a plain `mv` + `compile` has one bad
+ * moment — the old path is gone and the wiring still names it. For a gate
+ * wired `|| exit 2` that is a hook that cannot load, which blocks every Bash
+ * call (the repair is a file write, not a command). Compiling the renamed copy
+ * while the old file still exists, and deleting the old one only after that
+ * compile succeeded, has no such moment: if anything fails the old hook is
+ * still on disk and still wired. `compile` replaces the old wiring itself
+ * ({@link ownedRefs}), so nothing is left naming the deleted path.
+ *
+ * 🔴 `cp -n`, because the marked name may already exist: a plain `cp` replaced
+ * an edited `guard.hook.mjs` with the stale `guard.mjs`, and the weaker hook
+ * became the wired gate. {@link unclaimedMessage} checks first and prints no
+ * command at all in that case; `-n` is for the file that appears in between.
+ */
+function renameCommand(path, role) {
+    const target = (0, source_kinds_js_1.markedName)(path, role);
+    switch (role) {
+        case "hook":
+            return (`cp -n -- ${shq(path)} ${shq(target)} && ` +
+                `npx vigiles compile ${shq(target)} && ` +
+                `rm -f -- ${shq(path)} ${shq(`${exports.HOOKS_DIR}/${(0, node_path_1.basename)(path)}.json`)}`);
+        case "provider":
+            return `mv -n -- ${shq(path)} ${shq(target)}`;
+    }
+}
+/**
+ * {@link unclaimedMessage} with the one fact it cannot know, read off the disk:
+ * whether the marked name is already there.
+ */
+function unclaimedReport(path, role, cwd = process.cwd()) {
+    return unclaimedMessage(path, role, (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, (0, source_kinds_js_1.markedName)(path, role))));
+}
+/**
+ * The text `compile` prints for one file it will not compile, with the exact
+ * command to fix it. `targetExists` is whether the marked name is already on
+ * disk: then there is nothing safe to copy, and the message says to merge by
+ * hand instead.
+ */
+function unclaimedMessage(path, role, targetExists = false) {
+    const dir = (0, source_kinds_js_1.dirName)(path);
+    const target = (0, source_kinds_js_1.markedName)(path, role);
+    const found = (0, source_kinds_js_1.classifySource)((0, source_kinds_js_1.baseName)(path)).kind;
+    const head = `${path} — not compiled: a ${role} source must carry \`.${role}.\` before its extension (${(0, source_kinds_js_1.baseName)(target)}), and this name carries no marker vigiles knows.`;
+    const misplaced = found === "provider" || found === "hook"
+        ? `  It is marked as a ${found}, which belongs in ${found === "hook" ? exports.HOOKS_DIR : exports.PROVIDERS_DIR}/ — move it there.`
+        : undefined;
+    const notIt = `  If it is not a ${role}, move it out of ${dir || "this directory"} — a test belongs in a \`.harness.\` or \`.eval.\` file.`;
+    if (misplaced !== undefined)
+        return [head, misplaced].join("\n");
+    if (targetExists)
+        return [
+            head,
+            `  ${target} already exists beside it, so nothing is printed that could overwrite it. If ${path} is the ${role}, compare the two by hand, keep the content you want in ${target}, delete ${path}${role === "hook" ? ` and its stamp, and run \`npx vigiles compile ${target}\`` : ""}.`,
+            notIt,
+        ].join("\n");
+    return [
+        head,
+        role === "hook"
+            ? `  If it is a hook, rename it. Copy first and delete last, so a failure leaves the old hook in place and wired:`
+            : `  If it is a provider, rename it (providers are found by directory, never wired by path):`,
+        `    ${renameCommand(path, role)}`,
+        notIt,
+    ].join("\n");
 }
 /**
  * The CANONICAL form of a hook-source reference — how the path is written into
@@ -126,7 +327,25 @@ function hookGateRef(ref, projectRootTokens) {
     return token === undefined ? ref : `"${token}/${ref}"`;
 }
 /**
- * True when an entry's command routes through the runtime for `hookPath`.
+ * The wiring references a hook file owns: its own, and — for `x.hook.ts` — the
+ * one an older vigiles wrote when the file was still called `x.ts`.
+ *
+ * 🔴 WITHOUT THE SECOND, RENAMING A HOOK TO CARRY ITS MARKER LEAVES A DEAD ENTRY.
+ * Wiring is keyed by path, so compiling `guard.hook.mjs` appended a new entry and
+ * left the one for `guard.mjs` in `settings.json`, pointing at a file that is
+ * about to be deleted. That entry cannot load; wired as a gate it blocks every
+ * Bash call, the repair included (see {@link unclaimedMessage}). The marker rename
+ * is the one rename vigiles itself asks of every consumer, so it is the one the
+ * merge is told about: the renamed file takes over the old file's wiring.
+ */
+function ownedRefs(hookPath) {
+    const ref = normalizeHookRef(hookPath);
+    const before = (0, source_kinds_js_1.preMarkerName)(ref, "hook");
+    return before === undefined ? [ref] : [ref, before];
+}
+/**
+ * True when an entry's command routes through the runtime for `hookPath`
+ * (or for the name it had before it carried its marker, see {@link ownedRefs}).
  *
  * Compares CANONICALIZED path tokens rather than testing for a raw substring:
  * `./x.hook.ts` and `x.hook.ts` are the same file (so the entry is replaced,
@@ -134,10 +353,10 @@ function hookGateRef(ref, projectRootTokens) {
  * `x.hook.ts` and `my-x.hook.ts` are not (a substring test said they were).
  */
 function managesHook(entry, hookPath) {
-    const ref = normalizeHookRef(hookPath);
+    const refs = ownedRefs(hookPath);
     return entry.hooks.some((h) => h.command.split(/\s+/).some((token) => {
         const bare = bareToken(token);
-        return bare !== "" && normalizeHookRef(bare) === ref;
+        return bare !== "" && refs.includes(normalizeHookRef(bare));
     }));
 }
 /**

package/dist/hook-runtime.d.ts

@@ -44,7 +44,7 @@ import { loadHook } from "./load-hook.js";
  * loads in a test loads identically here (one loader, no drift).
  */
 export declare const loadHookProgram: typeof loadHook;
-/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+/** Load a registered provider (`.vigiles/providers/<name>.provider.<ext>`) → its definition. */
 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, root?: string): string;

package/dist/hook-runtime.js

@@ -75,7 +75,7 @@ function injectableEventsFor(root) {
  * loads in a test loads identically here (one loader, no drift).
  */
 exports.loadHookProgram = load_hook_js_1.loadHook;
-/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+/** Load a registered provider (`.vigiles/providers/<name>.provider.<ext>`) → its definition. */
 async function loadProvider(file, root = process.cwd()) {
     const abs = (0, node_path_1.resolve)(root, file);
     const { pathToFileURL } = require("node:url");
@@ -155,7 +155,13 @@ async function gatherHookContext(program, file, root) {
  */
 async function loadProviderRegistry(root) {
     const registry = {};
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(root)) {
+    // Tolerant on purpose, unlike `compile`: a provider file written before the
+    // `.provider.` marker existed is `unclaimed`, and a hook compiled yesterday
+    // still resolves `provider("x")` against it today. `compile` refuses such a
+    // file out loud; the runtime must not turn that into a silently empty value
+    // for a hook already wired. Tests and declarations are never loaded.
+    const { claimed, unclaimed } = (0, hook_install_js_1.discoverProviderFiles)(root);
+    for (const file of [...claimed, ...unclaimed]) {
         try {
             const def = await loadProvider(file, root);
             registry[def.name] = def;

package/dist/hook-state-store.d.ts

@@ -91,7 +91,7 @@ export interface HookStateHandle {
      * OLD fact, and "old" is not something a test can produce by waiting.
      *
      * ```js
-     * const st = experimental_hookState(".vigiles/hooks/nag.mjs", { cwd });
+     * const st = experimental_hookState(".vigiles/hooks/nag.hook.mjs", { cwd });
      * st.seed("retro.nagged", { ago: "4d" });   // → the hook speaks
      * st.seed("retro.nagged", { ago: "10m" });  // → the hook stays quiet
      * ```

package/dist/hook.js

@@ -143,7 +143,7 @@ Object.defineProperty(exports, "HookStateError", { enumerable: true, get: functi
 // and `pipesToShell()` match over, so a guard written against the closed
 // vocabulary sees the OPERATION rather than the literal tokens.
 //
-// It is exported because `examples/harness/safe-bash-guard-v2.mjs` needs it —
+// It is exported because `examples/harness/safe-bash-guard-v2.hook.mjs` needs it —
 // and that need is the finding, not the feature. v2 is an UNRUN experiment (no
 // test executes it) covering three things the vocabulary cannot yet express: a
 // flag with a value (`--index-url`), an env-assignment prefix, and a

package/dist/load-hook.d.ts

@@ -10,7 +10,7 @@ import { type AnyHook } from "./core/hook-program.js";
  * ```js
  * import { loadHook, assertHookDenies } from "vigiles";
  *
- * const guard = await loadHook(".vigiles/hooks/guard.mjs");
+ * const guard = await loadHook(".vigiles/hooks/guard.hook.mjs");
  * assertHookDenies(guard, {
  *   tool_name: "Bash",
  *   tool_input: { command: "git push --force" },

package/dist/load-hook.js

@@ -29,7 +29,7 @@ const hook_program_js_1 = require("./core/hook-program.js");
  * ```js
  * import { loadHook, assertHookDenies } from "vigiles";
  *
- * const guard = await loadHook(".vigiles/hooks/guard.mjs");
+ * const guard = await loadHook(".vigiles/hooks/guard.hook.mjs");
  * assertHookDenies(guard, {
  *   tool_name: "Bash",
  *   tool_input: { command: "git push --force" },

package/dist/source-kinds.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What a file in a vigiles-owned source directory IS — decided in ONE place.
+ *
+ * `.vigiles/hooks/` and `.vigiles/providers/` hold several kinds of file side by
+ * side: the programs `vigiles compile` turns into wiring, the tests that exercise
+ * them, type declarations, and the `.json` stamp `compile` writes next to each
+ * hook. Discovery used to ask "does it end in a runnable extension?" and treat
+ * every yes as a hook (#278): a `task-list-nudge.harness.mjs` beside its
+ * `task-list-nudge.hook.ts` was compiled as a hook and failed the build. The
+ * obvious patch — subtract the names that bit (`.harness.`, `.test.`) — is a list
+ * of what a hook is NOT, and a list of that kind is open: the next helper file
+ * somebody colocates is the next report.
+ *
+ * So a hook is defined by what it IS. A file's kind comes from ONE marker, the
+ * LAST dot-separated segment before the extension (`guard.hook.mjs` → `hook`),
+ * looked up in ONE table ({@link MARKERS}). Because exactly one segment decides,
+ * a name has exactly one kind; because the table is closed, every consumer can
+ * `switch` over {@link SourceKind} exhaustively and the compiler names the next
+ * one that forgets a case. A runnable file whose marker is not in the table is
+ * `unclaimed` — a kind of its own, not an absence — so a renamed-away hook is a
+ * reported fact rather than a silent hole.
+ *
+ * The patterns test discovery uses (`vigiles test`, `vigiles eval`, the coverage
+ * defaults, the browser twin) are DERIVED from the same table. They used to be
+ * five hand-kept copies of one fact: `*.harness.*` and `*.eval.*` are tests.
+ *
+ * Pure and import-free on purpose. `hook-install.ts` imports this and is reached
+ * from the hook runtime, where every module is a per-call cost, and the browser
+ * twin of coverage detection needs it too — nothing here may touch `node:*`.
+ */
+/**
+ * Every extension Node executes directly. `.mts`/`.cts` are real (TS 4.7+) and
+ * Node 22 strips their types with no toolchain — measured, not assumed.
+ */
+export declare const RUNNABLE_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/** Which vigiles test runner takes a file: `vigiles test` or `vigiles eval`. */
+export type TestTier = "harness" | "eval";
+/**
+ * The closed union of what a file in a source directory can be. Exactly one per
+ * name; see {@link classifySource}.
+ */
+export type SourceKind = 
+/** A compiled-hook program: `guard.hook.mjs`. */
+{
+    readonly kind: "hook";
+}
+/** A registered context provider: `k8s.provider.mjs`. */
+ | {
+    readonly kind: "provider";
+}
+/** A vigiles test: `guard.harness.mjs` (`vigiles test`) or `guard.eval.mjs` (`vigiles eval`). */
+ | {
+    readonly kind: "vigiles-test";
+    readonly test: TestTier;
+}
+/** A type declaration: `x.d.ts`, `x.d.mts`, `x.d.cts`. */
+ | {
+    readonly kind: "declaration";
+}
+/** The `.json` sidecar `compile` writes beside a source: `guard.hook.mjs.json`. */
+ | {
+    readonly kind: "stamp";
+}
+/** Not a runnable source at all: `README.md`, `.gitkeep`, a stray `.json`. */
+ | {
+    readonly kind: "non-source";
+}
+/**
+ * A runnable file whose name carries no marker vigiles knows: `guard.mjs`
+ * (a hook from before the marker), `util.ts`, `guard.test.ts`. Nobody's — and
+ * therefore never compiled, and never silently ignored either.
+ */
+ | {
+    readonly kind: "unclaimed";
+};
+/** The markers that name a file a vigiles consumer COMPILES (as opposed to runs or ignores). */
+export type CompilableMarker = "hook" | "provider";
+/**
+ * The kind of a file, from its BASENAME. Total: every string has an answer, and
+ * the answer is one member of {@link SourceKind}.
+ *
+ * Order matters and is the whole algorithm: a declaration is a declaration even
+ * when its infix says `hook` (`x.hook.d.ts`); a `.json` beside a source is its
+ * stamp; then the last infix is looked up. Case-sensitive, like the file systems
+ * these names mostly live on.
+ */
+export declare function classifySource(filename: string): SourceKind;
+/**
+ * Is this basename an eval script — the PAID tier, the one that spends real
+ * model calls? It decides which of two runners owns a test file, and has been
+ * wrong in both directions:
+ *
+ * - As the full suffix `.eval.mjs`: `foo.eval.ts` fell into the free branch and
+ *   would have spent real model calls on every push.
+ * - As the bare INFIX `.eval.`: `parser.eval.test.ts`, an ordinary deterministic
+ *   test, was credited to the paid tier and dropped from the free one — though
+ *   `vigiles eval` cannot discover that name at all.
+ *
+ * The answer that is wrong in neither direction is the runner's own: `.eval.`
+ * followed by a runnable extension AT THE END of the name, which is exactly what
+ * the last-infix rule of {@link classifySource} says.
+ *
+ * @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;
+/** Is this basename a vigiles test of either tier? */
+export declare function isVigilesTest(filename: string): boolean;
+/** The glob `vigiles test` / `vigiles eval` discover a tier's scripts with. */
+export declare function testGlob(tier: TestTier): string;
+/** The patterns coverage credits tests with by default — one per tier, from the table. */
+export declare const DEFAULT_TEST_GLOBS: readonly string[];
+/** The last path segment, whichever separator precedes it. */
+export declare const baseName: (path: string) => string;
+/** Everything up to and including the last separator, or "" when there is none. */
+export declare const dirName: (path: string) => string;
+/**
+ * `guard.mjs` → `guard.hook.mjs`: the name a file must carry to be claimed as
+ * `marker`. Keeps the directory. The inverse of {@link preMarkerName}.
+ */
+export declare function markedName(path: string, marker: CompilableMarker): string;
+/**
+ * `guard.hook.mjs` → `guard.mjs`: the name a file carried before the marker
+ * existed, or `undefined` when the name has no such marker. Used to recognise
+ * the wiring an older vigiles wrote for the same file.
+ */
+export declare function preMarkerName(path: string, marker: CompilableMarker): string | undefined;
+//# sourceMappingURL=source-kinds.d.ts.map

package/dist/source-kinds.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * What a file in a vigiles-owned source directory IS — decided in ONE place.
+ *
+ * `.vigiles/hooks/` and `.vigiles/providers/` hold several kinds of file side by
+ * side: the programs `vigiles compile` turns into wiring, the tests that exercise
+ * them, type declarations, and the `.json` stamp `compile` writes next to each
+ * hook. Discovery used to ask "does it end in a runnable extension?" and treat
+ * every yes as a hook (#278): a `task-list-nudge.harness.mjs` beside its
+ * `task-list-nudge.hook.ts` was compiled as a hook and failed the build. The
+ * obvious patch — subtract the names that bit (`.harness.`, `.test.`) — is a list
+ * of what a hook is NOT, and a list of that kind is open: the next helper file
+ * somebody colocates is the next report.
+ *
+ * So a hook is defined by what it IS. A file's kind comes from ONE marker, the
+ * LAST dot-separated segment before the extension (`guard.hook.mjs` → `hook`),
+ * looked up in ONE table ({@link MARKERS}). Because exactly one segment decides,
+ * a name has exactly one kind; because the table is closed, every consumer can
+ * `switch` over {@link SourceKind} exhaustively and the compiler names the next
+ * one that forgets a case. A runnable file whose marker is not in the table is
+ * `unclaimed` — a kind of its own, not an absence — so a renamed-away hook is a
+ * reported fact rather than a silent hole.
+ *
+ * The patterns test discovery uses (`vigiles test`, `vigiles eval`, the coverage
+ * defaults, the browser twin) are DERIVED from the same table. They used to be
+ * five hand-kept copies of one fact: `*.harness.*` and `*.eval.*` are tests.
+ *
+ * Pure and import-free on purpose. `hook-install.ts` imports this and is reached
+ * from the hook runtime, where every module is a per-call cost, and the browser
+ * twin of coverage detection needs it too — nothing here may touch `node:*`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dirName = exports.baseName = exports.DEFAULT_TEST_GLOBS = exports.RUNNABLE_EXTS = void 0;
+exports.classifySource = classifySource;
+exports.isEvalScript = isEvalScript;
+exports.isVigilesTest = isVigilesTest;
+exports.testGlob = testGlob;
+exports.markedName = markedName;
+exports.preMarkerName = preMarkerName;
+/**
+ * Every extension Node executes directly. `.mts`/`.cts` are real (TS 4.7+) and
+ * Node 22 strips their types with no toolchain — measured, not assumed.
+ */
+exports.RUNNABLE_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/**
+ * The marker table: the LAST dot-segment before the extension → its kind.
+ * Adding a kind of file means adding a row here and handling the new
+ * {@link SourceKind} member in each consumer's `switch`.
+ */
+const MARKERS = [
+    { infix: "hook", kind: { kind: "hook" } },
+    { infix: "provider", kind: { kind: "provider" } },
+    { infix: "harness", kind: { kind: "vigiles-test", test: "harness" } },
+    { infix: "eval", kind: { kind: "vigiles-test", test: "eval" } },
+];
+/**
+ * The tiers a vigiles test can belong to, read off {@link MARKERS}. A tier is
+ * also its own infix (`guard.eval.mjs` is tier `eval`): `source-kinds.test.ts`
+ * asserts that for every tier, so a row that broke it fails there.
+ */
+const TEST_TIERS = MARKERS.flatMap((m) => m.kind.kind === "vigiles-test" ? [m.kind.test] : []);
+const EXT_ALT = exports.RUNNABLE_EXTS.join("|");
+const DECLARATION = /\.d\.(?:ts|mts|cts)$/;
+const STAMP = new RegExp(`\\.(?:${EXT_ALT})\\.json$`);
+/**
+ * `<stem>.<infix>.<ext>`, the infix being the LAST segment before the extension.
+ * The stem may be empty (`.harness.mjs`): the runner's glob matches that, so the
+ * classifier must too; {@link classifySource} decides which kinds may go without
+ * one. `[\\s\\S]`, not `.`: `.` stops at a newline, and a name with one in it
+ * used to fall out of every kind and be dropped without a word.
+ */
+const MARKED = new RegExp(`^([\\s\\S]*)\\.([^.]+)\\.(?:${EXT_ALT})$`);
+const RUNNABLE = new RegExp(`^[\\s\\S]+\\.(?:${EXT_ALT})$`);
+const UNCLAIMED = { kind: "unclaimed" };
+/**
+ * The kind of a file, from its BASENAME. Total: every string has an answer, and
+ * the answer is one member of {@link SourceKind}.
+ *
+ * Order matters and is the whole algorithm: a declaration is a declaration even
+ * when its infix says `hook` (`x.hook.d.ts`); a `.json` beside a source is its
+ * stamp; then the last infix is looked up. Case-sensitive, like the file systems
+ * these names mostly live on.
+ */
+function classifySource(filename) {
+    if (DECLARATION.test(filename))
+        return { kind: "declaration" };
+    if (STAMP.test(filename))
+        return { kind: "stamp" };
+    if (!RUNNABLE.test(filename))
+        return { kind: "non-source" };
+    const parts = MARKED.exec(filename);
+    const row = MARKERS.find((m) => m.infix === parts?.[2]);
+    if (row === undefined)
+        return UNCLAIMED;
+    // A test needs no name to be run (`vigiles test` finds `.harness.mjs`); a hook
+    // or a provider must be nameable, so a stemless one is nobody's.
+    return parts?.[1] === "" && row.kind.kind !== "vigiles-test"
+        ? UNCLAIMED
+        : row.kind;
+}
+/**
+ * Is this basename an eval script — the PAID tier, the one that spends real
+ * model calls? It decides which of two runners owns a test file, and has been
+ * wrong in both directions:
+ *
+ * - As the full suffix `.eval.mjs`: `foo.eval.ts` fell into the free branch and
+ *   would have spent real model calls on every push.
+ * - As the bare INFIX `.eval.`: `parser.eval.test.ts`, an ordinary deterministic
+ *   test, was credited to the paid tier and dropped from the free one — though
+ *   `vigiles eval` cannot discover that name at all.
+ *
+ * The answer that is wrong in neither direction is the runner's own: `.eval.`
+ * followed by a runnable extension AT THE END of the name, which is exactly what
+ * the last-infix rule of {@link classifySource} says.
+ *
+ * @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) {
+    const k = classifySource(filename);
+    return k.kind === "vigiles-test" && k.test === "eval";
+}
+/** Is this basename a vigiles test of either tier? */
+function isVigilesTest(filename) {
+    return classifySource(filename).kind === "vigiles-test";
+}
+/** The glob `vigiles test` / `vigiles eval` discover a tier's scripts with. */
+function testGlob(tier) {
+    return `**/*.${tier}.{${exports.RUNNABLE_EXTS.join(",")}}`;
+}
+/** The patterns coverage credits tests with by default — one per tier, from the table. */
+exports.DEFAULT_TEST_GLOBS = TEST_TIERS.map(testGlob);
+/** Split at the last directory separator — either one, so a Windows path works too. */
+const splitDir = (path) => {
+    const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1;
+    return [path.slice(0, cut), path.slice(cut)];
+};
+/** The last path segment, whichever separator precedes it. */
+const baseName = (path) => splitDir(path)[1];
+exports.baseName = baseName;
+/** Everything up to and including the last separator, or "" when there is none. */
+const dirName = (path) => splitDir(path)[0];
+exports.dirName = dirName;
+/**
+ * `guard.mjs` → `guard.hook.mjs`: the name a file must carry to be claimed as
+ * `marker`. Keeps the directory. The inverse of {@link preMarkerName}.
+ */
+function markedName(path, marker) {
+    const [dir, base] = splitDir(path);
+    return dir + base.replace(/\.([^.]+)$/, `.${marker}.$1`);
+}
+/**
+ * `guard.hook.mjs` → `guard.mjs`: the name a file carried before the marker
+ * existed, or `undefined` when the name has no such marker. Used to recognise
+ * the wiring an older vigiles wrote for the same file.
+ */
+function preMarkerName(path, marker) {
+    const [dir, base] = splitDir(path);
+    const m = new RegExp(`^([\\s\\S]+)\\.${marker}\\.(${EXT_ALT})$`).exec(base);
+    return m === null ? undefined : `${dir}${m[1]}.${m[2]}`;
+}
+//# sourceMappingURL=source-kinds.js.map

package/dist/test-coverage-files.js

@@ -34,22 +34,7 @@ exports.findUntestedSurfacesInFiles = findUntestedSurfacesInFiles;
 const posix_path_js_1 = require("./posix-path.js");
 const layout_js_1 = require("./core/layout.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
-// Mirrors src/test-coverage.ts constants. VALUES are re-declared, never imported
-// — test-coverage.ts pulls in node:fs/glob, and this twin must stay browser-safe.
-const DEFAULT_TEST_SUFFIXES = [
-    ".harness.ts",
-    ".harness.mts",
-    ".harness.cts",
-    ".harness.js",
-    ".harness.mjs",
-    ".harness.cjs",
-    ".eval.ts",
-    ".eval.mts",
-    ".eval.cts",
-    ".eval.js",
-    ".eval.mjs",
-    ".eval.cjs",
-];
+const source_kinds_js_1 = require("./source-kinds.js");
 const IGNORE_MARKER = "vigiles:ignore-test";
 /** Mirror of the DEFAULT_IGNORE globs (root-anchored), as a key predicate. */
 function isIgnored(key) {
@@ -190,7 +175,7 @@ function discoverTests(files) {
     for (const path of Object.keys(files)) {
         if (isIgnored(path))
             continue;
-        if (DEFAULT_TEST_SUFFIXES.some((s) => path.endsWith(s))) {
+        if ((0, source_kinds_js_1.isVigilesTest)((0, posix_path_js_1.basename)(path))) {
             out.push((0, coverage_evidence_js_1.prepareTest)(path));
         }
     }

package/dist/test-coverage.js

@@ -78,6 +78,7 @@ const ts_runner_caps_js_1 = require("./ts-runner-caps.js");
 const glob_1 = require("glob");
 const glob_ignore_js_1 = require("./core/glob-ignore.js");
 const exclude_js_1 = require("./exclude.js");
+const source_kinds_js_1 = require("./source-kinds.js");
 const layout_js_1 = require("./core/layout.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
 const coverage_artifact_js_1 = require("./coverage-artifact.js");
@@ -98,9 +99,6 @@ function surfaceGlobs(dir, leaf, materializeRoot) {
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
-/** Every extension Node executes directly. `.mts`/`.cts` are real (TS 4.7+) and
- * Node 22 strips their types with no toolchain — measured, not assumed. */
-const RUNNABLE_EXTS = "{ts,mts,cts,js,mjs,cjs}";
 /**
  * 🔴 `*.test.*` USED TO BE HERE, AND REMOVING IT IS THE POINT.
  *
@@ -128,10 +126,11 @@ const RUNNABLE_EXTS = "{ts,mts,cts,js,mjs,cjs}";
  * for hooks/agents and dropping them for skills — because a rule with a per-kind
  * exception is what this file just spent a day removing.
  */
-const DEFAULT_TEST_GLOBS = [
-    `**/*.harness.${RUNNABLE_EXTS}`,
-    `**/*.eval.${RUNNABLE_EXTS}`,
-];
+// Read off the table in `source-kinds.ts` — the same one `vigiles test`,
+// `vigiles eval` and the hook/provider discovery classify by — so the patterns
+// that credit a test and the files a hook directory refuses to compile cannot
+// drift apart.
+const DEFAULT_TEST_GLOBS = source_kinds_js_1.DEFAULT_TEST_GLOBS;
 const DEFAULT_IGNORE = [
     "node_modules/**",
     "dist/**",
@@ -298,6 +297,10 @@ function discoverTests(basePath, globs, ignore) {
         cwd: basePath,
         ignore,
         dot: true,
+        // `glob` defaults this to TRUE on macOS and Windows, so `a.hook.HARNESS.mjs`
+        // was a test there and unclaimed on Linux — and the classifier is
+        // case-sensitive. One answer on every OS.
+        nocase: false,
     });
     // Prepared ONCE per file (comment-strip + declaration parse), not once per
     // (surface × file) pair — the matching below is quadratic by nature.
@@ -737,7 +740,7 @@ function staleRunNote(report) {
     ];
 }
 /** Names a default vitest/jest run collects — the suffixes vigiles will not use. */
-const FOREIGN_RUNNER_SUFFIX = /\.(test|spec)\.(ts|mts|cts|js|mjs|cjs)$/;
+const FOREIGN_RUNNER_SUFFIX = new RegExp(`\\.(test|spec)\\.(${source_kinds_js_1.RUNNABLE_EXTS.join("|")})$`);
 /**
  * The would-be colocated tests that only their NAME disqualifies.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "32.1.1",
+  "version": "33.0.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",