vigiles 32.1.0 → 32.1.1

package/dist/cli-main.js

@@ -69,6 +69,7 @@ const action_gate_js_1 = require("./action-gate.js");
 const guards_js_1 = require("./core/guards.js");
 const hook_program_js_1 = require("./core/hook-program.js");
 const hook_install_js_1 = require("./hook-install.js");
+const hook_check_install_js_1 = require("./hook-check-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
 // The named-state STORE. Lifted out of this file so a TEST can seed a fact
@@ -6017,12 +6018,11 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // cannot load must block — the repo seized, every command refused including the repair.
         //
         // 🔴 AND LAUNCHED LOCALLY, NOT THROUGH `npx` — 193 ms against 2545 ms on a warm
-        // cache, thirteen times, on every tool call. The trailing `|| exit N` is what the
-        // shell does when that binary cannot start at all, and N is decided by the hook's
-        // ROLE: see `hookRuntimeRef` and `hookRuntimeMissingExit` for both measurements
-        // and for why a gate and a nudge must answer differently.
+        // cache, thirteen times, on every tool call. The `|| exit N` ending is what
+        // the shell does when that file cannot start at all. `compileHookProgram`
+        // adds it (see `hookRuntimeMissingExit`), so it is not written here.
         gateCommand: `${(0, hook_install_js_1.hookRuntimeRef)(adapter.layout.projectRootTokens)} hook-runtime run-program ` +
-            `${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)} || exit ${(0, hook_install_js_1.hookRuntimeMissingExit)((0, hook_program_js_1.dispatchKind)(program))}`,
+            (0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens),
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settings: adapter.layout.settings,
@@ -6171,6 +6171,7 @@ async function installHooks(hookFiles, harnessFlag, configHarness) {
             }
         }
     }
+    (0, hook_check_install_js_1.installHookCheck)(adapters);
     return ok;
 }
 /**

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

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

package/dist/core/hook-program.js

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

package/dist/coverage-probe.d.ts

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

package/dist/coverage-probe.js

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

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

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

package/dist/hook-check-install.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHookCheck = installHookCheck;
+/**
+ * Writes the start-of-session check described in `src/hook-check.ts` and adds its
+ * entry to each harness's settings. `vigiles compile` calls this once, after it
+ * has merged the hooks.
+ *
+ * The list of files comes from the settings as they are now, not from the hooks
+ * this run compiled. So compiling one hook does not make the check forget the
+ * others, and compiling twice changes nothing. The entry is found again by the
+ * script's path, so a recompile replaces it in place and leaves any
+ * `SessionStart` hook the user wrote alone.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hook_check_js_1 = require("./hook-check.js");
+const hook_install_js_1 = require("./hook-install.js");
+function isShellAdapter(adapter) {
+    return adapter.shellHooks;
+}
+/** One harness's settings as a plain object, or `undefined` if the file does not exist yet. */
+function readSettings(adapter, cwd) {
+    const file = (0, node_path_1.resolve)(cwd, adapter.layout.settingsPath);
+    return (0, node_fs_1.existsSync)(file)
+        ? adapter.layout.settings.parse((0, node_fs_1.readFileSync)(file, "utf-8"))
+        : undefined;
+}
+/** Add the check's `SessionStart` entry to one harness's settings, or replace it where it already is. */
+function registerCheck(adapter, existing, cwd) {
+    const ref = (0, hook_install_js_1.hookGateRef)(hook_check_js_1.HOOK_CHECK_REF, adapter.layout.projectRootTokens);
+    const merged = adapter.hookProtocol.mergeRegistrations(existing, {
+        SessionStart: [
+            { hooks: [{ type: "command", command: `sh ${ref} || exit 0` }] },
+        ],
+    }, hook_check_js_1.HOOK_CHECK_REF);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, adapter.layout.settingsPath), adapter.layout.settings.render(merged));
+}
+function installHookCheck(adapters, cwd = process.cwd()) {
+    const found = adapters.filter(isShellAdapter).flatMap((adapter) => {
+        const settings = readSettings(adapter, cwd);
+        return settings === undefined ? [] : [{ adapter, settings }];
+    });
+    const { paths, unsafe } = (0, hook_check_js_1.checkPaths)(found.flatMap((f) => (0, hook_check_js_1.commandsIn)(f.settings.hooks)));
+    for (const path of unsafe) {
+        console.warn(`⚠ hook-check: ${path} has characters the check cannot quote safely, so it is NOT covered.`);
+    }
+    if (paths.length === 0)
+        return;
+    const script = (0, node_path_1.resolve)(cwd, hook_check_js_1.HOOK_CHECK_REF);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(script), { recursive: true });
+    (0, node_fs_1.writeFileSync)(script, (0, hook_check_js_1.renderHookCheck)(paths));
+    for (const { adapter, settings } of found)
+        registerCheck(adapter, settings, cwd);
+    console.log(`✓ ${hook_check_js_1.HOOK_CHECK_REF} → SessionStart notice for ${paths.length} wired hook file(s)`);
+}
+//# sourceMappingURL=hook-check-install.js.map

package/dist/hook-check.d.ts

@@ -0,0 +1,36 @@
+/** Where the generated script is written. It is committed, next to the hook sources. */
+export declare const HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/**
+ * Every `command` string in a parsed hooks block. It looks for the key `command`
+ * instead of following one layout, because the layout depends on the harness
+ * (Claude Code nests commands under a matcher block, Codex's TOML is flat).
+ */
+export declare function commandsIn(node: unknown): string[];
+export interface CheckPaths {
+    /** Paths relative to the project, sorted, no duplicates: what the script tests. */
+    readonly paths: readonly string[];
+    /**
+     * Paths the check found but cannot safely write into the script. `compile`
+     * warns about each one, because a path left out is a hook the check does not
+     * cover.
+     */
+    readonly unsafe: readonly string[];
+}
+/**
+ * The files that the compiled-hook commands in `commands` need, as paths relative
+ * to the project. Two kinds of path are left out on purpose: absolute paths
+ * (another machine's checkout will not have them) and paths that use any variable
+ * except the project root, such as `$HOME` or a plugin root (we cannot resolve
+ * them here).
+ */
+export declare function checkPaths(commands: readonly string[]): CheckPaths;
+/**
+ * The text of the script. The same paths always give the same text, so a
+ * recompile that finds the same hooks writes the same bytes.
+ *
+ * The script prints JSON with an `additionalContext` field instead of plain text.
+ * That form is confirmed for the start of a session on both Claude Code and
+ * Codex; plain text is only confirmed on Claude Code.
+ */
+export declare function renderHookCheck(paths: readonly string[]): string;
+//# sourceMappingURL=hook-check.d.ts.map

package/dist/hook-check.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_CHECK_REF = void 0;
+exports.commandsIn = commandsIn;
+exports.checkPaths = checkPaths;
+exports.renderHookCheck = renderHookCheck;
+/**
+ * A check that runs when a session starts and says "run npm install" if files
+ * that the repo's hooks need are missing.
+ *
+ * Why it exists (#312). A compiled hook lives in two places: the wiring in
+ * `.claude/settings.json` (stored in git) and the files that wiring runs (in
+ * `node_modules`, stored by npm). A fresh container, a merge that brings new
+ * wiring, or a dependency update can change one without the other. Today the
+ * first sign is a hook refusing the first command. This check notices one step
+ * earlier and names the fix.
+ *
+ * What it does not do: fix anything. If a hook that can block commands has
+ * missing files, it still refuses every shell command, including the install.
+ * The check only says so before the first command is tried, so a person can run
+ * the install from a terminal outside the session. Removing the cause would need
+ * hook files stored in git next to their wiring; that is a separate decision
+ * (#312).
+ *
+ * Three rules shape the code:
+ *
+ * - It must work when nothing is installed. So the script is plain POSIX `sh`
+ *   using only built-in commands (no node, no vigiles, no grep), and it is
+ *   committed, so it arrives together with the wiring.
+ * - It only prints and always exits 0. We have not verified what exit code 2
+ *   does at session start, and a check that could fail would be one more way to
+ *   break the session it is meant to help. It is wired `|| exit 0`, like any
+ *   reminder.
+ * - It lists only what a compiled hook needs: the hook files named by
+ *   `hook-runtime run-program` commands in the settings, plus the local runtime
+ *   when it is started by path. Reporting any other script (say
+ *   `scripts/build.sh`) as missing in a fresh clone would be a false alarm,
+ *   because `npm install` does not create it.
+ *
+ * The list is read from the settings after `compile` has merged into them. So it
+ * also covers hooks that another tool wrote there, and it does not shrink when
+ * `compile` is run on just one hook. A hook added after the last `compile` is
+ * not covered until the next one.
+ *
+ * Limits: it checks that a file exists, not that it loads. A package that is
+ * present but no longer exports what a hook imports passes this check and still
+ * breaks. A path is recognised by the same pattern the coverage code uses, which
+ * has no room for spaces or quotes, so a hook under such a path is not covered,
+ * and the check cannot say so.
+ */
+const coverage_probe_js_1 = require("./coverage-probe.js");
+/** Where the generated script is written. It is committed, next to the hook sources. */
+exports.HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/**
+ * Every `command` string in a parsed hooks block. It looks for the key `command`
+ * instead of following one layout, because the layout depends on the harness
+ * (Claude Code nests commands under a matcher block, Codex's TOML is flat).
+ */
+function commandsIn(node) {
+    if (Array.isArray(node))
+        return node.flatMap(commandsIn);
+    if (typeof node !== "object" || node === null)
+        return [];
+    return Object.entries(node).flatMap(([key, value]) => key === "command" && typeof value === "string"
+        ? [value]
+        : commandsIn(value));
+}
+/** How a command may spell the project root. It is removed to leave a relative path. */
+const PROJECT_ROOT_PREFIX = /^\$(?:\{CLAUDE_PROJECT_DIR\}|CLAUDE_PROJECT_DIR)\//;
+/** The characters a path may contain. It is written into a shell string and a JSON string. */
+const SAFE_PATH = /^[A-Za-z0-9._@+/-]+$/;
+/**
+ * The files that the compiled-hook commands in `commands` need, as paths relative
+ * to the project. Two kinds of path are left out on purpose: absolute paths
+ * (another machine's checkout will not have them) and paths that use any variable
+ * except the project root, such as `$HOME` or a plugin root (we cannot resolve
+ * them here).
+ */
+function checkPaths(commands) {
+    const relative = commands
+        .flatMap(coverage_probe_js_1.runProgramFiles)
+        .map((file) => file.replace(PROJECT_ROOT_PREFIX, ""))
+        .filter((file) => !file.startsWith("/") && !file.includes("$"));
+    const unique = [...new Set(relative)].sort();
+    return {
+        paths: unique.filter((p) => SAFE_PATH.test(p)),
+        unsafe: unique.filter((p) => !SAFE_PATH.test(p)),
+    };
+}
+/**
+ * The text of the script. The same paths always give the same text, so a
+ * recompile that finds the same hooks writes the same bytes.
+ *
+ * The script prints JSON with an `additionalContext` field instead of plain text.
+ * That form is confirmed for the start of a session on both Claude Code and
+ * Codex; plain text is only confirmed on Claude Code.
+ */
+function renderHookCheck(paths) {
+    const list = paths.map((p) => `  '${p}'`).join(" \\\n");
+    return `#!/bin/sh
+# Generated by \`vigiles compile\`. Do not edit; the next compile rewrites it.
+#
+# Start-of-session notice (vigiles #312). If a file that a compiled hook runs is
+# not installed, it says so in the first turn. It uses only plain sh and shell
+# built-ins (no node, no node_modules, no vigiles), because "not installed" is
+# exactly the situation it reports. It only prints and always exits 0.
+#
+# It does not fix anything. A hook that can block commands, with its files
+# missing, refuses every shell command including the install, so the install has
+# to be run from a terminal outside the session.
+root="\${CLAUDE_PROJECT_DIR:-.}"
+missing=""
+for p in \\
+${list}
+do
+  [ -e "$root/$p" ] || missing="$missing $p"
+done
+if [ -n "$missing" ]; then
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' \\
+    "vigiles: hook files that this repo runs are not installed:$missing. Run npm ci (or npm install) from a terminal outside this session before anything else. A blocking hook whose files are missing refuses every shell command in a session, the install included; a reminder-only hook that cannot load is skipped. See docs/compiled-hooks.md, When a hook cannot load."
+fi
+exit 0
+`;
+}
+//# sourceMappingURL=hook-check.js.map

package/dist/hook-install.d.ts

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

package/dist/hook-install.js

@@ -5,7 +5,6 @@ exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
 exports.normalizeHookRef = normalizeHookRef;
 exports.hookRuntimeRef = hookRuntimeRef;
-exports.hookRuntimeMissingExit = hookRuntimeMissingExit;
 exports.hookGateRef = hookGateRef;
 exports.mergeHooksJson = mergeHooksJson;
 exports.mergeHooksToml = mergeHooksToml;
@@ -122,43 +121,6 @@ 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}"`;

package/dist/hook-runtime.js

@@ -432,12 +432,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 +480,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 +499,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "32.1.0",
+  "version": "32.1.1",
   "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",