vigiles 27.2.0 → 28.0.0

package/dist/core/test-utils.d.ts

@@ -1,6 +1,5 @@
 import type { ClaudeSpec } from "./spec.js";
-export declare function makeTmpDir(suffix?: string): string;
-export declare function cleanupTmpDir(dir: string): void;
+export { makeTmpDir, cleanupTmpDir } from "./tmp-root.js";
 export declare function makeSpec(overrides?: Partial<ClaudeSpec>): ClaudeSpec;
 declare function git(cwd: string, cmd: string): string;
 export declare function initGitRepo(dir: string): void;

package/dist/core/test-utils.js

@@ -1,20 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.makeTmpDir = makeTmpDir;
-exports.cleanupTmpDir = cleanupTmpDir;
+exports.cleanupTmpDir = exports.makeTmpDir = void 0;
 exports.makeSpec = makeSpec;
 exports.initGitRepo = initGitRepo;
 exports.git = git;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
-function makeTmpDir(suffix = "test") {
-    return (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), `vigiles-${suffix}-`));
-}
-function cleanupTmpDir(dir) {
-    (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
-}
+// Re-exported, not redefined: the temp root lives in `tmp-root.ts` because the
+// runtime modules that need one must not pull in `makeSpec`/`initGitRepo` and
+// their dependencies. One definition, two doors.
+var tmp_root_js_1 = require("./tmp-root.js");
+Object.defineProperty(exports, "makeTmpDir", { enumerable: true, get: function () { return tmp_root_js_1.makeTmpDir; } });
+Object.defineProperty(exports, "cleanupTmpDir", { enumerable: true, get: function () { return tmp_root_js_1.cleanupTmpDir; } });
 function makeSpec(overrides) {
     return {
         _specType: "claude",

package/dist/core/tmp-root.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Create a temporary directory and return the path with every symlink resolved.
+ *
+ * The `realpathSync` wrapper is the whole point: it must stay OUTSIDE
+ * `mkdtempSync`, because the directory has to exist before it can be resolved.
+ *
+ * @param suffix distinguishes roots in a listing; the name is `vigiles-<suffix>-*`
+ */
+export declare function makeTmpDir(suffix?: string): string;
+/** Remove a root made by {@link makeTmpDir}. Safe on a path that is already gone. */
+export declare function cleanupTmpDir(dir: string): void;
+//# sourceMappingURL=tmp-root.d.ts.map

package/dist/core/tmp-root.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeTmpDir = makeTmpDir;
+exports.cleanupTmpDir = cleanupTmpDir;
+/**
+ * The ONE way to make a temporary fixture root, with its symlinks resolved.
+ *
+ * ── THE TRAP THIS EXISTS TO ABOLISH (issue #241, measured) ──────────────────────
+ * On macOS `os.tmpdir()` returns a path under `/var/folders/…`, and `/var` is
+ * itself a symlink to `/private/var`. Node resolves a module's own URL to the
+ * REALPATH but leaves `process.argv[1]`, and any path a test composed itself,
+ * exactly as typed. A fixture built under `tmpdir()` therefore carries two
+ * spellings of one directory, and anything comparing them is red on macOS and
+ * green on Linux:
+ *
+ *     const d = mkdtempSync(join(tmpdir(), "probe-"));
+ *     // import.meta.url → "file:///private/var/folders/…/probe.mjs"
+ *     // process.argv[1] → "/var/folders/…/probe.mjs"
+ *
+ * A consumer hit that three times in one suite: a resolver's return value against
+ * a composed expectation, an `isMain` control case, and a git fixture whose
+ * repository root git reported realpath'd while the relative path was computed
+ * against the other spelling (`zernie/research-paper-pipeline#9`).
+ *
+ * 🔴 WHY A SHIPPED HELPER AND NOT THREE FIXED CALL SITES. Those call sites were
+ * hand-rolled because the product shipped nothing to roll: `mkdtempSync(join(
+ * tmpdir(), …))` is the shape a harness author reaches for, and it is the shape
+ * that carries the trap. Fixing our own sites leaves every future author to
+ * rediscover it. So this is exported from the harness surface (`vigiles`), where
+ * `recordCheck` and `skip` already live.
+ *
+ * 🔴 WHY ITS OWN MODULE. `core/test-utils.ts` also carries `makeSpec` and
+ * `initGitRepo`, which pull in spec types and `execSync`; the runtime modules
+ * that need a temp root must not drag those in. `test-utils` re-exports these two
+ * so existing imports keep working, and there is still exactly one definition.
+ *
+ * ⚠️ On Linux `realpathSync` is the identity here, so no behavioural test on this
+ * platform can hold the fix in place. What holds it is the regression test beside
+ * this file, which builds its own symlink rather than relying on the platform's.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+/**
+ * Create a temporary directory and return the path with every symlink resolved.
+ *
+ * The `realpathSync` wrapper is the whole point: it must stay OUTSIDE
+ * `mkdtempSync`, because the directory has to exist before it can be resolved.
+ *
+ * @param suffix distinguishes roots in a listing; the name is `vigiles-<suffix>-*`
+ */
+function makeTmpDir(suffix = "test") {
+    return (0, node_fs_1.realpathSync)((0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), `vigiles-${suffix}-`)));
+}
+/** Remove a root made by {@link makeTmpDir}. Safe on a path that is already gone. */
+function cleanupTmpDir(dir) {
+    (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+}
+//# sourceMappingURL=tmp-root.js.map

package/dist/core/validate.d.ts

@@ -19,7 +19,21 @@ export declare function normalizeSeverity(v: unknown): unknown;
  * A non-string/array value falls back with a warning (the `ruleMarkers` pattern).
  */
 export declare function asStringArray(v: unknown, fallback: readonly string[], key: string): readonly string[];
-export declare function loadConfig(): VigilesConfig;
+/**
+ * Read `.vigilesrc.json`.
+ *
+ * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
+ * working directory and walks up — right for a CLI verb, where the user is
+ * standing in the project they mean, and wrong for a hook, whose process has no
+ * stable cwd. A hook rail that omits it reads a DIFFERENT project's config, or
+ * none, and the failure runs the wrong way: a missing file means defaults, so a
+ * rule the author switched OFF comes back on, silently, because the file saying
+ * "off" was never found. Nothing in the output distinguishes that from a project
+ * that never configured the rule.
+ *
+ * Every CLI verb still calls this with no argument and is unaffected.
+ */
+export declare function loadConfig(searchFrom?: string): VigilesConfig;
 export declare function parseRules(content: string, { ruleMarkers }?: ParseOptions): ParsedRule[];
 export declare function validate(content: string, { ruleMarkers, rules: rulesConfig, filePath, dialect }?: ValidateOptions): ValidationResult;
 export declare function readInstructionFile(filePath: string, options?: ReadOptions): ReadResult;

package/dist/core/validate.js

@@ -172,13 +172,27 @@ function asStringArray(v, fallback, key) {
     console.warn(`Invalid ${key} in config: expected a string or string[], got ${JSON.stringify(v)}. Ignoring.`);
     return fallback;
 }
-function loadConfig() {
+/**
+ * Read `.vigilesrc.json`.
+ *
+ * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
+ * working directory and walks up — right for a CLI verb, where the user is
+ * standing in the project they mean, and wrong for a hook, whose process has no
+ * stable cwd. A hook rail that omits it reads a DIFFERENT project's config, or
+ * none, and the failure runs the wrong way: a missing file means defaults, so a
+ * rule the author switched OFF comes back on, silently, because the file saying
+ * "off" was never found. Nothing in the output distinguishes that from a project
+ * that never configured the rule.
+ *
+ * Every CLI verb still calls this with no argument and is unaffected.
+ */
+function loadConfig(searchFrom) {
     try {
         const explorer = (0, cosmiconfig_1.cosmiconfigSync)("vigiles", {
             searchPlaces: [".vigilesrc.json"],
             mergeSearchPlaces: false,
         });
-        const result = explorer.search();
+        const result = explorer.search(searchFrom);
         if (!result?.config)
             return { ...DEFAULT_CONFIG };
         const userConfig = result.config;

package/dist/eval.js

@@ -84,6 +84,7 @@ const check_count_js_1 = require("./check-count.js");
 const coverage_probe_js_1 = require("./coverage-probe.js");
 const tool_intercept_js_1 = require("./tool-intercept.js");
 const tool_stub_js_1 = require("./tool-stub.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 function writeFiles(cwd, files) {
     for (const [p, content] of Object.entries(files)) {
         const full = (0, node_path_1.resolve)(cwd, p);
@@ -650,7 +651,7 @@ function whichSkillsFired(trace) {
  * falls out of one pass over the prompts (N× cheaper than re-running per pair).
  */
 async function runSkillSelectionTrial(args) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-selection-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("selection");
     try {
         if (args.fixture)
             writeFiles(cwd, args.fixture);
@@ -1008,7 +1009,7 @@ function seedEphemeralHome(throwawayHome, realHome, keep = exports.EPHEMERAL_HOM
 }
 /** Execute one trial in a fresh sandbox; returns its metric row + usage. */
 async function executeTrial(spec, arm, trialIndex, runner, cfg) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-eval-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("eval");
     try {
         const resolved = (0, plugin_loader_js_1.resolveHarness)({
             plugin: arm.plugin,
@@ -1456,7 +1457,7 @@ function packageSkillsDir(skillsDir, opts = {}) {
     const abs = (0, node_path_1.resolve)(skillsDir);
     if (!(0, node_fs_1.existsSync)(abs))
         throw new Error(`skillsDir not found: ${skillsDir} (resolved ${abs})`);
-    const root = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-skills-"));
+    const root = (0, tmp_root_js_1.makeTmpDir)("skills");
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, ".claude-plugin"), { recursive: true });
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"), JSON.stringify({ name: opts.name ?? "vigiles-loose-skills", version: "0.0.0" }, null, 2));
     const skillsOut = (0, node_path_1.join)(root, "skills");
@@ -1649,7 +1650,7 @@ function copySkillsInto(src, skillsOut, stub, present) {
  * dir. Pure (filesystem only).
  */
 function packageInstallSet(opts) {
-    const root = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
+    const root = (0, tmp_root_js_1.makeTmpDir)("harness");
     try {
         (0, node_fs_1.mkdirSync)((0, node_path_1.join)(root, ".claude-plugin"), { recursive: true });
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, ".claude-plugin", "plugin.json"), JSON.stringify({ name: opts.name, version: "0.0.0" }, null, 2));
@@ -1737,7 +1738,7 @@ function resolveTriggerPluginDir(spec) {
 /** Run one prompt set × trials through `runner`, aggregating fired counts. */
 /** Run one trigger trial in a throwaway cwd (fixture seeded) → fired 0/1. */
 async function runTriggerTrial(prompt, cfg, runner) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-trigger-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("trigger");
     try {
         if (cfg.fixture)
             writeFiles(cwd, cfg.fixture);

package/dist/harness-test.js

@@ -43,7 +43,6 @@ exports.runHarness = runHarness;
  */
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const adapter_conformance_js_1 = require("./adapter-conformance.js");
 const check_count_js_1 = require("./check-count.js");
@@ -61,6 +60,7 @@ var sandbox_js_2 = require("./sandbox.js");
 Object.defineProperty(exports, "decideSandbox", { enumerable: true, get: function () { return sandbox_js_2.decideSandbox; } });
 Object.defineProperty(exports, "specTrusted", { enumerable: true, get: function () { return sandbox_js_2.specTrusted; } });
 Object.defineProperty(exports, "sandboxAvailable", { enumerable: true, get: function () { return sandbox_js_2.sandboxAvailable; } });
+const tmp_root_js_1 = require("./core/tmp-root.js");
 function contentText(content) {
     if (typeof content === "string")
         return content;
@@ -430,7 +430,7 @@ async function runHarnessTest(spec, opts = {}) {
     // Default (no adapter): the unchanged Claude Code driver — keeps the
     // sandbox/confined path and behaviour byte-for-byte identical.
     const driver = adapter
-        ? requireDriver(adapter)
+        ? await requireDriver(adapter)
         : exports.claudeCodeDriver;
     const isClaudeCode = driver.runtime.name === runtime_js_1.claudeCodeRuntime.name;
     const decision = (0, sandbox_js_1.decideSandbox)({
@@ -443,7 +443,7 @@ async function runHarnessTest(spec, opts = {}) {
     if (decision.action === "sandbox" && !isClaudeCode) {
         throw new Error(`sandbox not supported for ${driver.runtime.name}: confined execution is Claude Code only. Pass sandbox: false to run ${driver.runtime.name} unconfined (you audited the code, or trust the outer container).`);
     }
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("harness");
     const { files, settings } = (0, plugin_loader_js_1.resolveHarness)({
         plugin: spec.plugin,
         settings: spec.settings,
@@ -528,12 +528,12 @@ async function runHarness(spec, opts = {}) {
     return runHarnessTest(spec, opts);
 }
 /** Pull the pillar-2 driver off an adapter, asserting it supports testing. */
-function requireDriver(adapter) {
+async function requireDriver(adapter) {
     (0, adapter_conformance_js_1.assertHarnessTestable)(adapter);
     if (!adapter.harnessTestDriver) {
         throw new Error(`Adapter "${adapter.name}" declares harnessTesting but carries no harnessTestDriver — it cannot drive runHarnessTest.`);
     }
-    return adapter.harnessTestDriver;
+    return await adapter.harnessTestDriver();
 }
 /* v8 ignore stop */
 //# sourceMappingURL=harness-test.js.map

package/dist/hook-install.d.ts

@@ -1,3 +1,4 @@
+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). */
@@ -55,6 +56,58 @@ export declare function normalizeHookRef(hookPath: string, cwd?: string): string
  * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
  * it is asserted directly rather than left to inspection.
  */
+/**
+ * Where the hook runtime lives, spelled so the shell can find it WITHOUT `npx`.
+ *
+ * 🔴 MEASURED 2026-09-19, warm cache, five runs each:
+ *
+ *     node <local>/dist/cli.js hook-runtime run-program …   193 ms
+ *     npx vigiles              hook-runtime run-program …  2545 ms
+ *
+ * Thirteen times, on every tool call, because `npx` re-resolves the package on
+ * each invocation — local, then global, then the registry. That search is the
+ * single largest cost in a hook's life; everything the runtime does inside adds
+ * up to less than a fifth of it.
+ *
+ * A harness with no project-root token gets the relative spelling, which is all
+ * 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

@@ -4,6 +4,8 @@ exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
 exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
 exports.normalizeHookRef = normalizeHookRef;
+exports.hookRuntimeRef = hookRuntimeRef;
+exports.hookRuntimeMissingExit = hookRuntimeMissingExit;
 exports.hookGateRef = hookGateRef;
 exports.mergeHooksJson = mergeHooksJson;
 exports.mergeHooksToml = mergeHooksToml;
@@ -99,6 +101,64 @@ function normalizeHookRef(hookPath, cwd = process.cwd()) {
  * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
  * it is asserted directly rather than left to inspection.
  */
+/**
+ * Where the hook runtime lives, spelled so the shell can find it WITHOUT `npx`.
+ *
+ * 🔴 MEASURED 2026-09-19, warm cache, five runs each:
+ *
+ *     node <local>/dist/cli.js hook-runtime run-program …   193 ms
+ *     npx vigiles              hook-runtime run-program …  2545 ms
+ *
+ * Thirteen times, on every tool call, because `npx` re-resolves the package on
+ * each invocation — local, then global, then the registry. That search is the
+ * single largest cost in a hook's life; everything the runtime does inside adds
+ * up to less than a fifth of it.
+ *
+ * A harness with no project-root token gets the relative spelling, which is all
+ * it can be given — see {@link hookGateRef} for the same fallback.
+ */
+function hookRuntimeRef(projectRootTokens) {
+    const rel = "node_modules/vigiles/dist/cli.js";
+    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.d.ts

@@ -45,9 +45,9 @@ import { loadHook } from "./load-hook.js";
  */
 export declare const loadHookProgram: typeof loadHook;
 /** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
-export declare function loadProvider(file: string): Promise<RegisteredProvider>;
+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): string;
+export declare function hookStampPath(file: string, root?: string): string;
 /**
  * `vigiles hook-runtime run-program <file>` — the runtime the compiled hooks block
  * points at. Reads the live event on stdin, loads the typed program, verifies