vigiles 27.2.0 → 28.0.0

package/dist/adapter-conformance.js

@@ -13,13 +13,13 @@ exports.assertAdapterLoadsHooks = assertAdapterLoadsHooks;
  * in their test suite. See `docs/authoring-an-adapter.md`.
  */
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const compile_js_1 = require("./core/compile.js");
 const spec_js_1 = require("./core/spec.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
 const vocabulary_consistency_js_1 = require("./core/vocabulary-consistency.js");
 const event_capability_js_1 = require("./core/event-capability.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 /** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
 function checkAdapterConformance(adapter) {
     const failures = [];
@@ -166,7 +166,7 @@ function assertHarnessTestable(adapter) {
  * run with zero hooks. Does filesystem IO, so it's a separate opt-in assert.
  */
 function assertAdapterLoadsHooks(adapter) {
-    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-conformance-"));
+    const dir = (0, tmp_root_js_1.makeTmpDir)("conformance");
     try {
         const settingsAbs = (0, node_path_1.join)(dir, adapter.layout.settingsPath);
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });

package/dist/adapters/claude-code/adapter.js

@@ -14,7 +14,6 @@ const layout_js_1 = require("./layout.js");
 const runtime_js_1 = require("./runtime.js");
 const hook_protocol_js_1 = require("./hook-protocol.js");
 const model_mock_js_1 = require("./model-mock.js");
-const harness_test_js_1 = require("../../harness-test.js");
 exports.claudeCodeAdapter = {
     name: "claude-code",
     // The reference harness: every tier. Mockable transport (Anthropic SSE) and
@@ -30,7 +29,9 @@ exports.claudeCodeAdapter = {
     runtime: runtime_js_1.claudeCodeRuntime,
     hookProtocol: hook_protocol_js_1.claudeCodeHookProtocol,
     modelMock: model_mock_js_1.claudeCodeModelMock,
-    harnessTestDriver: harness_test_js_1.claudeCodeDriver,
+    // Imported inside the thunk, not at the top: a top-level import runs at module
+    // init and would pull the whole test/compiler graph back in.
+    harnessTestDriver: async () => (await import("../../harness-test.js")).claudeCodeDriver,
     detect(root) {
         // Most specific signal wins: a plugin manifest (3) > repo settings (2) >
         // a bare CLAUDE.md (1, weak — many tools also read it / AGENTS.md).

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

@@ -26,7 +26,6 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
 const node_fs_1 = require("node:fs");
-const node_os_2 = require("node:os");
 const glob_1 = require("glob");
 const check_count_js_1 = require("../../check-count.js");
 /**
@@ -64,8 +63,21 @@ exports.SKIP_EXIT_CODE = 77;
 function statusFor(code, checks, output) {
     if (code === exports.SKIP_EXIT_CODE)
         return "skip";
+    // 🔴 `checks === undefined` GUARDS THE TEXT MATCH, and it is the load-bearing
+    // half. A script that REPORTED a count executed: the counter is written by an
+    // exit handler that exists only once the module was linked and run
+    // (`check-count.ts`), so the count is a STRUCTURAL fact about the child, while
+    // `didNotLoad` is a guess about its text.
+    //
+    // MEASURED: `statusFor(1, 3, "<hook stderr: Cannot find module …>\nAssertionError")`
+    // returned `"skip"` and the run exited 0 — a harness that ran, recorded three
+    // checks and FAILED an assertion, reported as skipped. That is not an exotic
+    // input: vigiles harnesses drive hooks and print their transcripts, so a
+    // loader phrase in the output is ordinary EVIDENCE about the thing under test,
+    // not a diagnosis of the harness. Watching the child from outside cannot tell
+    // those apart. The count can, and it was already in hand.
     if (code !== 0)
-        return didNotLoad(output) ? "skip" : "fail";
+        return checks === undefined && didNotLoad(output) ? "skip" : "fail";
     return checks === 0 ? "vacuous" : "pass";
 }
 /**
@@ -83,10 +95,17 @@ function statusFor(code, checks, output) {
  * 'recordCheck' not found`, and the ledger dropped from 48 records to 34 and from
  * 47 to 33. Nothing about those surfaces had changed — the machine had.
  *
- * ⚠️ This does NOT make a broken environment quiet. A skip still prints `⊘
- * SKIPPED`, and `--no-skip` — which this repo's own CI passes — still fails the
- * run. What changes is only whether a machine problem is allowed to delete a
- * measurement taken on a machine that worked.
+ * ⚠️ This does NOT make a broken environment quiet: a script classified here
+ * fails the run by default (`cli-main.ts`, right after `anyFailed`), because a
+ * skip the AUTHOR never declared is not a skip. What this classification buys is
+ * only that a machine problem may not delete a measurement taken on a machine
+ * that worked.
+ *
+ * 🔴 That default is new, and the sentence it replaces was false. It read
+ * «`--no-skip` — which this repo's own CI passes — still fails the run».
+ * Measured: `--no-skip` appears ZERO times under `.github/`, `package.json`,
+ * `scripts/` and `.claude/`; CI passes `--min=14` and nothing else. The
+ * safety net the non-fatal classification leaned on was never strung.
  *
  * Deliberately literal, and only the loader's own vocabulary: these strings come
  * from Node's module resolution, not from user code. A test that legitimately
@@ -99,6 +118,13 @@ function didNotLoad(output) {
         output.includes("Cannot find package") ||
         output.includes("Cannot find module") ||
         /SyntaxError: Named export '[^']*' not found/.test(output) ||
+        // Same event, ESM spelling. Node phrases a missing named export one way for
+        // a CommonJS target and another for an ES module, and only the first was
+        // listed — so the 2026-08-20 class below still RETRACTED coverage whenever
+        // the dependency happened to be ESM. Measured on Node 22:
+        //   CJS: SyntaxError: Named export 'recordCheck' not found. The requested module …
+        //   ESM: SyntaxError: The requested module './x.mjs' does not provide an export named 'recordCheck'
+        /SyntaxError: The requested module '[^']*' does not provide an export named/.test(output) ||
         output.includes("ERR_UNSUPPORTED_DIR_IMPORT") ||
         output.includes("ERR_PACKAGE_PATH_NOT_EXPORTED"));
 }
@@ -118,6 +144,7 @@ var ts_runner_caps_js_1 = require("../../ts-runner-caps.js");
 Object.defineProperty(exports, "detectNodeCaps", { enumerable: true, get: function () { return ts_runner_caps_js_1.detectNodeCaps; } });
 Object.defineProperty(exports, "canRunTypeScript", { enumerable: true, get: function () { return ts_runner_caps_js_1.canRunTypeScript; } });
 const ts_runner_caps_js_2 = require("../../ts-runner-caps.js");
+const tmp_root_js_1 = require("../../core/tmp-root.js");
 /**
  * The `node` argv (after the binary) to run a single script. Plain JS runs
  * directly; a TypeScript script picks `tsx` when available, else Node's native
@@ -159,7 +186,13 @@ function discoverScripts(patterns, defaultGlob, cwd, ignore) {
     const globs = patterns.length > 0 ? patterns : [defaultGlob];
     const found = new Set();
     for (const p of globs) {
-        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, p))) {
+        // 🔴 `isFile`, not `existsSync`: a DIRECTORY exists too. `vigiles test .`
+        // therefore passed `.` through as a script, `spawn("node", ["."])` died with
+        // Node's `ERR_UNSUPPORTED_DIR_IMPORT` stack, and the classifier downstream
+        // read that stack as "did not load" — a crash reported as a skip, exit 0.
+        // A directory now contributes no files, so the caller's own loud
+        // nothing-matched path owns the message (see `cli-main.ts`).
+        if ((0, node_fs_1.statSync)((0, node_path_1.resolve)(cwd, p), { throwIfNoEntry: false })?.isFile()) {
             found.add(p);
             continue;
         }
@@ -174,10 +207,16 @@ function discoverScripts(patterns, defaultGlob, cwd, ignore) {
         // `test-coverage.ts` and `cli.ts` both pass `dot: true` with comments saying why, and
         // `test-coverage.test.ts` records "glob without `dot:true` never found it and the surface
         // looked untested". Coverage learned it; the runner did not.
+        // 🔴 `nodir: true` for the same reason as the `isFile` guard above, and the
+        // guard alone was NOT enough — caught by its own test. A pattern that names
+        // an existing directory (`sub`, `.`) skips the fast path and then comes back
+        // out of the globber, because a directory matches a glob perfectly well.
+        // Asked of the globber rather than filtered afterwards: it already knows.
         for (const m of (0, glob_1.globSync)(p, {
             cwd,
             ignore: [...ignore],
             dot: true,
+            nodir: true,
         })) {
             found.add(m);
         }
@@ -219,7 +258,7 @@ function readCheckReport(path) {
  */
 async function runScripts(files, cwd, env = {}, opts = {}) {
     const caps = (0, ts_runner_caps_js_2.detectNodeCaps)(cwd);
-    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_2.tmpdir)(), "vigiles-checks-"));
+    const countDir = (0, tmp_root_js_1.makeTmpDir)("checks");
     // 🔴 THE DEFAULT IS DECIDED BY `entry`, NOT BY A FLAG, because the two commands
     // that share this runner have OPPOSITE right answers and the caller already
     // distinguishes them:

package/dist/adapters/codex/adapter.js

@@ -20,7 +20,6 @@ const layout_js_1 = require("./layout.js");
 const runtime_js_1 = require("./runtime.js");
 const hook_protocol_js_1 = require("./hook-protocol.js");
 const model_mock_js_1 = require("./model-mock.js");
-const driver_js_1 = require("./driver.js");
 exports.codexAdapter = {
     name: "codex",
     // Full convergence with Claude Code: mockable (Responses SSE) + shell hooks
@@ -38,7 +37,7 @@ exports.codexAdapter = {
     runtime: runtime_js_1.codexRuntime,
     hookProtocol: hook_protocol_js_1.codexHookProtocol,
     modelMock: model_mock_js_1.codexModelMock,
-    harnessTestDriver: driver_js_1.codexDriver,
+    harnessTestDriver: async () => (await import("./driver.js")).codexDriver,
     detect(root) {
         // A `.codex/config.toml` is a strong signal; a bare AGENTS.md is weak (many
         // harnesses read it). (Unused while unregistered — kept for symmetry.)

package/dist/cli-main.js

@@ -4936,10 +4936,19 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
         // VALUE cannot tell them apart — only the flag's presence can. (Caught by a control:
         // the first version read `minRequired === 0` and made `--min=0` do nothing.)
         if (restArgs.length > 0 && minFlag === undefined) {
-            console.error(`✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
-                `${restArgs.join(", ")}\n` +
-                `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
-                `  If an empty match is expected here, say so with --min=0.`);
+            // A DIRECTORY is the one stale-looking target whose cause we actually know,
+            // so say it instead of listing the three guesses. `vigiles test .` used to
+            // reach `spawn("node", ["."])` and surface Node's module-resolution stack;
+            // the generic message above would now be true but unhelpful.
+            const dirs = restArgs.filter((a) => (0, node_fs_1.lstatSync)(a, { throwIfNoEntry: false })?.isDirectory() === true);
+            console.error(dirs.length > 0
+                ? `✗ vigiles ${kind}: ${dirs.join(", ")} ${dirs.length === 1 ? "is a directory" : "are directories"} — ` +
+                    `pass a file, or a glob like "${defaultGlob}".\n` +
+                    `  A directory is not a script; nothing ran.`
+                : `✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
+                    `${restArgs.join(", ")}\n` +
+                    `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
+                    `  If an empty match is expected here, say so with --min=0.`);
             process.exit(1);
         }
         console.log(`No ${defaultGlob} files found.`);
@@ -5002,6 +5011,35 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     console.log("\n" + (0, run_scripts_js_1.formatScriptSummary)(results));
     if ((0, run_scripts_js_1.anyFailed)(results))
         process.exit(1);
+    // 🔴 A SKIP THE AUTHOR NEVER DECLARED IS NOT A SKIP — and the discriminator was
+    // already sitting in the result. `skip()` exits 77 (`SKIP_EXIT_CODE`); a script
+    // the runtime could not evaluate exits with whatever the loader gave it, 1 in
+    // practice. Both are classified `"skip"` so that neither RETRACTS coverage —
+    // which is right, a file that did not run proved nothing either way — but only
+    // the declared one is a reason to stay green.
+    //
+    // Reported as #243: `vigiles test .` printed a resolver stack over a `⊘`, said
+    // `0 passed, 1 skipped`, and exited 0. Downstream a consumer's README shipped
+    // that exact command as its first setup step, so a new reader's suite silently
+    // never ran. `--no-skip` would have caught it and is not the default; `--min=1`
+    // does not, because it counts files MATCHED, not scripts executed.
+    //
+    // This is deliberately NOT a fifth `ScriptStatus`. Coverage retraction reads the
+    // status as a bare STRING (`executedScripts`, `coverage-artifact.ts`, whose
+    // parameter is typed `string`), so a new member would start retracting silently
+    // with no type error — breaking the one property the classification exists to
+    // protect.
+    const notEvaluated = results.filter((r) => r.status === "skip" && r.code !== run_scripts_js_1.SKIP_EXIT_CODE);
+    if (notEvaluated.length > 0) {
+        console.error(`\n✗ vigiles ${kind}: ${String(notEvaluated.length)} script(s) never ran — the runtime could not load them:\n` +
+            notEvaluated
+                .map((r) => `  ${r.file} (exit ${String(r.code)})`)
+                .join("\n") +
+            `\n  Their previous coverage is kept, because a script that did not run retracts nothing.\n` +
+            `  If a missing dependency is expected here, import it dynamically and call skip() — ` +
+            `a declared skip stays green.`);
+        process.exit(1);
+    }
     // `--no-skip`: in a context that ASSERTS the capability is present (a CI job),
     // a skipped tier is untested surface — fail loudly instead of passing green.
     if (args.includes("--no-skip") && results.some((r) => r.status === "skip")) {
@@ -5214,6 +5252,45 @@ function annotateLintForGitHub(report, flags) {
         ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
     }
 }
+/**
+ * The project root a `hook-runtime` rail acts on — NEVER `process.cwd()` first.
+ *
+ * These rails are a SECOND execution path, wired by hand into a hooks config
+ * (`npx vigiles hook-runtime <kind>`), and every one of them used to ask
+ * `process.cwd()` where the project was. The hook process has no stable cwd: a
+ * git worktree, or a session that has `cd`-ed into a subdirectory, stands
+ * somewhere the project's files are not, and then the state store writes its
+ * marker beside the wrong repo and `.vigiles/*.json` is simply not found. The
+ * failure is SILENT in the permissive direction — no gates loaded reads exactly
+ * like a project that declared none.
+ *
+ * Same order the compiled runtime uses (`projectRootOf`, core/hook-program.ts):
+ * `$CLAUDE_PROJECT_DIR` first — the harness resolved the hook's own path against
+ * it — then the event's own `cwd`, which Claude Code puts in every hook payload.
+ * `process.cwd()` stays as the documented LAST resort, for the rails a human or
+ * the model invokes as a plain command with no event and no env to go on.
+ *
+ * Pass the parsed event wherever stdin was already read; the handlers that take
+ * only an argument pass nothing and get the env answer.
+ */
+function runtimeRoot(event = {}) {
+    return (0, hook_program_js_1.projectRootOf)(event, process.env) ?? process.cwd();
+}
+/**
+ * The hook payload as a root SOURCE — `{}` when stdin was absent or malformed,
+ * which {@link runtimeRoot} reads as "this event offers no root" and falls
+ * through. Deliberately separate from each handler's own parse: a rail that
+ * cannot understand its event still knows where the project is, and a rail that
+ * only wants `tool_name` should not have to widen its own type to say so.
+ */
+function eventRoot(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Run a compiled skill's deterministic gate ladder: execute each step gate in
  * order (short-circuiting on the first failure), then the result gate. This is
@@ -5226,7 +5303,8 @@ function runSkillCommand(target) {
         console.error("Usage: vigiles hook-runtime run-skill <SKILL.md>");
         process.exit(2);
     }
-    const path = (0, node_path_1.resolve)(process.cwd(), target);
+    const root = runtimeRoot();
+    const path = (0, node_path_1.resolve)(root, target);
     if (!(0, node_fs_1.existsSync)(path)) {
         console.error(`Not found: ${target}`);
         process.exit(2);
@@ -5237,7 +5315,7 @@ function runSkillCommand(target) {
         return;
     }
     console.log(`Running gate ladder for ${target}:\n`);
-    const report = (0, skill_runtime_js_1.runSkillGates)(gates, process.cwd());
+    const report = (0, skill_runtime_js_1.runSkillGates)(gates, root);
     for (const r of report.results) {
         const label = r.at === "result" ? "result" : `step ${String(r.at)}`;
         console.log(`  ${r.ok ? "✓" : "✗"} ${label} — ${(0, skill_runtime_js_1.gateLabel)(r.gate)}`);
@@ -5265,11 +5343,12 @@ function runSkillCommand(target) {
  * feeds the message back to the model; exit 0 allows it and clears the marker.
  */
 function skillHookCommand() {
-    const decision = (0, skill_runtime_js_1.evaluateStopHook)(process.cwd());
+    const root = runtimeRoot();
+    const decision = (0, skill_runtime_js_1.evaluateStopHook)(root);
     if (decision.allow) {
         if (decision.message)
             console.log(decision.message);
-        (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+        (0, skill_runtime_js_1.clearActiveSkill)(root);
         return;
     }
     console.error(decision.message);
@@ -5281,12 +5360,20 @@ function skillStartCommand(target) {
         console.error("Usage: vigiles hook-runtime skill-start <SKILL.md>");
         process.exit(2);
     }
-    (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    const root = runtimeRoot();
+    (0, skill_runtime_js_1.setActiveSkill)(root, target);
     // Record the fire in the flight recorder: the skill NAME is the parent dir of
     // its SKILL.md (skills/<name>/SKILL.md), falling back to the raw target.
     const parts = target.replace(/\\/g, "/").split("/").filter(Boolean);
     const name = parts.length >= 2 ? parts[parts.length - 2] : (parts[0] ?? target);
-    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true });
+    // The SAME root the decision above used. `appendObservation` defaults to
+    // `process.cwd()`, which is correct as a library default and wrong here: a
+    // hook does not run with a stable cwd, so the decision would land in the
+    // project while its record landed beside whatever directory the process
+    // happened to stand in. A ledger split across two directories is not untidy,
+    // it is wrong in a way that reads as normal — the file in the project looks
+    // complete, and nobody notices a flight recorder that is short.
+    (0, observe_js_1.appendObservation)({ kind: "skill", name, fired: true }, root);
     console.log(`Active skill: ${target}`);
 }
 /**
@@ -5319,7 +5406,7 @@ function skillToolHookCommand() {
     }
     if (!tool)
         return;
-    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(process.cwd(), tool, command);
+    const decision = (0, skill_runtime_js_1.evaluateSkillPreToolUse)(runtimeRoot(eventRoot(raw)), tool, command);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -5355,7 +5442,7 @@ function agentHookCommand() {
     catch {
         /* malformed input → no tool, allow */
     }
-    const cwd = process.cwd();
+    const cwd = runtimeRoot(eventRoot(raw));
     // EXPERIMENTAL (parked P3 — do NOT auto-wire). The spawn/SubagentStop bracketing
     // is now nesting-safe: a depth-aware STACK (push on dispatch, POP on SubagentStop)
     // closes the contract-escape the flat single-slot model allowed under CC v2.1.172
@@ -5387,13 +5474,15 @@ function agentHookCommand() {
         return;
     const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(cwd, tool, command);
     if (!decision.allow) {
+        // Same root as the decision — see `skillStartCommand` for why the default
+        // is wrong on a hook rail.
         (0, observe_js_1.appendObservation)({
             kind: "agent",
             name: (0, agent_runtime_js_1.readActiveAgent)(cwd) ?? "unknown",
             tool,
             allowed: false,
             reason: decision.message,
-        });
+        }, cwd);
         console.error(decision.message);
         process.exit(2);
     }
@@ -5438,7 +5527,7 @@ function guardHookCommand() {
     catch {
         /* no stdin */
     }
-    const { decision } = (0, guards_js_1.runGuardHook)(process.cwd(), raw);
+    const { decision } = (0, guards_js_1.runGuardHook)(runtimeRoot(eventRoot(raw)), raw);
     if (!decision.allow) {
         console.error(decision.reason ?? "Blocked by a vigiles guard.");
         process.exit(2);
@@ -5450,7 +5539,7 @@ function agentStartCommand(target) {
         console.error("Usage: vigiles hook-runtime agent-start <agents/<name>.md>");
         process.exit(2);
     }
-    (0, agent_runtime_js_1.pushActiveAgent)(process.cwd(), target);
+    (0, agent_runtime_js_1.pushActiveAgent)(runtimeRoot(), target);
     console.log(`Active agent: ${target}`);
 }
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
@@ -5474,7 +5563,7 @@ async function handleHookRuntime(kind, restArgs) {
             agentStartCommand(restArgs[0]);
             return;
         case "agent-done":
-            (0, agent_runtime_js_1.popActiveAgent)(process.cwd());
+            (0, agent_runtime_js_1.popActiveAgent)(runtimeRoot());
             return;
         case "skill":
             skillHookCommand();
@@ -5486,7 +5575,7 @@ async function handleHookRuntime(kind, restArgs) {
             skillStartCommand(restArgs[0]);
             return;
         case "skill-done":
-            (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+            (0, skill_runtime_js_1.clearActiveSkill)(runtimeRoot());
             return;
         case "run-skill":
             runSkillCommand(restArgs[0]);
@@ -5507,11 +5596,11 @@ async function handleHookRuntime(kind, restArgs) {
             evalLockNudgeHookCommand();
             return;
         case "effect-enter":
-            (0, effect_region_js_1.setEffectActive)(process.cwd());
+            (0, effect_region_js_1.setEffectActive)(runtimeRoot());
             console.log("Effect boundary entered.");
             return;
         case "effect-exit":
-            (0, effect_region_js_1.clearEffectActive)(process.cwd());
+            (0, effect_region_js_1.clearEffectActive)(runtimeRoot());
             return;
         default:
             console.error(`vigiles hook-runtime: unknown runtime entrypoint "${kind ?? ""}". ` +
@@ -5542,7 +5631,8 @@ function actionHookCommand() {
     catch {
         /* malformed input → no event, allow */
     }
-    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(process.cwd()), process.cwd());
+    const root = runtimeRoot(eventRoot(raw));
+    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(root), root);
     if (!decision.allow) {
         console.error(decision.message);
         process.exit(2);
@@ -5586,7 +5676,7 @@ function evalLockNudgeHookCommand() {
     }
     if (!file)
         return;
-    const cwd = process.cwd();
+    const cwd = runtimeRoot(eventRoot(raw));
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     // 🔴 THE SAME CONFIG `vigiles lint` READS. This used to pass `basePath` alone,
     // so a repo that had switched `untested-skill` off, or pointed `include` at
@@ -5600,7 +5690,7 @@ function evalLockNudgeHookCommand() {
     // second gate saying the same thing is a branch no test can distinguish from
     // its absence (measured — the mutation passed), i.e. the dead-fragment class
     // this same change removed from the runner table.
-    const config = (0, validate_js_1.loadConfig)();
+    const config = (0, validate_js_1.loadConfig)(cwd);
     const { options } = untestedRules(config);
     // 🔴 THE SAME LAYOUT `vigiles lint` RESOLVES, for the same reason as the config
     // above. This used to pass `basePath` alone, so the detector fell back to the
@@ -5663,10 +5753,12 @@ function refsHookCommand() {
     }
     if (!file || !isInstructionFile(file))
         return;
-    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)().rules["unmarked-refs"]);
+    // Root first: the config read below is anchored on it, and reading the config
+    // from the process's directory is how a disabled rule comes back to life.
+    const cwd = runtimeRoot(eventRoot(raw));
+    const severity = (0, types_js_1.ruleSeverity)((0, validate_js_1.loadConfig)(cwd).rules["unmarked-refs"]);
     if (severity === false)
         return;
-    const cwd = process.cwd();
     const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
     let markdown;
     try {
@@ -5749,7 +5841,14 @@ async function installHookFile(file, adapter, registeredProviders = []) {
         // emitter never produced it. Measured 2026-09-10 in a consumer repo: after a compile,
         // one `cd` into a subdirectory made a PreToolUse gate fail to load, and a gate that
         // cannot load must block — the repo seized, every command refused including the repair.
-        gateCommand: `npx vigiles hook-runtime run-program ${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)}`,
+        //
+        // 🔴 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.
+        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))}`,
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settingsFormat: adapter.layout.settingsFormat,

package/dist/core/adapter.d.ts

@@ -84,7 +84,28 @@ export interface HarnessAdapter {
      * one seam the runner dispatches through). Carried on the bundle so the runner
      * never imports a sibling adapter to find it.
      */
-    readonly harnessTestDriver?: HarnessTestDriver;
+    /**
+     * 🔴 A THUNK, NOT THE DRIVER, and the indirection is the whole point. A driver
+     * lives in `harness-test.ts`, which imports the conformance suite, which
+     * imports the compiler, which imports the cross-language symbol index, which
+     * loads a NATIVE binary. Holding the driver eagerly meant every consumer of an
+     * adapter paid for all of it — including the hook runtime, which reads only
+     * `dialect` and `hookProtocol` and never runs a harness test at all.
+     *
+     * Measured 2026-09-19, `require("./adapter-registry.js")`:
+     *
+     *     eager:  107 modules, 7 ast-grep, 1 native .node
+     *
+     * ...on a path whose actual work takes about a millisecond. Calling the thunk
+     * is what loads the driver, so the test tier pays and the runtime does not.
+     *
+     * ASYNC because a dynamic `import()` is the only form that defers in BOTH
+     * environments this code runs in: the CJS `dist/` build (where TypeScript
+     * lowers it to a deferred `require`) and vitest loading the TS sources
+     * directly, where a synchronous `require` of a sibling `.ts` does not resolve
+     * at all — measured, not assumed.
+     */
+    readonly harnessTestDriver?: () => Promise<HarnessTestDriver>;
     /**
      * How strongly a repo at `root` looks like it targets this harness — the CLI
      * uses it to auto-detect which adapter to use (the library selects by import).

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

@@ -895,6 +895,49 @@ export interface RawHookEvent {
      */
     readonly cwd?: string;
 }
+/**
+ * A hook event whose project root has already been RESOLVED — the shape every
+ * consumer past the entry point takes.
+ *
+ * {@link RawHookEvent} is what arrives on stdin; this is what the runtime works
+ * with. The difference is one field, and that field is the whole point: with the
+ * root ON the event, an event and a root cannot be handed to different places
+ * and disagree. That divergence is not hypothetical. Measured 2026-09-19: the
+ * decision layer resolved against the payload while the tamper stamp resolved
+ * against `process.cwd()`, and under a git worktree the stamp check did not
+ * point at the wrong file — it returned silently and did not run at all.
+ *
+ * Threading the root as a second parameter beside the event fixes an instance
+ * and keeps the shape. A field removes the shape.
+ */
+export interface HookEvent extends RawHookEvent {
+    /**
+     * The project root, always usable — so no consumer repeats a `?? cwd` fallback
+     * and none can forget it.
+     */
+    readonly root: string;
+    /**
+     * Whether {@link root} came from the payload (`$CLAUDE_PROJECT_DIR` or the
+     * event's own `cwd`) or is the fallback standing in for a payload that
+     * declared none.
+     *
+     * 🔴 THIS IS THE FIELD A POLICY DECISION READS. What to do with an undeclared
+     * root differs by ROLE, not by call site: a gate that cannot locate the
+     * project is a gate that cannot decide, and a gate that cannot decide must
+     * refuse; a nudge in the same position must stay quiet, because a reminder is
+     * never worth a wedged repository. Collapsing both into one behaviour inside
+     * the resolver would make that choice unexpressible.
+     */
+    readonly rootDeclared: boolean;
+}
+/**
+ * Resolve a raw payload's project root ONCE, at the entry point.
+ *
+ * `fallback` is injected rather than read here, because this module does no IO
+ * and holds no ambient state — the caller supplies `process.cwd()`. That is what
+ * keeps `process.cwd()` to a single occurrence in the whole hook runtime.
+ */
+export declare function resolveHookEvent(raw: RawHookEvent, env: Readonly<Record<string, string | undefined>>, fallback: string): HookEvent;
 /** The normalized outcome of running a hook program — discriminated by role. */
 export type HookProgramOutcome = {
     readonly kind: "decision";

package/dist/core/hook-program.js

@@ -34,6 +34,7 @@ exports.injectionOf = injectionOf;
 exports.responseView = responseView;
 exports.experimental_defineReact = experimental_defineReact;
 exports.runReact = runReact;
+exports.resolveHookEvent = resolveHookEvent;
 exports.outcomeWrites = outcomeWrites;
 exports.rememberHookSource = rememberHookSource;
 exports.hookSource = hookSource;
@@ -717,6 +718,22 @@ function hookRouting(hook) {
         // A react MAY also be tool-less (Stop/SessionEnd) — same shape, same reason.
         if (hook.match === undefined)
             return { on: hook.on };
+        // 🔴 SAY WHAT IS WRONG, IN THE AUTHOR'S VOCABULARY. From a typed `.ts` hook
+        // this is unreachable — tsc rejects a `match` without `tools`. From a `.mjs`
+        // hook, which is a supported authoring format, nothing checks it, and
+        // reading `.tools.join` off the wrong shape used to surface as
+        // `Cannot read properties of undefined (reading 'join')`: a message that
+        // names an internal property of an internal function and points nowhere
+        // near the author's file. This repo has already paid twice for a diagnosis
+        // that sends the reader to the wrong place (the loader that advised
+        // `npm run build` when the answer was `npm install`; the bare "cannot be
+        // loaded"). A `HookCompileError` is also what the installer catches to
+        // print the FILE alongside the reason — a TypeError falls past it.
+        if (!Array.isArray(hook.match.tools)) {
+            throw new HookCompileError(`a ${hook.role} hook's \`match\` must be \`{ tools: [...] }\` — got ` +
+                `${JSON.stringify(hook.match)}. Use \`tools("Edit", "Write")\` to build it; ` +
+                `a path condition belongs in the gate's own predicate, not in \`match\`.`);
+        }
         return { on: hook.on, matcher: hook.match.tools.join("|") };
     }
     // Bash by construction — see decideProgram; the author no longer declares it.
@@ -1331,6 +1348,21 @@ function runReact(hook, raw, ctx = {}, root = typeof raw.cwd === "string" ? raw.
         ctx: ctx,
     });
 }
+/**
+ * Resolve a raw payload's project root ONCE, at the entry point.
+ *
+ * `fallback` is injected rather than read here, because this module does no IO
+ * and holds no ambient state — the caller supplies `process.cwd()`. That is what
+ * keeps `process.cwd()` to a single occurrence in the whole hook runtime.
+ */
+function resolveHookEvent(raw, env, fallback) {
+    const declared = projectRootOf(raw, env);
+    return {
+        ...raw,
+        root: declared ?? fallback,
+        rootDeclared: declared !== undefined,
+    };
+}
 /**
  * The state writes an outcome declares, filtered to the ones the runtime may
  * actually perform. A gate's `Decision` carries none — deliberately: a gate is

package/dist/core/linters.js

@@ -36,7 +36,6 @@ exports.parseGolangciEnabledLinters = parseGolangciEnabledLinters;
 exports.clearCedarCache = clearCedarCache;
 exports.checkLinterRule = checkLinterRule;
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const edit_distance_js_1 = require("./edit-distance.js");
 Object.defineProperty(exports, "editDistance", { enumerable: true, get: function () { return edit_distance_js_1.editDistance; } });
@@ -72,6 +71,7 @@ function augmentToolPath() {
     }
 }
 augmentToolPath();
+const tmp_root_js_1 = require("./tmp-root.js");
 // ---------------------------------------------------------------------------
 // Parsing enforcement references
 // ---------------------------------------------------------------------------
@@ -267,7 +267,7 @@ function getDetektDefaultRules() {
     if (DETEKT_DEFAULT_RULE_CACHE)
         return DETEKT_DEFAULT_RULE_CACHE;
     let rules = new Set();
-    const tmp = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-detekt-"));
+    const tmp = (0, tmp_root_js_1.makeTmpDir)("detekt");
     try {
         const target = (0, node_path_1.join)(tmp, "generated-default.yml");
         (0, node_child_process_1.execSync)(`detekt --generate-config --config ${target}`, {
@@ -481,7 +481,7 @@ function runCheckstyleProbe(configPath, probePath) {
  * either placement instantiates.
  */
 function checkstyleModuleInstantiates(ruleName) {
-    const tmp = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-checkstyle-"));
+    const tmp = (0, tmp_root_js_1.makeTmpDir)("checkstyle");
     try {
         const probe = (0, node_path_1.join)(tmp, "Probe.java");
         (0, node_fs_1.writeFileSync)(probe, "class Probe {}\n");