vigiles 32.1.0 → 33.0.0

package/dist/hook-install.js

@@ -3,9 +3,14 @@ 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.hookRuntimeMissingExit = hookRuntimeMissingExit;
 exports.hookGateRef = hookGateRef;
 exports.mergeHooksJson = mergeHooksJson;
 exports.mergeHooksToml = mergeHooksToml;
@@ -18,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
@@ -30,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`),
@@ -41,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
@@ -122,49 +322,30 @@ function hookRuntimeRef(projectRootTokens) {
     const token = projectRootTokens?.[0];
     return token === undefined ? `node ${rel}` : `node "${token}/${rel}"`;
 }
-/**
- * What the shell must do when the runtime above CANNOT START — a missing
- * `node_modules/vigiles`, an unreadable file, an interpreter that dies before a
- * single line of ours runs. No code of ours executes in that case, so the policy
- * has to be expressed in the emitted command or not at all.
- *
- * 🔴 THIS IS NOT A NEW POLICY. `runHookProgramCommand`'s load-failure branch has
- * decided it since 2026-08: *"an inject's purpose is to ADD context, not to
- * ENFORCE a decision … Gates (file, bash, prompt, stop) remain conservative and
- * fail closed."* That branch only reaches failures that happen AFTER the runtime
- * starts. This carries the same rule one layer out, to the failures that happen
- * before it.
- *
- * WHY THE SPLIT, RATHER THAN ONE ANSWER FOR EVERYTHING — the two failures are
- * not comparable:
- *
- *   A GATE THAT SILENTLY PASSES IS WORSE THAN NO GATE. Its whole value is the
- *   refusal, and a harness that reports protection it is not providing is the
- *   one state worse than admitting it has none. So a gate whose runtime is
- *   missing exits 2: loud, blocking, and the cause is on stderr.
- *
- *   A NUDGE THAT BLOCKS COSTS THE WHOLE REPOSITORY. Measured here 2026-08-10:
- *   merge-conflict markers in `package.json` stopped every hook loading, the
- *   Bash gate then refused `git merge --abort` — the one command that undoes the
- *   cause — and the session could not be repaired from inside. A reminder is
- *   never worth that, so a nudge exits 0 and says nothing it cannot say.
- *
- * The role is not a flag someone can flip: `Reaction` has no `deny` and an
- * inject returns context, so "nudge" is a fact about the TYPE the author chose.
- *
- * (Industry does not agree on one answer either — husky and lefthook skip,
- * pre-commit fails. Which is itself the argument for deciding by role instead
- * of picking one and imposing it on both.)
- */
-function hookRuntimeMissingExit(kind) {
-    return kind === "inject" || kind === "react" ? 0 : 2;
-}
 function hookGateRef(ref, projectRootTokens) {
     const token = projectRootTokens?.[0];
     return token === undefined ? ref : `"${token}/${ref}"`;
 }
 /**
- * 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,
@@ -172,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;
@@ -432,12 +438,16 @@ async function runHookProgramCommand(file) {
         // the author are different from a `deny`'s: name the real cause, and leave a
         // way back.
         //
-        // EXCEPTION: inject hooks. An inject's purpose is to ADD context, not to
-        // ENFORCE a decision. If it fails to load, the session should degrade
-        // gracefully (no context injected) rather than wedging the entire harness.
-        // This is a harness failure, not a gating decision — so we handle it by
-        // logging the error and exiting 0. Gates (file, bash, prompt, stop) remain
-        // conservative and fail closed.
+        // A hook that cannot be loaded always exits 2 here, whatever kind of hook it
+        // is. We cannot tell: the hook did not load, so there is nothing to ask
+        // whether it is a gate (can block) or a nudge (reminder only). This code used
+        // to guess from the file name (`file.includes("inject")`), and the guess
+        // disagreed with the `|| exit N` ending that `vigiles compile` writes on the
+        // command: a nudge without "inject" in its name blocked the session, and a
+        // gate with it let every command through (#312).
+        // Now only that ending decides. A nudge is wired `|| exit 0`, so the shell
+        // turns our 2 into a 0 and it degrades; a gate is wired `|| exit 2` and
+        // blocks. A command with no such ending is treated as a gate, the safe default.
         //
         // Escapes, both announced loudly on stderr:
         //   - the stale-stamp one (an edit to the hook itself / `vigiles compile`),
@@ -476,11 +486,13 @@ async function runHookProgramCommand(file) {
             announceRepairEscape(file, cause);
             return;
         }
-        // Log the error, but for inject hooks, degrade gracefully (exit 0).
         const errorMsg = `vigiles: hook ${file} ${cause}.\n` +
             `vigiles: this is the state of the HARNESS, not a decision about your ` +
             `command — the gate never ran. Blocking anyway (a gate that cannot run ` +
             `must not pass traffic).\n` +
+            `vigiles: if this hook is a NUDGE (an inject or a react), it must not ` +
+            `block: its wiring should end in \`|| exit 0\`, which \`vigiles compile\` ` +
+            `writes. A hook wired by hand with no such ending is treated as a gate.\n` +
             `vigiles: the way out is a FILE WRITE, not a command — under a tool that ` +
             `WRITES (Write/Edit/MultiEdit); a Read of the same path repairs nothing ` +
             `and is refused. Fix whichever of ` +
@@ -493,24 +505,11 @@ async function runHookProgramCommand(file) {
             `repair this failure.\n` +
             `vigiles: no command is allowed, deliberately. \`git merge --abort\` and ` +
             `\`git checkout\` RUN \`.git/hooks/*\` (measured: reference-transaction, ` +
-            `post-checkout), and \`vigiles compile\` loads the hook through the same ` +
-            `resolver that just failed.`;
+            `post-checkout), \`vigiles compile\` loads the hook through the same ` +
+            `resolver that just failed, and an install runs the lifecycle scripts of ` +
+            `every package in the lockfile.`;
         console.error(errorMsg);
-        // Exit code depends on hook kind. This heuristic is based on the filename —
-        // a more robust approach would parse the stamp or metadata, but that requires
-        // the hook to load. Inject hooks typically have "inject" in the name; fall
-        // back to blocking (exit 2) for safety on gates.
-        const isLikelyInject = file.includes("inject");
-        if (isLikelyInject) {
-            // Inject hook: degrade gracefully. Log the error but don't wedge the session.
-            console.error(`vigiles: ${file} is an inject hook; degrading gracefully (no context injected).`);
-            process.exit(0);
-        }
-        else {
-            // Gate hook: fail closed.
-            process.exit(2);
-        }
-        return;
+        process.exit(2);
     }
     verifyStampOrRefuse(file, event);
     switch ((0, hook_program_js_1.dispatchKind)(program)) {

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/local-files.js

@@ -100,6 +100,7 @@ exports.LOCAL_FILES = [
  */
 exports.COMMITTED_PATHS = [
     "hooks", // hook sources + their stamps (`hook-install.ts`)
+    "hook-check.sh", // the start-of-session check, generated by compile (`hook-check.ts`)
     "providers", // registered hook-context providers
     "eval-locks", // committed eval staleness stamps (`eval-lock.ts`)
     "eval-baseline.json", // the committed regression baseline (`eval-baseline.ts`)

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