vigiles 27.2.0 → 28.0.0

package/dist/hook-runtime.js

@@ -75,8 +75,8 @@ function injectableEventsFor(root) {
  */
 exports.loadHookProgram = load_hook_js_1.loadHook;
 /** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
-async function loadProvider(file) {
-    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+async function loadProvider(file, root = process.cwd()) {
+    const abs = (0, node_path_1.resolve)(root, file);
     const { pathToFileURL } = require("node:url");
     let mod;
     try {
@@ -95,8 +95,8 @@ async function loadProvider(file) {
     return def;
 }
 /** Path of the tamper-evident stamp sidecar for a hook file. */
-function hookStampPath(file) {
-    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
+function hookStampPath(file, root = process.cwd()) {
+    return (0, node_path_1.resolve)(root, ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
 }
 /**
  * Perform the state writes a hook declared, after its output has been emitted.
@@ -104,14 +104,14 @@ function hookStampPath(file) {
  * thrown on) is announced — silence here would be a hook that believes it
  * remembered something.
  */
-function applyHookWrites(file, outcome) {
+function applyHookWrites(file, outcome, root) {
     const { ok, refused } = (0, hook_program_js_1.outcomeWrites)(outcome);
     for (const name of refused) {
         console.error(`vigiles: refused to record ${name} from ${file} — not a valid state key.`);
     }
     for (const w of ok) {
         try {
-            (0, hook_state_store_js_1.writeHookState)(file, w);
+            (0, hook_state_store_js_1.writeHookState)(file, w, { cwd: root });
         }
         catch (e) {
             console.error(`vigiles: could not record ${w.name} from ${file}: ${String(e)}`);
@@ -124,13 +124,13 @@ function applyHookWrites(file, outcome) {
  * that can't resolve yields its default (never throws). The pure registry +
  * decision logic live in core/hook-providers.ts — this only injects the real IO.
  */
-async function gatherHookContext(program, file) {
+async function gatherHookContext(program, file, root) {
     const needs = (0, hook_program_js_1.hookNeeds)(program);
     if (needs.length === 0)
         return {};
     // Only load the registered-provider registry if a provider() ref is declared.
     const hasRef = needs.some((n) => typeof n !== "string" && n.kind === "provider-ref");
-    const registry = hasRef ? await loadProviderRegistry() : {};
+    const registry = hasRef ? await loadProviderRegistry(root) : {};
     const { execSync } = require("node:child_process");
     const { isCI } = require("ci-info");
     return (0, hook_providers_js_1.gatherContext)(needs, {
@@ -138,12 +138,12 @@ async function gatherHookContext(program, file) {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "ignore"],
         }),
-        cwd: process.cwd(),
+        cwd: root,
         platform: process.platform,
         isCI,
         // The namespace is bound HERE, from the hook's own path — core never sees
         // it, so no key a hook can spell reaches another owner's store.
-        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key),
+        readState: (key) => (0, hook_state_store_js_1.readHookState)(file, key, root),
         now: Date.now(),
     }, registry);
 }
@@ -152,11 +152,11 @@ async function gatherHookContext(program, file) {
  * for `provider()` ref resolution. A bad/unloadable provider file is skipped (the
  * ref then yields its default ""), never crashes a live session.
  */
-async function loadProviderRegistry() {
+async function loadProviderRegistry(root) {
     const registry = {};
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(process.cwd())) {
+    for (const file of (0, hook_install_js_1.discoverProviderFiles)(root)) {
         try {
-            const def = await loadProvider(file);
+            const def = await loadProvider(file, root);
             registry[def.name] = def;
         }
         catch {
@@ -166,9 +166,9 @@ async function loadProviderRegistry() {
     return registry;
 }
 /** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
-function recordObservation(file, on, would, reason) {
+function recordObservation(file, on, would, reason, root) {
     try {
-        const dir = (0, node_path_1.resolve)(process.cwd(), ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, ".vigiles");
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
         const line = JSON.stringify({
             ts: new Date().toISOString(),
@@ -189,7 +189,7 @@ function recordObservation(file, on, would, reason) {
  * shadow/rollout path. Harness-neutral — exit 2 / exit 0 are identical on Claude
  * Code and Codex; the record is vigiles-local.
  */
-function emitGate(decision, on, mode, file) {
+function emitGate(decision, on, mode, file, root) {
     const action = (0, hook_program_js_1.gateAction)(decision, mode);
     switch (action.kind) {
         case "block":
@@ -200,7 +200,7 @@ function emitGate(decision, on, mode, file) {
                 mode: "enforce",
                 rule: file,
                 reason: action.reason,
-            });
+            }, root);
             console.error(action.reason);
             process.exit(2);
             return;
@@ -212,7 +212,7 @@ function emitGate(decision, on, mode, file) {
                 mode: "enforce",
                 rule: file,
                 reason: action.reason,
-            });
+            }, root);
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
                     hookEventName: on,
@@ -229,8 +229,8 @@ function emitGate(decision, on, mode, file) {
                 mode: "observe",
                 rule: file,
                 reason: action.reason,
-            });
-            recordObservation(file, on, action.would, action.reason);
+            }, root);
+            recordObservation(file, on, action.would, action.reason, root);
             console.error(`⚠ [vigiles observe] ${on}: would ${action.would} — ${action.reason}`);
             return; // exit 0 — observe never blocks
         case "allow":
@@ -247,9 +247,9 @@ function emitGate(decision, on, mode, file) {
  * observed wedge came from a `package.json` the author was not thinking about at
  * the time — it had merge-conflict markers in it, nothing to do with hooks.
  */
-function hookLoadPathFiles(hookFile) {
+function hookLoadPathFiles(hookFile, root) {
     const files = [];
-    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), hookFile));
+    let dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(root, hookFile));
     for (;;) {
         const pkg = (0, node_path_1.resolve)(dir, "package.json");
         files.push(pkg);
@@ -275,15 +275,15 @@ function hookLoadPathFiles(hookFile) {
             break;
         dir = up;
     }
-    files.push((0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json"));
+    files.push((0, node_path_1.resolve)(root, ".vigilesrc.json"));
     return files;
 }
 /**
  * The conflicted files on this hook's load path, if any — the difference between
  * "your hook is broken" and "your repo is mid-merge and the hook is collateral".
  */
-function conflictedLoadPathFiles(hookFile) {
-    return hookLoadPathFiles(hookFile)
+function conflictedLoadPathFiles(hookFile, root) {
+    return hookLoadPathFiles(hookFile, root)
         .filter((p) => {
         try {
             return ((0, node_fs_1.existsSync)(p) && (0, merge_conflict_js_1.hasMergeConflictMarkers)((0, node_fs_1.readFileSync)(p, "utf-8")));
@@ -292,7 +292,7 @@ function conflictedLoadPathFiles(hookFile) {
             return false; // unreadable is a different problem; don't guess about it
         }
     })
-        .map((p) => (0, node_path_1.relative)(process.cwd(), p) || p);
+        .map((p) => (0, node_path_1.relative)(root, p) || p);
 }
 /**
  * Print the loud stderr banner that accompanies a REPAIR-only pass-through, and
@@ -321,14 +321,15 @@ function announceRepairEscape(file, why) {
  * `.claude/settings.json` to unwire the gate. Observed 2026-08-03.
  */
 function verifyStampOrRefuse(file, event) {
-    const stampPath = hookStampPath(file);
+    const { root } = event;
+    const stampPath = hookStampPath(file, root);
     if (!(0, node_fs_1.existsSync)(stampPath))
         return;
     try {
         const { stamp } = JSON.parse((0, node_fs_1.readFileSync)(stampPath, "utf-8"));
-        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(root, file), "utf-8");
         if (stamp && !(0, hook_program_js_1.verifyHookStamp)(source, stamp)) {
-            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, process.cwd())) {
+            if ((0, hook_program_js_1.isStampRepairEvent)(event, file, root)) {
                 announceRepairEscape(file, "does not match its compiled stamp");
                 return;
             }
@@ -388,21 +389,39 @@ async function runHookProgramCommand(file) {
     catch {
         /* no stdin */
     }
-    let event = {};
+    let payload = {};
     try {
-        event = JSON.parse(raw);
+        payload = JSON.parse(raw);
     }
     catch {
         /* malformed → empty event */
     }
-    // The root repo-relative path prefixes resolve against. `$CLAUDE_PROJECT_DIR`
-    // first (the same root the harness resolved THIS hook's own path against),
-    // then the payload's `cwd`; never `process.cwd()`, which under a git worktree
-    // can be a different checkout. See `projectRootOf`.
-    const projectRoot = (0, hook_program_js_1.projectRootOf)(event, process.env);
+    // 🔴 THE ROOT IS RESOLVED ONCE, HERE, AND RIDES ON THE EVENT. Everything below
+    // reads `event.root`; nothing recomputes it and nothing is handed a root
+    // beside an event it might disagree with. That disagreement is the defect
+    // this shape exists to prevent — the stamp sidecar, the hook's own source,
+    // the state store, the ledger and the provider registry each used to resolve
+    // against `process.cwd()` while the decision layer resolved against the
+    // payload, so under a worktree the tamper check did not misfire, it did not
+    // run at all.
+    //
+    // This is the only `process.cwd()` on the runtime's own execution path, and
+    // it is the documented last resort for a payload that declares no root. The
+    // two others in this file are back-compat defaults on exported helpers
+    // (`loadProvider`, `hookStampPath`) for callers outside the runtime; the
+    // runtime itself always passes a root and never takes them.
+    const event = (0, hook_program_js_1.resolveHookEvent)(payload, process.env, process.cwd());
+    const root = event.root;
+    // ⚠️ THE DECISION LAYER MUST NOT SEE THE FALLBACK, and this is not a detail.
+    // `pathView` treats an undefined root as "I cannot place this path" and errs
+    // toward SILENCE. Handing it `process.cwd()` instead would turn that silence
+    // into confident decisions measured against a directory nobody declared —
+    // quietly widening what gates fire on. IO paths need a usable root; verdicts
+    // need an honest one, and they are not the same question.
+    const declaredRoot = event.rootDeclared ? event.root : undefined;
     let program;
     try {
-        program = await (0, exports.loadHookProgram)(file);
+        program = await (0, exports.loadHookProgram)(file, root);
     }
     catch (err) {
         // A LOAD failure is a fact about the harness, not a verdict about the
@@ -430,7 +449,7 @@ async function runHookProgramCommand(file) {
         //     not go through PreToolUse(Bash)).
         // Everything else stays BLOCKED, and the escapes are whitelists of commands
         // that are WRITES — see `isLoadPathRepairEvent` for why no command is one.
-        const conflicted = conflictedLoadPathFiles(file);
+        const conflicted = conflictedLoadPathFiles(file, root);
         // 🔴 THE THROWN MESSAGE IS THE ONLY THING THAT NAMES THE REAL CAUSE when the
         // merge-conflict heuristic above does not fire. Without it this said just
         // "cannot be loaded" — a diagnosis that sends the reader looking in the wrong
@@ -444,13 +463,13 @@ async function runHookProgramCommand(file) {
                 `may be fine)`
             : `cannot be loaded — ${thrown}`;
         if ((0, hook_program_js_1.isLoadPathRepairEvent)(event, file, {
-            // The root the REST of this runtime already uses: `hookStampPath` and
-            // `verifyStampOrRefuse` read the hook and its sidecar via `process.cwd()`,
-            // so a repair accepted against any other root would name a file the
-            // runtime never reads. The hook's own path cannot supply it (a hook sits
-            // at any depth, and a `.git` probe would be a disk read core does not do).
-            root: process.cwd(),
-            loadPathFiles: hookLoadPathFiles(file),
+            // The root the REST of this runtime already uses — now the PROJECT's,
+            // not the process's. A repair accepted against any other root would name
+            // a file the runtime never reads. The hook's own path cannot supply it (a
+            // hook sits at any depth, and a `.git` probe would be a disk read core
+            // does not do), so it is passed in.
+            root,
+            loadPathFiles: hookLoadPathFiles(file, root),
         })) {
             announceRepairEscape(file, cause);
             return;
@@ -466,7 +485,7 @@ async function runHookProgramCommand(file) {
             `${file}, ${merge_conflict_js_1.HARNESS_CONFIG_FILES.join(", ")} is broken — those writes are ` +
             `allowed even while this refuses, and a Bash gate never gated file tools ` +
             `at all. The hook then loads and the gate decides normally again.\n` +
-            `vigiles: those paths resolve under ${process.cwd()} — plus any ancestor ` +
+            `vigiles: those paths resolve under ${root} — plus any ancestor ` +
             `\`package.json\` Node actually reads, so whatever is named above as the ` +
             `cause is writable. A path in a DIFFERENT checkout is refused: it cannot ` +
             `repair this failure.\n` +
@@ -494,7 +513,7 @@ async function runHookProgramCommand(file) {
     verifyStampOrRefuse(file, event);
     switch ((0, hook_program_js_1.dispatchKind)(program)) {
         case "inject": {
-            const ctx = await gatherHookContext(program, file);
+            const ctx = await gatherHookContext(program, file, root);
             const injection = (0, hook_program_js_1.injectionOf)(program, event, ctx);
             process.stdout.write(JSON.stringify({
                 hookSpecificOutput: {
@@ -508,20 +527,20 @@ async function runHookProgramCommand(file) {
                 kind: "injection",
                 context: injection.context,
                 records: injection.records,
-            });
+            }, root);
             return;
         }
         case "react": {
-            const ctx = await gatherHookContext(program, file);
-            warnIfPathUndecidable(event, projectRoot);
-            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, projectRoot);
+            const ctx = await gatherHookContext(program, file, root);
+            warnIfPathUndecidable(event, declaredRoot);
+            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, declaredRoot);
             // A notice has to REACH someone. stderr at exit 0 goes to the debug log
             // and nothing else (the host's docs are explicit: "Claude never sees it"),
             // and a react always exits 0 because its type has no `deny` — so stderr
             // alone delivered nowhere. Emit the same `additionalContext` shape the
             // shipped refs/eval-lock nudges use, gated on the ACTIVE adapter's
             // `injectableEvents` so this is per-harness fact, not a CC literal.
-            const injectable = injectableEventsFor(projectRoot ?? process.cwd());
+            const injectable = injectableEventsFor(root);
             const delivery = (0, hook_program_js_1.noticeDelivery)(reaction, program.on, injectable);
             if (delivery.kind === "inject") {
                 process.stdout.write(JSON.stringify({
@@ -537,7 +556,7 @@ async function runHookProgramCommand(file) {
             // Removing it would break existing consumers to gain nothing.
             if (reaction.kind === "notice")
                 console.error(reaction.message);
-            applyHookWrites(file, { kind: "reaction", reaction });
+            applyHookWrites(file, { kind: "reaction", reaction }, root);
             if (reaction.kind === "run") {
                 const { spawnSync } = require("node:child_process");
                 const res = spawnSync(reaction.command, {
@@ -549,29 +568,29 @@ async function runHookProgramCommand(file) {
             return;
         }
         case "file-gate": {
-            const ctx = await gatherHookContext(program, file);
-            warnIfPathUndecidable(event, projectRoot);
-            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            const ctx = await gatherHookContext(program, file, root);
+            warnIfPathUndecidable(event, declaredRoot);
+            emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, declaredRoot), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "bash-gate": {
-            const ctx = await gatherHookContext(program, file);
-            // The same `projectRoot` the file gates get: without it every
+            const ctx = await gatherHookContext(program, file, root);
+            // The same `declaredRoot` the file gates get: without it every
             // repo-relative prefix in a DENYLIST matcher (`touches`/`writesTo`) is
             // matched by over-blocking alone, and with it an absolute token is placed
             // exactly. Measured bypass this closes: `sed -i s/a/b/ <abs>/paper.tex`
             // exited 0 against a guard that blocked the relative spelling.
-            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            emitGate((0, hook_program_js_1.decideProgram)(program, event, ctx, declaredRoot), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "prompt-gate": {
-            const ctx = await gatherHookContext(program, file);
-            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            const ctx = await gatherHookContext(program, file, root);
+            emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
         case "stop-gate": {
-            const ctx = await gatherHookContext(program, file);
-            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
+            const ctx = await gatherHookContext(program, file, root);
+            emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file, root);
             return;
         }
     }

package/dist/load-hook.d.ts

@@ -20,5 +20,5 @@ import { type AnyHook } from "./core/hook-program.js";
  * @throws {HookCompileError} when the file can't be imported, or has no
  * default-exported hook program.
  */
-export declare function loadHook(file: string): Promise<AnyHook>;
+export declare function loadHook(file: string, root?: string): Promise<AnyHook>;
 //# sourceMappingURL=load-hook.d.ts.map

package/dist/load-hook.js

@@ -39,8 +39,8 @@ const hook_program_js_1 = require("./core/hook-program.js");
  * @throws {HookCompileError} when the file can't be imported, or has no
  * default-exported hook program.
  */
-async function loadHook(file) {
-    const abs = (0, node_path_1.resolve)(process.cwd(), file);
+async function loadHook(file, root = process.cwd()) {
+    const abs = (0, node_path_1.resolve)(root, file);
     let mod;
     try {
         mod = (await import((0, node_url_1.pathToFileURL)(abs).href));

package/dist/run-hook.js

@@ -189,7 +189,23 @@ function runHookWith(command, input, opts, deps) {
             ran: false,
             conditionReason: verdict.why,
         };
-    const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), opts, deps);
+    // 🔴 A SPAWN DIRECTORY WITH NO DECLARED ROOT MEANS "THIS DIRECTORY IS THE
+    // PROJECT". Without this, a test that says `{ cwd: dir }` and nothing else
+    // inherits whatever `$CLAUDE_PROJECT_DIR` the AMBIENT shell exports, and since
+    // the runtime prefers the env over the payload (see `projectRootOf`), the hook
+    // resolves a root the test never named. Measured 2026-09-19: five rail suites
+    // pass with the variable unset — which is CI, and this container — and fail
+    // when it is set, which is any run inside a live Claude Code session. That is
+    // a one-sided failure, invisible exactly where it would be caught.
+    //
+    // An EXPLICIT value always wins, including the empty string: a test that pins
+    // `CLAUDE_PROJECT_DIR: ""` is saying "no env root, resolve from the payload",
+    // and that case has its own coverage.
+    const rooted = opts.cwd !== undefined &&
+        !Object.prototype.hasOwnProperty.call(opts.env ?? {}, "CLAUDE_PROJECT_DIR")
+        ? { ...opts, env: { ...opts.env, CLAUDE_PROJECT_DIR: opts.cwd } }
+        : opts;
+    const res = (0, run_script_js_1.runScriptWith)(command, JSON.stringify(input), rooted, deps);
     const json = parseHookOutput(res.stdout);
     const { blocked, decision, haltsTurn, blockedBy } = decideHook(res.exitCode, json, protocol);
     return {

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": "28.0.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",