vigiles 27.2.0 → 27.3.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/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/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")) {

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");

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/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;
@@ -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,

package/dist/run-script.js

@@ -33,12 +33,12 @@ exports.runScript = runScript;
  */
 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 egress_js_1 = require("./egress.js");
 const sandbox_js_1 = require("./sandbox.js");
 const check_count_js_1 = require("./check-count.js");
 const coverage_probe_js_1 = require("./coverage-probe.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 /**
  * True when the exit code is the shell's own report that it never reached the
  * program — so nothing of the harness ran and no surface may be credited.
@@ -260,7 +260,7 @@ function snapshotTree(dir) {
     return out;
 }
 function sandboxedSpawn(command, stdin, opts) {
-    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-sbx-"));
+    const ioDir = (0, tmp_root_js_1.makeTmpDir)("hook-sbx");
     const home = (0, node_path_1.join)(ioDir, "home");
     (0, node_fs_1.mkdirSync)(home);
     // The hook's confined writable work dir: the caller's cwd if given, else a
@@ -354,7 +354,7 @@ function readEgressResult(resultFile) {
         : { status: 1, signal: null, stdout: "", stderr: "", counters: "" };
 }
 function egressSpawn(command, stdin, opts) {
-    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-egr-"));
+    const ioDir = (0, tmp_root_js_1.makeTmpDir)("hook-egr");
     const home = (0, node_path_1.join)(ioDir, "home");
     (0, node_fs_1.mkdirSync)(home);
     const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");

package/dist/sandbox.js

@@ -33,9 +33,9 @@ exports.runSandboxed = runSandboxed;
  */
 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 runtime_js_1 = require("./adapters/claude-code/runtime.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 let cachedAvailable;
 /**
  * Whether this environment can ACTUALLY confine untrusted code under bubblewrap.
@@ -247,7 +247,7 @@ const WRAPPER = [
    bwrap-backed integration test (skipped without bwrap), not the unit gate —
    the pure policy/args/parse helpers above carry the testable logic. */
 function runSandboxed(opts) {
-    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-sbx-"));
+    const ioDir = (0, tmp_root_js_1.makeTmpDir)("sbx");
     const home = (0, node_path_1.join)(ioDir, "home");
     (0, node_fs_1.mkdirSync)(home);
     const scriptF = (0, node_path_1.join)(ioDir, "script.json");

package/dist/scan-behavioral.js

@@ -34,7 +34,6 @@ exports.formatGateReport = formatGateReport;
 const node_fs_1 = require("node:fs");
 const foreign_runner_js_1 = require("./core/foreign-runner.js");
 const eval_load_phase_js_1 = require("./core/eval-load-phase.js");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_child_process_1 = require("node:child_process");
 const scan_js_1 = require("./scan.js");
@@ -46,6 +45,7 @@ const harness_test_js_1 = require("./harness-test.js");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const eval_js_2 = require("./adapters/codex/eval.js");
 const driver_js_1 = require("./adapters/codex/driver.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 function buildProbe(dir, harness) {
     if (harness === "codex") {
         return {
@@ -529,7 +529,7 @@ function gateRubric(gate) {
 }
 /** Run ONE attack against the unstubbed plugin → the agent's output (or errored). */
 async function runGateAttack(dir, job, deps, model) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-gate-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("gate");
     try {
         const out = await deps.driver.runner({
             task: job.attack,

package/dist/test.d.ts

@@ -51,6 +51,7 @@
  * distinction in its config rather than in its imports.
  */
 export { recordCheck } from "./check-count.js";
+export { makeTmpDir, cleanupTmpDir } from "./core/tmp-root.js";
 export { runScript } from "./run-script.js";
 export type { RunScriptOptions, ScriptRunResult } from "./run-script.js";
 export { runHook, parseHookOutput, decideHook, propertyHook, fileToolEvents, egressRoutes, } from "./run-hook.js";

package/dist/test.js

@@ -66,8 +66,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_formatPluginGuardReport = exports.experimental_verifyPluginGuards = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.experimental_hookState = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.recordCheck = void 0;
-exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = void 0;
+exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_formatPluginGuardReport = exports.experimental_verifyPluginGuards = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.experimental_hookState = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.cleanupTmpDir = exports.makeTmpDir = exports.recordCheck = void 0;
+exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = exports.parseOutput = exports.parseResultEvent = void 0;
 // --- reporting: how much did this script actually do? ---
 // `vigiles test` can otherwise see only an exit code, so a file that runs NOTHING
 // prints the same `✓` as one that ran and passed (measured 2026-08-08 on a file
@@ -76,6 +76,21 @@ exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = ex
 // visible to the runner too. See check-count.ts.
 var check_count_js_1 = require("./check-count.js");
 Object.defineProperty(exports, "recordCheck", { enumerable: true, get: function () { return check_count_js_1.recordCheck; } });
+// --- fixture roots: a temp directory whose two spellings agree ---
+// 🔴 DO NOT hand-roll `mkdtempSync(join(tmpdir(), …))` in a harness. On macOS
+// `/var` is a symlink to `/private/var`, so that shape hands you a directory with
+// TWO spellings: Node resolves a module's own URL to the realpath but leaves
+// `process.argv[1]` and any path you composed as typed. Every assertion that
+// compares them is then red on macOS and green on Linux, for a reason that
+// belongs to neither the test nor the code under test — measured three times in
+// one consumer suite (#241, zernie/research-paper-pipeline#9).
+//
+// `makeTmpDir` resolves the root once, at creation. The trap is unreachable from
+// anything built under it, including a symlink the harness creates ITSELF to test
+// symlink handling — that stays a genuine test, because it is explicit.
+var tmp_root_js_1 = require("./core/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; } });
 // --- the process primitives: runScript (any program) + runHook (plus a decision) ---
 // `runScript` runs any program and reports what it DID (exit, both streams,
 // writes, egress). `runHook` is that plus the hook protocol: event to stdin,

package/package.json

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