vigiles 30.0.0 → 30.0.2

package/dist/adapters/claude-code/agent-runtime.js

@@ -40,6 +40,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const effects_js_1 = require("../../core/effects.js");
 const dialect_js_1 = require("./dialect.js");
+const local_files_js_1 = require("../../local-files.js");
 const effect_region_js_1 = require("./effect-region.js");
 const agent_tools_js_1 = require("./agent-tools.js");
 Object.defineProperty(exports, "parseAgentTools", { enumerable: true, get: function () { return agent_tools_js_1.parseAgentTools; } });
@@ -90,7 +91,7 @@ function decidePreToolUse(allowed, tool) {
 // STACK: push on dispatch, pop on SubagentStop (back to the parent), gate on the
 // stack TOP. Counterexample the flat model fails and the stack model passes:
 // Open(writer); Open(writer); Stop; Call(Bash).
-const ACTIVE_PATH = ".vigiles/active-agent.json";
+const ACTIVE_PATH = `${local_files_js_1.VIGILES_DIR}/${local_files_js_1.ACTIVE_AGENT_FILE}`;
 /**
  * Read the active-agent stack (oldest → newest; the dispatched subagent chain).
  * Back-compat: a legacy single-slot `{ agent: string }` marker reads as a one-frame
@@ -122,6 +123,7 @@ function writeActiveStack(cwd, stack) {
         return;
     }
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.dirname)(p));
     (0, node_fs_1.writeFileSync)(p, JSON.stringify({ stack }) + "\n");
 }
 /**

package/dist/adapters/claude-code/effect-region.js

@@ -12,11 +12,13 @@ exports.hasEffectBoundary = hasEffectBoundary;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const EFFECT_ACTIVE_PATH = ".vigiles/effect-active.json";
+const local_files_js_1 = require("../../local-files.js");
+const EFFECT_ACTIVE_PATH = `${local_files_js_1.VIGILES_DIR}/${local_files_js_1.EFFECT_ACTIVE_FILE}`;
 /** Record that the agent has entered an effect boundary. */
 function setEffectActive(cwd) {
     const p = (0, node_path_1.resolve)(cwd, EFFECT_ACTIVE_PATH);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.dirname)(p));
     (0, node_fs_1.writeFileSync)(p, JSON.stringify({ active: true }) + "\n");
 }
 /** Clear the effect-active marker (the agent exited the effect boundary). */

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -37,7 +37,19 @@ export interface ScriptRunResult {
  */
 export declare const SKIP_EXIT_CODE = 77;
 /**
- * Classify one script's run from its exit code and its reported check count.
+ * What the runner's load hook saw of one script (`harness-resolve-hooks.mts`).
+ *
+ * `marked` — the hook saw the script's module as an ES module and planted a
+ * marker import at the top of it. `linked` — that marker evaluated, which ESM
+ * only does once the WHOLE import graph was found, parsed and linked.
+ */
+export interface LoadEvidence {
+    readonly marked: boolean;
+    readonly linked: boolean;
+}
+/**
+ * Classify one script's run from its exit code, its reported check count and
+ * what the load hook saw.
  *
  * 🔴 THE FOURTH STATE, AND WHY. Exit codes answer "did it fail?", never "did it
  * do anything?". Measured 2026-08-08: a file whose whole body is
@@ -60,8 +72,36 @@ export declare const SKIP_EXIT_CODE = 77;
  * none of it says zero. This is the `undefined`-vs-`[]` distinction
  * `assertNoWrite` already draws: "nobody looked" must not read as "nothing
  * happened".
+ *
+ * 🔴 DID IT LOAD? A non-zero exit from a script whose module was marked and
+ * never linked is did-not-load: `"skip"` with the loader's exit code, which
+ * keeps its coverage (`fail` RETRACTS it, see `runsFromResults`). A module that
+ * never linked executed no assertion — the same "did not run" as a missing
+ * `claude`, arriving through a different door. MEASURED, twice on 2026-08-20: a
+ * container restore left an old `node_modules`, every harness in a consumer repo
+ * died on `Named export 'recordCheck' not found`, and its ledger fell from 48
+ * records to 34 and from 47 to 33 for surfaces nothing had touched. The run is
+ * still red: `cli-main.ts` fails on any skip the author did not declare.
+ *
+ * This used to be decided by grepping the child's OUTPUT for loader phrases,
+ * and that was wrong in the dangerous direction (#243): a harness that printed
+ * a hook transcript containing "Cannot find module", then failed an assertion,
+ * was read as did-not-load and kept its coverage. Output is no longer an input.
+ * Anything without a marker (CommonJS, an entry the hook never saw) can never
+ * claim did-not-load — it is a `fail`, the side that retracts rather than hides.
+ * A syntax error in the script itself also never links, so it too is
+ * did-not-load; that is the owner's call, not an accident.
+ */
+export declare function statusFor(code: number, checks: number | undefined, load?: LoadEvidence): ScriptStatus;
+/**
+ * Did this script fail to LOAD — as opposed to declaring a skip (exit 77)?
+ * The one predicate behind both the CLI's "never ran" failure and `--min`.
+ *
+ * Deliberately NOT a fifth `ScriptStatus`: coverage retraction reads the status
+ * as a bare string (`coverage-artifact.ts`), so a new member would start
+ * retracting silently with no type error.
  */
-export declare function statusFor(code: number, checks: number | undefined, output?: string): ScriptStatus;
+export declare function loadFailed(r: ScriptRunResult): boolean;
 /** Filename extensions accepted for harness/eval scripts (JS and TS). */
 export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
 /** Glob suffix matching every accepted script extension, e.g. `harness`. */

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.canRunTypeScript = exports.detectNodeCaps = exports.SCRIPT_EXTS = exports.SKIP_EXIT_CODE = void 0;
 exports.statusFor = statusFor;
+exports.loadFailed = loadFailed;
 exports.scriptGlob = scriptGlob;
 exports.interpreterArgs = interpreterArgs;
 exports.discoverScripts = discoverScripts;
@@ -36,7 +37,8 @@ const check_count_js_1 = require("../../check-count.js");
  */
 exports.SKIP_EXIT_CODE = 77;
 /**
- * Classify one script's run from its exit code and its reported check count.
+ * Classify one script's run from its exit code, its reported check count and
+ * what the load hook saw.
  *
  * 🔴 THE FOURTH STATE, AND WHY. Exit codes answer "did it fail?", never "did it
  * do anything?". Measured 2026-08-08: a file whose whole body is
@@ -59,74 +61,47 @@ exports.SKIP_EXIT_CODE = 77;
  * none of it says zero. This is the `undefined`-vs-`[]` distinction
  * `assertNoWrite` already draws: "nobody looked" must not read as "nothing
  * happened".
+ *
+ * 🔴 DID IT LOAD? A non-zero exit from a script whose module was marked and
+ * never linked is did-not-load: `"skip"` with the loader's exit code, which
+ * keeps its coverage (`fail` RETRACTS it, see `runsFromResults`). A module that
+ * never linked executed no assertion — the same "did not run" as a missing
+ * `claude`, arriving through a different door. MEASURED, twice on 2026-08-20: a
+ * container restore left an old `node_modules`, every harness in a consumer repo
+ * died on `Named export 'recordCheck' not found`, and its ledger fell from 48
+ * records to 34 and from 47 to 33 for surfaces nothing had touched. The run is
+ * still red: `cli-main.ts` fails on any skip the author did not declare.
+ *
+ * This used to be decided by grepping the child's OUTPUT for loader phrases,
+ * and that was wrong in the dangerous direction (#243): a harness that printed
+ * a hook transcript containing "Cannot find module", then failed an assertion,
+ * was read as did-not-load and kept its coverage. Output is no longer an input.
+ * Anything without a marker (CommonJS, an entry the hook never saw) can never
+ * claim did-not-load — it is a `fail`, the side that retracts rather than hides.
+ * A syntax error in the script itself also never links, so it too is
+ * did-not-load; that is the owner's call, not an accident.
  */
-function statusFor(code, checks, output) {
+function statusFor(code, checks, load) {
     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 checks === undefined && didNotLoad(output) ? "skip" : "fail";
+    if (code !== 0) {
+        // A reported count is written by an exit handler that exists only once the
+        // module ran (`check-count.ts`), so it overrules a missing marker file.
+        const neverLinked = load?.marked === true && !load.linked && checks === undefined;
+        return neverLinked ? "skip" : "fail";
+    }
     return checks === 0 ? "vacuous" : "pass";
 }
 /**
- * Did the script fail to LOAD, rather than fail?
- *
- * 🔴 The distinction is not cosmetic, because `fail` RETRACTS coverage while
- * `skip` does not (see the table on `runsFromResults`). The rule for `fail` —
- * "it ran and proved nothing, so it must not keep yesterday's green record
- * alive" — is right, and it does not describe a file the runtime never
- * evaluated. A module that cannot resolve executed no assertion; it is the same
- * "did not run" as a missing `claude` CLI, arriving through a different door.
- *
- * MEASURED, twice in one session on 2026-08-20: a container restore left an old
- * `node_modules` behind, every harness in the consumer repo died on `Named export
- * '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 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.
+ * Did this script fail to LOAD — as opposed to declaring a skip (exit 77)?
+ * The one predicate behind both the CLI's "never ran" failure and `--min`.
  *
- * 🔴 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
- * asserts on one of them exits 0 or asserts, and never reaches here.
+ * Deliberately NOT a fifth `ScriptStatus`: coverage retraction reads the status
+ * as a bare string (`coverage-artifact.ts`), so a new member would start
+ * retracting silently with no type error.
  */
-function didNotLoad(output) {
-    if (output === undefined || output === "")
-        return false;
-    return (output.includes("ERR_MODULE_NOT_FOUND") ||
-        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"));
+function loadFailed(r) {
+    return r.status === "skip" && r.code !== exports.SKIP_EXIT_CODE;
 }
 /** Filename extensions accepted for harness/eval scripts (JS and TS). */
 exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
@@ -240,6 +215,23 @@ function readCheckReport(path) {
         return undefined;
     }
 }
+/**
+ * What the load hook left behind for one child. A missing or malformed
+ * `seenFile` means the hook never saw the script, so `marked` is false and the
+ * run can never be read as did-not-load.
+ */
+function readLoadEvidence(seenFile, loadedFile) {
+    return { marked: readMarked(seenFile), linked: (0, node_fs_1.existsSync)(loadedFile) };
+}
+function readMarked(seenFile) {
+    try {
+        const seen = JSON.parse((0, node_fs_1.readFileSync)(seenFile, "utf8"));
+        return seen.marked === true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Run each script as `node <file>` (or `node <entry> <file>`, see
  * {@link RunScriptsOptions}), inheriting stdio so the script's own report
@@ -293,6 +285,8 @@ async function runScripts(files, cwd, env = {}, opts = {}) {
             return;
         }
         const countFile = (0, node_path_1.join)(countDir, `${String(i)}.count`);
+        const seenFile = (0, node_path_1.join)(countDir, `${String(i)}.seen`);
+        const loadedFile = (0, node_path_1.join)(countDir, `${String(i)}.loaded`);
         // Resolve a harness's bare `vigiles` import from the CLI's OWN install, so
         // running the gate does not require installing the package into the
         // project — which, in a repo that already has a package.json, drags in the
@@ -301,7 +295,21 @@ async function runScripts(files, cwd, env = {}, opts = {}) {
         // fails, so a locally installed copy still wins.
         const selfRoot = (0, node_path_1.resolve)(__dirname, "..", "..", "..");
         const hook = (0, node_url_1.pathToFileURL)((0, node_path_1.join)(selfRoot, "dist", "harness-resolve-hooks.mjs")).href;
-        const child = (0, node_child_process_1.spawn)("node", ["--import", hookImport(hook), ...argv], {
+        // 🔴 OUR HOOK IS REGISTERED BEFORE `--import tsx`, and the order is
+        // load-bearing. Hooks chain last-in-first-out, so this makes tsx the
+        // OUTER hook: it transpiles the source we already marked, and its source
+        // map describes that source. The other order was measured wrong: tsx
+        // emits each module on ONE line with an inline map, a prefix added after
+        // it shifts every generated column, and a stack frame on line 2 was
+        // reported on line 3 (Node 20.20 and 22.22). The format we see from the
+        // inner position is the same (`module` in a `type: module` scope,
+        // `commonjs` otherwise — also measured).
+        const probe = {
+            entryURL: scriptURL(cwd, file),
+            loadedFile,
+            seenFile,
+        };
+        const child = (0, node_child_process_1.spawn)("node", ["--import", hookImport(hook, probe), ...argv], {
             cwd,
             stdio: ["ignore", "pipe", "pipe"],
             env: {
@@ -321,7 +329,7 @@ async function runScripts(files, cwd, env = {}, opts = {}) {
             resolveRun({
                 file,
                 code,
-                status: statusFor(code, report?.checks, output),
+                status: statusFor(code, report?.checks, readLoadEvidence(seenFile, loadedFile)),
                 checks: report?.checks,
                 ...(report ? { surfaces: report.surfaces } : {}),
             });
@@ -436,13 +444,30 @@ function formatScriptSummary(results) {
     return lines.join("\n");
 }
 /**
- * A `--import` argument that registers the resolver hook without a temp file:
+ * A `--import` argument that registers the harness hooks without a temp file:
  * a data: URL calling `module.register`. Inline because writing a shim into the
  * user's tree to run their tests would be a side effect the runner has no
- * business having.
+ * business having. The per-child probe rides in `data`, not the environment,
+ * so a process the script spawns does not inherit it.
  */
-function hookImport(hookHref) {
-    const src = `import {register} from "node:module";register(${JSON.stringify(hookHref)});`;
+function hookImport(hookHref, probe) {
+    const src = `import {register} from "node:module";register(${JSON.stringify(hookHref)},{data:${JSON.stringify(probe)}});`;
     return `data:text/javascript,${encodeURIComponent(src)}`;
 }
+/**
+ * The URL Node will load the SCRIPT under — for `eval` too, where the process
+ * entry is `eval-entry.js` and the script is what it imports. ESM resolution
+ * realpaths file URLs, so a symlinked path must be realpathed here or the hook
+ * would never recognise it (which is safe — no marker, no did-not-load claim —
+ * but blind).
+ */
+function scriptURL(cwd, file) {
+    const abs = (0, node_path_1.resolve)(cwd, file);
+    try {
+        return (0, node_url_1.pathToFileURL)((0, node_fs_1.realpathSync)(abs)).href;
+    }
+    catch {
+        return (0, node_url_1.pathToFileURL)(abs).href;
+    }
+}
 //# sourceMappingURL=run-scripts.js.map

package/dist/adapters/claude-code/skill-runtime.js

@@ -38,6 +38,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const effects_js_1 = require("../../core/effects.js");
 const dialect_js_1 = require("./dialect.js");
+const local_files_js_1 = require("../../local-files.js");
 const STEP_RE = /^###\s+Step\s+(\d+)/;
 const GATE_CMD_RE = /<!--\s*vigiles:gate\s+"([^"]*)"(?:\s+retry:(\d+))?\s*-->/;
 const GATE_FILE_RE = /<!--\s*vigiles:gate\s+file:(\S+)\s*-->/;
@@ -235,11 +236,12 @@ function runSkillGates(gates, cwd) {
 // (Claude Code hooks don't surface the active skill, so we record it). Wiring
 // `skill-start` to fire automatically is the integration step; the decision
 // logic below is harness-agnostic and fully testable.
-const ACTIVE_PATH = ".vigiles/active-skill.json";
+const ACTIVE_PATH = `${local_files_js_1.VIGILES_DIR}/${local_files_js_1.ACTIVE_SKILL_FILE}`;
 /** Record the skill the agent is currently executing. */
 function setActiveSkill(cwd, skillPath) {
     const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.dirname)(p));
     (0, node_fs_1.writeFileSync)(p, JSON.stringify({ skill: skillPath }) + "\n");
 }
 /** Clear the active-skill marker (the skill finished). */

package/dist/cli-main.js

@@ -38,6 +38,8 @@ const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
 const install_reader_js_1 = require("./core/install-reader.js");
 const plugin_declaration_js_1 = require("./plugin-declaration.js");
+const local_files_tracked_js_1 = require("./local-files-tracked.js");
+const local_files_js_1 = require("./local-files.js");
 const scan_behavioral_js_1 = require("./scan-behavioral.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
 const skill_harness_js_1 = require("./skill-harness.js");
@@ -4914,6 +4916,21 @@ function gitHead(cwd) {
 }
 async function handleRunScripts(kind, args, restArgs, excludes) {
     const cwd = process.cwd();
+    // The ignore file keeps NEW copies of `.vigiles/` local files out of git, but
+    // cannot untrack one a repo already committed. Said here, on the CLI, because
+    // it spawns `git` — never from a hook runtime — and said FIRST, before any
+    // early return: a repo whose harness was removed still carries the stale
+    // committed artifact, and "no files found" must not swallow the warning
+    // (Codex review on #274).
+    //
+    // The ignore file is brought up to date FIRST, and only where `.vigiles/`
+    // already exists: the writers below would otherwise make their edit after the
+    // check, so a tracked ignore file dirtied by this very run went unreported on
+    // the one run a user may ever do (Codex review on #275).
+    const vigilesDir = (0, node_path_1.join)(cwd, local_files_js_1.VIGILES_DIR);
+    if ((0, node_fs_1.existsSync)(vigilesDir))
+        (0, local_files_js_1.ensureLocalFilesIgnored)(vigilesDir);
+    (0, local_files_tracked_js_1.warnTrackedLocalFiles)(cwd);
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
     // The eval LOCK flags (`--check`/`--update`) are resolved BEFORE file discovery
@@ -4929,9 +4946,13 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     // A script under an excluded path is not DISCOVERED (a vendored corpus's own
     // harness must not run as ours), but a script you NAME still runs (#192).
     const files = (0, run_scripts_js_1.discoverScripts)(restArgs.map((p) => noteExplicitOverride(excludes, p, "running")), defaultGlob, cwd, excludes.ignore);
-    // `--min=N`: a CI gate asserts at least N scripts actually RAN — so a bad path,
-    // a renamed file, or a glob that matched nothing fails LOUD instead of passing
-    // green with zero evals executed. Default 0 (off) keeps local runs ergonomic.
+    // `--min=N`: a CI gate asserts at least N scripts actually LOADED — so a bad
+    // path, a renamed file, a glob that matched nothing, or a file that matched and
+    // never linked fails LOUD instead of passing green with nothing executed.
+    // Checked twice: here against files MATCHED (cheap, before anything runs), and
+    // after the run against scripts that LOADED — a matched file that could not be
+    // evaluated is not a script that ran (#243). A declared skip (exit 77) did
+    // load, so it counts. Default 0 (off) keeps local runs ergonomic.
     const minFlag = args.find((a) => a.startsWith("--min="));
     const minRequired = minFlag
         ? Math.max(0, Number.parseInt(minFlag.split("=")[1] ?? "", 10) || 0)
@@ -5035,6 +5056,12 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     // saw — the same shape as the flight-recorder ledger it already appends to.
     recordRunCoverage(cwd, results, kind, harnessFlagFrom(args));
     console.log("\n" + (0, run_scripts_js_1.formatScriptSummary)(results));
+    const loadedCount = results.filter((r) => !(0, run_scripts_js_1.loadFailed)(r)).length;
+    const belowFloor = loadedCount < minRequired;
+    if (belowFloor) {
+        console.error(`\n✗ vigiles ${kind}: --min=${String(minRequired)} but only ${String(loadedCount)} of ` +
+            `${String(files.length)} matched ${kind} file(s) loaded.`);
+    }
     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
@@ -5042,20 +5069,23 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     // 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.
+    // the declared one is a reason to stay green. Which is which is decided by the
+    // runner's load hook (a marker import that evaluates only once the module
+    // graph linked), not by reading the child's output — see `statusFor`.
     //
     // 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.
+    // did not either, because it counted files MATCHED — it now also counts the
+    // scripts that loaded (above).
     //
     // 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);
+    const notEvaluated = results.filter(run_scripts_js_1.loadFailed);
     if (notEvaluated.length > 0) {
         console.error(`\n✗ vigiles ${kind}: ${String(notEvaluated.length)} script(s) never ran — the runtime could not load them:\n` +
             notEvaluated
@@ -5066,6 +5096,8 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
             `a declared skip stays green.`);
         process.exit(1);
     }
+    if (belowFloor)
+        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/guards.js

@@ -41,6 +41,7 @@ exports.runGuardHook = runGuardHook;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const arg_match_js_1 = require("../arg-match.js");
+const local_files_js_1 = require("../local-files.js");
 /** Ergonomic builders for the closed vocabulary. */
 exports.guard = {
     block: (target, reason) => ({
@@ -237,7 +238,7 @@ function parseGuards(json) {
 // Runtime IO — load the guard set, read/append the session ledger
 // ---------------------------------------------------------------------------
 const GUARDS_FILE = ".vigiles/guards.json";
-const LEDGER_FILE = ".vigiles/guard-ledger.json";
+const LEDGER_FILE = `${local_files_js_1.VIGILES_DIR}/${local_files_js_1.GUARD_LEDGER_FILE}`;
 /** Load the declared guard set from `.vigiles/guards.json` (absent → none). */
 function loadGuards(cwd) {
     const p = (0, node_path_1.resolve)(cwd, GUARDS_FILE);
@@ -273,6 +274,7 @@ function recordGuardCall(cwd, event) {
     const calls = readGuardLedger(cwd);
     calls.push({ tool: event.tool, input: event.input });
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.dirname)(p));
     (0, node_fs_1.writeFileSync)(p, JSON.stringify({ calls }, null, 2));
 }
 /** Parse a PreToolUse event JSON (the hook's stdin) into a {@link ToolEvent}. */

package/dist/coverage-artifact.d.ts

@@ -1,9 +1,10 @@
 import type { ProbeOrigin, SurfaceProbe } from "./check-count.js";
+import { COVERAGE_ARTIFACT_FILE } from "./local-files.js";
 import type { Surface, SurfaceKind } from "./test-coverage.js";
 /** Bumped when the record shape changes in a non-additive way. */
 export declare const COVERAGE_ARTIFACT_VERSION = 1;
-/** The artifact filename under `.vigiles/`. */
-export declare const COVERAGE_ARTIFACT_FILE = "coverage.json";
+/** The artifact filename under `.vigiles/` — defined on the one local-files list. */
+export { COVERAGE_ARTIFACT_FILE };
 /**
  * Which runner produced a record. Mirrors the discovery split in
  * `test-coverage.ts`: `vigiles test` runs `*.harness.*` (free, every push),

package/dist/coverage-artifact.js

@@ -58,10 +58,10 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
+const local_files_js_1 = require("./local-files.js");
+Object.defineProperty(exports, "COVERAGE_ARTIFACT_FILE", { enumerable: true, get: function () { return local_files_js_1.COVERAGE_ARTIFACT_FILE; } });
 /** Bumped when the record shape changes in a non-additive way. */
 exports.COVERAGE_ARTIFACT_VERSION = 1;
-/** The artifact filename under `.vigiles/`. */
-exports.COVERAGE_ARTIFACT_FILE = "coverage.json";
 /**
  * Every {@link RunAttribution}, as data — the artifact's validator reads it, so
  * the accepted set and the type cannot drift apart into a record shape the
@@ -576,7 +576,7 @@ function mergeRuns(previous, next, executed) {
 }
 /** Read the artifact, or `undefined` when there is none / it is not one. */
 function readCoverageArtifact(root) {
-    const file = (0, node_path_1.resolve)(root, ".vigiles", exports.COVERAGE_ARTIFACT_FILE);
+    const file = (0, node_path_1.resolve)(root, local_files_js_1.VIGILES_DIR, local_files_js_1.COVERAGE_ARTIFACT_FILE);
     if (!(0, node_fs_1.existsSync)(file))
         return undefined;
     let value;
@@ -618,9 +618,10 @@ function isCoverageRun(value) {
 /** Write the artifact. Best-effort: recording must never fail a green run. */
 function writeCoverageArtifact(root, artifact) {
     try {
-        const dir = (0, node_path_1.resolve)(root, ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, local_files_js_1.VIGILES_DIR);
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
-        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(dir, exports.COVERAGE_ARTIFACT_FILE), JSON.stringify(artifact, null, 2) + "\n");
+        (0, local_files_js_1.ensureLocalFilesIgnored)(dir);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(dir, local_files_js_1.COVERAGE_ARTIFACT_FILE), JSON.stringify(artifact, null, 2) + "\n");
     }
     catch {
         /* best-effort — a scratch-dir failure is not a test failure */

package/dist/eval-cache.d.ts

@@ -74,7 +74,12 @@ export declare function cacheKey(input: CacheKeyInput): SHA256Hash;
  * gate must surface, not mask. The message tells you how to recover.
  */
 export declare function readCache(dir: string, key: SHA256Hash): CacheRecord | null;
-/** Write a cached record by key (creating the cache dir as needed). */
+/**
+ * Write a cached record by key (creating the cache dir as needed). When `dir` is
+ * the default `.vigiles/eval-cache`, the recorded runs are per-checkout, so the
+ * `.vigiles/.gitignore` is kept current; a `cacheDir` the spec chose elsewhere is
+ * the author's to place and is left alone.
+ */
 export declare function writeCache(dir: string, key: SHA256Hash, record: CacheRecord): void;
 /** Snapshot the text files under `cwd` as `relativePath → contents` (bounded). */
 export declare function snapshotDir(cwd: string): Record<string, string>;

package/dist/eval-cache.js

@@ -28,6 +28,7 @@ exports.hashDir = hashDir;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const hash_js_1 = require("./core/hash.js");
+const local_files_js_1 = require("./local-files.js");
 const MAX_SNAPSHOT_FILE_BYTES = 1024 * 1024;
 const SKIP_DIRS = new Set(["node_modules", ".git"]);
 /**
@@ -113,9 +114,18 @@ function readCache(dir, key) {
         throw new Error(`eval cache: corrupt record ${path} (invalid JSON) — delete it or clear the cache dir`);
     }
 }
-/** Write a cached record by key (creating the cache dir as needed). */
+/**
+ * Write a cached record by key (creating the cache dir as needed). When `dir` is
+ * the default `.vigiles/eval-cache`, the recorded runs are per-checkout, so the
+ * `.vigiles/.gitignore` is kept current; a `cacheDir` the spec chose elsewhere is
+ * the author's to place and is left alone.
+ */
 function writeCache(dir, key, record) {
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    if ((0, node_path_1.basename)(dir) === local_files_js_1.EVAL_CACHE_DIR &&
+        (0, node_path_1.basename)((0, node_path_1.dirname)(dir)) === local_files_js_1.VIGILES_DIR) {
+        (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.dirname)(dir));
+    }
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, `${key}.json`), JSON.stringify(record));
 }
 /** Snapshot the text files under `cwd` as `relativePath → contents` (bounded). */

package/dist/eval.js

@@ -79,6 +79,7 @@ const proofs_js_1 = require("./core/proofs.js");
 const model_access_js_1 = require("./adapters/claude-code/model-access.js");
 const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
+const local_files_js_1 = require("./local-files.js");
 const eval_lock_js_1 = require("./eval-lock.js");
 const stats_js_1 = require("./stats.js");
 const check_count_js_1 = require("./check-count.js");
@@ -1331,7 +1332,7 @@ async function runEvalWith(spec, runner) {
         tools: spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"],
         timeoutMs: spec.timeoutMs ?? 240000,
         cache: spec.cache ?? "off",
-        cacheDir: spec.cacheDir ?? (0, node_path_1.resolve)(process.cwd(), ".vigiles", "eval-cache"),
+        cacheDir: spec.cacheDir ?? (0, node_path_1.resolve)(process.cwd(), local_files_js_1.VIGILES_DIR, local_files_js_1.EVAL_CACHE_DIR),
     };
     if (cfg.cache !== "off" && !isDatedModel(cfg.model)) {
         warnFloatingModel(cfg.model);

package/dist/harness-resolve-hooks.d.mts

@@ -8,6 +8,27 @@ type Resolved = {
     shortCircuit?: boolean;
 };
 type NextResolve = (specifier: string, context: ResolveContext) => Resolved | Promise<Resolved>;
+type LoadContext = {
+    format?: string | null;
+    conditions: string[];
+};
+type Loaded = {
+    format?: string | null;
+    source?: string | ArrayBuffer | ArrayBufferView | null;
+    shortCircuit?: boolean;
+};
+type NextLoad = (url: string, context: LoadContext) => Loaded | Promise<Loaded>;
+/** What the runner hands this hook for ONE child. See `run-scripts.ts`. */
+export interface LoadProbe {
+    /** The script's own module URL (realpath), whatever process entry runs it. */
+    readonly entryURL: string;
+    /** Written (empty) by the marker module when it evaluates: the graph linked. */
+    readonly loadedFile: string;
+    /** Written with `{ format, marked }` when this hook sees the script's module. */
+    readonly seenFile: string;
+}
+export declare function initialize(data: LoadProbe | undefined): void;
 export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<Resolved>;
+export declare function load(url: string, context: LoadContext, nextLoad: NextLoad): Promise<Loaded>;
 export {};
 //# sourceMappingURL=harness-resolve-hooks.d.mts.map

package/dist/harness-resolve-hooks.mjs

@@ -1,17 +1,47 @@
 /**
- * Module-resolution hook for HARNESS scripts (`vigiles test` / `vigiles eval`):
- * make a bare `vigiles` import resolve to the CLI's OWN installation.
+ * Module-customization hooks for HARNESS scripts (`vigiles test` / `vigiles eval`).
+ * Two jobs, one registration:
  *
- * The rescue itself — why it exists, what it refuses to touch — lives in
- * `./self-resolve.mjs`, because the spec host registers the same branch from
- * `./spec-hooks.mjs` and two copies of it is exactly the divergence that put
- * `test` and `compile` on different answers to the same question.
+ * 1. RESOLVE — make a bare `vigiles` import resolve to the CLI's OWN
+ *    installation. The rescue itself — why it exists, what it refuses to touch —
+ *    lives in `./self-resolve.mjs`, because the spec host registers the same
+ *    branch from `./spec-hooks.mjs` and two copies of it is exactly the
+ *    divergence that put `test` and `compile` on different answers to the same
+ *    question. What stays here is the protocol: try normal resolution first, and
+ *    only consider the rescue on the way out of the failure.
  *
- * What stays here is the hook PROTOCOL: try normal resolution first, and only
- * consider the rescue on the way out of the failure.
+ * 2. LOAD — tell the runner whether the script LOADED (#243). ESM links the
+ *    whole import graph before evaluating any of it, and evaluates a module's
+ *    imports in source order. So a marker import placed FIRST in the script's
+ *    module evaluates if and only if every module in the graph was found, parsed
+ *    and linked — and before any dependency or the script body runs. The marker
+ *    writes a file; the runner reads it. No output text is read, so a harness
+ *    that prints a loader error as EVIDENCE about the thing it tests (a hook
+ *    transcript, say) can no longer be mistaken for one that never ran.
+ *
+ * The probe paths arrive through `register(…, { data })` → `initialize`, NOT the
+ * environment, so a process the harness spawns cannot inherit them and write
+ * over its parent's answer.
  */
+import { writeFileSync } from "node:fs";
 import { resolveSelfSpecifier } from "./self-resolve.mjs";
+const MARKER_URL = "vigiles-internal:loaded";
+/**
+ * Formats the marker can be planted in. 🔴 CommonJS is deliberately absent: it
+ * has no link phase to mark (a `require` resolves while the body runs), so a CJS
+ * script carries no marker and a non-zero exit from it is conservatively a
+ * `fail` — which retracts coverage rather than hiding a real failure.
+ * `module-typescript` is Node's own type stripping (22.6+), which strips in
+ * place and so keeps positions.
+ */
+const MARKABLE = new Set(["module", "module-typescript"]);
+let probe;
+export function initialize(data) {
+    probe = data;
+}
 export async function resolve(specifier, context, nextResolve) {
+    if (probe !== undefined && specifier === MARKER_URL)
+        return { url: MARKER_URL, shortCircuit: true };
     try {
         return await nextResolve(specifier, context);
     }
@@ -24,4 +54,42 @@ export async function resolve(specifier, context, nextResolve) {
         return rescued;
     }
 }
+export async function load(url, context, nextLoad) {
+    if (probe !== undefined && url === MARKER_URL)
+        return {
+            format: "module",
+            shortCircuit: true,
+            source: `import { writeFileSync } from "node:fs"; writeFileSync(${JSON.stringify(probe.loadedFile)}, "");`,
+        };
+    const loaded = await nextLoad(url, context);
+    if (probe === undefined || url !== probe.entryURL)
+        return loaded;
+    const marked = MARKABLE.has(String(loaded.format));
+    // Written BEFORE the graph links, so its presence proves the hook saw the
+    // script. Without it a missing `loadedFile` would mean nothing: a script this
+    // hook never saw (a loader that rewrote its URL, say) is never did-not-load.
+    writeFileSync(probe.seenFile, JSON.stringify({ format: loaded.format, marked }));
+    if (!marked)
+        return loaded;
+    return { ...loaded, source: withMarker(sourceText(loaded.source)) };
+}
+function sourceText(source) {
+    if (typeof source === "string")
+        return source;
+    // `String(uint8array)` gives "1,2,3", so decode explicitly.
+    return new TextDecoder().decode(source ?? new Uint8Array());
+}
+/**
+ * Put the marker import on the file's FIRST line — after a shebang, which must
+ * stay first — so no line number moves; only columns on that one line do.
+ */
+function withMarker(src) {
+    const mark = `import ${JSON.stringify(MARKER_URL)};`;
+    if (!src.startsWith("#!"))
+        return mark + src;
+    const nl = src.indexOf("\n");
+    if (nl === -1)
+        return `${src}\n${mark}`;
+    return src.slice(0, nl + 1) + mark + src.slice(nl + 1);
+}
 //# sourceMappingURL=harness-resolve-hooks.mjs.map

package/dist/hook-runtime.js

@@ -50,6 +50,7 @@ const hook_install_js_1 = require("./hook-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const hook_state_store_js_1 = require("./hook-state-store.js");
 const observe_js_1 = require("./observe.js");
+const local_files_js_1 = require("./local-files.js");
 const load_hook_js_1 = require("./load-hook.js");
 const event_capability_js_1 = require("./core/event-capability.js");
 /**
@@ -168,8 +169,9 @@ async function loadProviderRegistry(root) {
 /** Append an observe-mode record to `.vigiles/hook-observations.jsonl` (best-effort). */
 function recordObservation(file, on, would, reason, root) {
     try {
-        const dir = (0, node_path_1.resolve)(root, ".vigiles");
+        const dir = (0, node_path_1.resolve)(root, local_files_js_1.VIGILES_DIR);
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        (0, local_files_js_1.ensureLocalFilesIgnored)(dir);
         const line = JSON.stringify({
             ts: new Date().toISOString(),
             hook: file,
@@ -177,7 +179,7 @@ function recordObservation(file, on, would, reason, root) {
             would,
             reason,
         }) + "\n";
-        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, "hook-observations.jsonl"), line);
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, local_files_js_1.HOOK_OBSERVATIONS_FILE), line);
     }
     catch {
         /* recording is best-effort — never let it break a live session */

package/dist/hook-state-store.js

@@ -57,6 +57,7 @@ const node_path_1 = require("node:path");
 const hash_js_1 = require("./core/hash.js");
 const hook_state_js_1 = require("./core/hook-state.js");
 const hook_install_js_1 = require("./hook-install.js");
+const local_files_js_1 = require("./local-files.js");
 /**
  * The directory a hook's recorded facts live in — the SCOPE of `state()`/`record()`.
  *
@@ -78,7 +79,7 @@ function hookStateDir(file, cwd = process.cwd()) {
     const dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file));
     const rel = (0, node_path_1.relative)(cwd, dir);
     const inside = rel !== "" && !rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel);
-    return (0, node_path_1.resolve)(cwd, ".vigiles/state", inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
+    return (0, node_path_1.resolve)(cwd, local_files_js_1.VIGILES_DIR, local_files_js_1.HOOK_STATE_DIR, inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
 }
 /** Read one recorded fact for a hook, or `null` if it was never recorded. */
 function readHookState(file, key, cwd = process.cwd()) {
@@ -112,6 +113,7 @@ function writeHookState(file, w, opts = {}) {
         by: (0, hook_install_js_1.normalizeHookRef)(file, cwd),
     };
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, local_files_js_1.ensureLocalFilesIgnored)((0, node_path_1.resolve)(cwd, local_files_js_1.VIGILES_DIR));
     const tmp = `${target}.${String(process.pid)}.tmp`;
     (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(entry, null, 2) + "\n");
     (0, node_fs_1.renameSync)(tmp, target);

package/dist/local-files-tracked.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The per-checkout files under `<root>/.vigiles/` that git tracks, as
+ * repo-relative paths from `root`. Empty when nothing is tracked, when `root` is
+ * not in a git work tree, or when `git` is missing — silence is the answer to
+ * every "cannot tell".
+ */
+export declare function trackedLocalFiles(root: string): string[];
+/**
+ * Does the COMMITTED `.vigiles/.gitignore` (the one at `HEAD`) lack entries
+ * vigiles needs — i.e. will vigiles' additions show up as a change to a tracked
+ * file until someone commits them.
+ *
+ * The question is asked of `HEAD`, not of the worktree's dirtiness, and that
+ * is the point (Codex review on #275, third pass). "The file is modified" was
+ * the earlier predicate; it could not tell vigiles' additions from the owner's
+ * own unrelated edit, and then advised committing work in progress. Reading the
+ * committed copy answers only for vigiles' entries, staged or not, and says
+ * nothing once they are committed, whatever else the owner is editing.
+ * `HEAD:./path`, not `HEAD:path`: without `./` git resolves the path from the
+ * REPOSITORY root, so a package nested in a larger worktree read the wrong file
+ * — or none — and stayed silent (Codex review on #275, gitrevisions(7)).
+ * Silent on every "cannot tell": not in a repo, no `HEAD`, file not committed.
+ */
+export declare function committedIgnoreFileLacksEntries(root: string): boolean;
+/**
+ * The one-line warning for {@link trackedLocalFiles}, or `null` when there is
+ * nothing to say. Files inside a tracked local DIRECTORY (`state/`,
+ * `eval-cache/`) are named by that directory, so one line stays one line and the
+ * command it prints untracks all of them.
+ */
+export declare function formatTrackedLocalFiles(tracked: readonly string[], committedLacksEntries?: boolean): string | null;
+/** Print the warning for `root` to stderr when there is one. CLI-only. */
+export declare function warnTrackedLocalFiles(root: string): void;
+//# sourceMappingURL=local-files-tracked.d.ts.map

package/dist/local-files-tracked.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackedLocalFiles = trackedLocalFiles;
+exports.committedIgnoreFileLacksEntries = committedIgnoreFileLacksEntries;
+exports.formatTrackedLocalFiles = formatTrackedLocalFiles;
+exports.warnTrackedLocalFiles = warnTrackedLocalFiles;
+/**
+ * The half `.gitignore` cannot do: tell the owner when a per-checkout file under
+ * `.vigiles/` is ALREADY tracked.
+ *
+ * `ensureLocalFilesIgnored` (`local-files.ts`) keeps new copies out of git, but
+ * an ignore rule does not untrack a file git already follows — a repo that
+ * committed `.vigiles/coverage.json` before this existed keeps committing every
+ * rewrite of it. Only the owner can fix that (`git rm --cached`), and changing
+ * the index is theirs to decide, so this reports and never acts.
+ *
+ * CLI-only, by construction: it spawns `git`, and a hook decision must never pay
+ * for a child process. That is why it is a separate module from the ignore half,
+ * which hook runtimes import.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const local_files_js_1 = require("./local-files.js");
+/** `.vigiles/.gitignore`, repo-relative. */
+const IGNORE_FILE = node_path_1.posix.join(local_files_js_1.VIGILES_DIR, local_files_js_1.LOCAL_GITIGNORE_FILE);
+/**
+ * The per-checkout files under `<root>/.vigiles/` that git tracks, as
+ * repo-relative paths from `root`. Empty when nothing is tracked, when `root` is
+ * not in a git work tree, or when `git` is missing — silence is the answer to
+ * every "cannot tell".
+ */
+function trackedLocalFiles(root) {
+    const specs = local_files_js_1.LOCAL_FILES.map((f) => node_path_1.posix.join(local_files_js_1.VIGILES_DIR, f.name));
+    try {
+        const r = (0, node_child_process_1.spawnSync)("git", ["ls-files", "-z", "--", ...specs], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.status !== 0 || typeof r.stdout !== "string")
+            return [];
+        return r.stdout.split("\0").filter((p) => p !== "");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Does the COMMITTED `.vigiles/.gitignore` (the one at `HEAD`) lack entries
+ * vigiles needs — i.e. will vigiles' additions show up as a change to a tracked
+ * file until someone commits them.
+ *
+ * The question is asked of `HEAD`, not of the worktree's dirtiness, and that
+ * is the point (Codex review on #275, third pass). "The file is modified" was
+ * the earlier predicate; it could not tell vigiles' additions from the owner's
+ * own unrelated edit, and then advised committing work in progress. Reading the
+ * committed copy answers only for vigiles' entries, staged or not, and says
+ * nothing once they are committed, whatever else the owner is editing.
+ * `HEAD:./path`, not `HEAD:path`: without `./` git resolves the path from the
+ * REPOSITORY root, so a package nested in a larger worktree read the wrong file
+ * — or none — and stayed silent (Codex review on #275, gitrevisions(7)).
+ * Silent on every "cannot tell": not in a repo, no `HEAD`, file not committed.
+ */
+function committedIgnoreFileLacksEntries(root) {
+    try {
+        const r = (0, node_child_process_1.spawnSync)("git", ["show", `HEAD:./${IGNORE_FILE}`], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.status !== 0 || typeof r.stdout !== "string")
+            return false;
+        return (0, local_files_js_1.entriesNotInEffect)(r.stdout).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The one-line warning for {@link trackedLocalFiles}, or `null` when there is
+ * nothing to say. Files inside a tracked local DIRECTORY (`state/`,
+ * `eval-cache/`) are named by that directory, so one line stays one line and the
+ * command it prints untracks all of them.
+ */
+function formatTrackedLocalFiles(tracked, committedLacksEntries = false) {
+    const lines = [];
+    if (tracked.length > 0) {
+        // `.vigiles/state/.claude/hooks/x.json` → `.vigiles/state`: the list entry.
+        const entries = [
+            ...new Set(tracked.map((p) => p.split("/").slice(0, 2).join("/"))),
+        ];
+        const one = entries.length === 1;
+        lines.push(`⚠ ${entries.join(", ")} ${one ? "is" : "are"} tracked by git, but ` +
+            `${local_files_js_1.VIGILES_DIR}/ local files describe one checkout and would credit a ` +
+            `machine where nothing ran. .gitignore does not untrack a tracked file; ` +
+            `untrack ${one ? "it" : "them"} once: git rm -r --cached ${entries.join(" ")}`);
+    }
+    // Not "untrack it": the repo may keep its own rules there, and untracking
+    // would take them away from everyone else.
+    if (committedLacksEntries)
+        lines.push(`⚠ ${IGNORE_FILE} is tracked by git and its committed version lacks ` +
+            `vigiles' local-file entries, which vigiles adds to your copy. Commit ` +
+            `those lines once; entries are appended only when missing.`);
+    return lines.length > 0 ? lines.join("\n") : null;
+}
+/** Print the warning for `root` to stderr when there is one. CLI-only. */
+function warnTrackedLocalFiles(root) {
+    const line = formatTrackedLocalFiles(trackedLocalFiles(root), committedIgnoreFileLacksEntries(root));
+    if (line)
+        process.stderr.write(line + "\n");
+}
+//# sourceMappingURL=local-files-tracked.js.map

package/dist/local-files.d.ts

@@ -0,0 +1,71 @@
+/** vigiles's own directory in a project. */
+export declare const VIGILES_DIR = ".vigiles";
+/** The execution tier of coverage (`coverage-artifact.ts`). */
+export declare const COVERAGE_ARTIFACT_FILE = "coverage.json";
+/** The flight-recorder ledger (`observe.ts`). */
+export declare const LEDGER_FILE = "runs.jsonl";
+/** Compiled hooks' named state, `record()`/`state()` (`hook-state-store.ts`). */
+export declare const HOOK_STATE_DIR = "state";
+/** The skill in progress (`adapters/claude-code/skill-runtime.ts`). */
+export declare const ACTIVE_SKILL_FILE = "active-skill.json";
+/** The subagent stack in progress (`adapters/claude-code/agent-runtime.ts`). */
+export declare const ACTIVE_AGENT_FILE = "active-agent.json";
+/** Inside-an-effect-boundary marker (`adapters/claude-code/effect-region.ts`). */
+export declare const EFFECT_ACTIVE_FILE = "effect-active.json";
+/** The calls a guard allowed this session (`core/guards.ts`). */
+export declare const GUARD_LEDGER_FILE = "guard-ledger.json";
+/** What an `observe`-mode hook would have blocked (`hook-runtime.ts`). */
+export declare const HOOK_OBSERVATIONS_FILE = "hook-observations.jsonl";
+/** Recorded model runs for eval replay, the default `cacheDir` (`eval.ts`). */
+export declare const EVAL_CACHE_DIR = "eval-cache";
+/** One per-checkout path under `.vigiles/`. */
+export interface LocalFile {
+    /** The name directly under `.vigiles/`. */
+    readonly name: string;
+    /** A directory (its whole subtree is local) rather than a single file. */
+    readonly dir: boolean;
+}
+/** Every per-checkout path vigiles writes under `.vigiles/`. The one list. */
+export declare const LOCAL_FILES: readonly LocalFile[];
+/**
+ * The names under `.vigiles/` that ARE the project's and must stay committable.
+ * Not used at runtime — it is the other half of the classification the guard in
+ * `local-files.test.ts` holds the source to, and the list that test checks is
+ * NOT ignored.
+ */
+export declare const COMMITTED_PATHS: readonly string[];
+/** The header comment on a `.vigiles/.gitignore` vigiles creates. */
+/** The ignore file vigiles keeps inside `.vigiles/`. One spelling for every reader. */
+export declare const LOCAL_GITIGNORE_FILE = ".gitignore";
+export declare const LOCAL_GITIGNORE_HEADER: readonly string[];
+/** The ignore lines, in order: every local path, then the file itself. */
+export declare function localIgnoreEntries(): string[];
+/**
+ * Keep `<vigilesDir>/.gitignore` listing every local path. Call it where a
+ * local file is written — not from `vigiles init`, which a project may never
+ * run, while the write always happens.
+ *
+ * - Absent → created with {@link LOCAL_GITIGNORE_HEADER} and every entry.
+ * - Every entry IN EFFECT → not touched (no rewrite, no mtime change).
+ * - Otherwise the entries not in effect are appended and nothing is removed
+ *   or reordered. Appending is enough because git's last matching rule wins.
+ *
+ * "In effect" is judged the way git reads the file, not by text membership:
+ * lines in order, a later negation cancels an earlier `/entry` (see
+ * {@link inEffect}), and leading whitespace is part of the pattern (only
+ * trailing whitespace is dropped).
+ * Both cases were measured with `git check-ignore`: `/coverage.json` followed
+ * by `!/coverage.json`, and ` /coverage.json`, each leave the file NOT
+ * ignored while a trimmed set would call the entry present.
+ *
+ * Costs one read on the hot path. Best-effort: any fs error is swallowed —
+ * keeping git tidy must never break a hook, a test run or an audit.
+ */
+/**
+ * The entries a `.vigiles/.gitignore` with this content does NOT put in effect.
+ * One reader for both questions — "what to append" ({@link ensureLocalFilesIgnored})
+ * and "does the committed copy already carry them" (the CLI's tracked-file check).
+ */
+export declare function entriesNotInEffect(content: string): string[];
+export declare function ensureLocalFilesIgnored(vigilesDir: string): void;
+//# sourceMappingURL=local-files.d.ts.map

package/dist/local-files.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_GITIGNORE_HEADER = exports.LOCAL_GITIGNORE_FILE = exports.COMMITTED_PATHS = exports.LOCAL_FILES = exports.EVAL_CACHE_DIR = exports.HOOK_OBSERVATIONS_FILE = exports.GUARD_LEDGER_FILE = exports.EFFECT_ACTIVE_FILE = exports.ACTIVE_AGENT_FILE = exports.ACTIVE_SKILL_FILE = exports.HOOK_STATE_DIR = exports.LEDGER_FILE = exports.COVERAGE_ARTIFACT_FILE = exports.VIGILES_DIR = void 0;
+exports.localIgnoreEntries = localIgnoreEntries;
+exports.entriesNotInEffect = entriesNotInEffect;
+exports.ensureLocalFilesIgnored = ensureLocalFilesIgnored;
+/**
+ * The files vigiles writes into a project's `.vigiles/` that describe ONE
+ * checkout on ONE machine — and the `.gitignore` that keeps them out of git.
+ *
+ * `.vigiles/` holds two kinds of file. Some are the project's own and are
+ * committed: hook sources and their stamps (`hooks/`), eval locks
+ * (`eval-locks/`), providers, the eval baseline, spec sidecars. The rest are a
+ * record of what happened HERE — which run exercised which surface, which skill
+ * is active right now, when a throttled hook last spoke — and committing one
+ * transplants that record onto a machine where none of it happened. A committed
+ * `coverage.json` credits coverage nobody ran; a committed `state/` silences a
+ * teammate's hook for a window they never saw; a committed `guard-ledger.json`
+ * satisfies a `requireBefore` guard with a prerequisite someone else ran.
+ *
+ * ## Why this file exists
+ *
+ * The rule "do not commit these" lived as one sentence in
+ * `docs/rules/untested-skill.md`, and vigiles honoured it only in its OWN repo's
+ * root `.gitignore`. Consumers committed them anyway: two repos carried
+ * `.vigiles/coverage.json` for weeks, one built a `merge=ours` git driver to
+ * paper over the conflicts it caused, and the other shipped `coverage.json` and
+ * `runs.jsonl` inside its npm tarball. A rule that exists only as prose enforces
+ * nothing, so the writer now enforces it where the write happens.
+ *
+ * ## The mechanism: a `.gitignore` INSIDE `.vigiles/`
+ *
+ * Tools that keep local state in a project leave the project's root
+ * `.gitignore` alone and drop one inside their own directory — `ruff` writes
+ * `.ruff_cache/.gitignore` containing `*`. `*` is wrong here, because the same
+ * directory holds committed files, so the file lists the local paths instead,
+ * each anchored with a leading `/` so it cannot match a same-named file deeper
+ * down. It also lists ITSELF, like ruff's `*` covers its own file: it then
+ * leaves no footprint in the project's history and never churns on upgrade.
+ *
+ * `.gitignore` does not untrack a file that is already tracked. That half is
+ * `local-files-tracked.ts`, which runs from the CLI only — it spawns `git`, and
+ * nothing here may, because {@link ensureLocalFilesIgnored} is called from hook
+ * runtimes on the decision path.
+ *
+ * ## One list, and the constants live IN it
+ *
+ * Every writer imports its file name from here rather than spelling it, so a
+ * name cannot drift from the ignore entry. The constants were defined in their
+ * writer modules before; the direction is inverted on purpose. With the list
+ * importing from the writers, each writer would import this module back (for
+ * the ensure call), a cycle in which a top-level list reads a `const` still in
+ * its temporal dead zone — and a hook deciding a `Bash` call would load
+ * `eval.ts` and `coverage-artifact.ts` just to learn two file names. This module
+ * imports nothing from the package, so every writer can depend on it for free.
+ * `local-files.test.ts` guards the other direction: every `.vigiles/` path the
+ * source spells must be either on this list or on {@link COMMITTED_PATHS}.
+ *
+ * Node-only (it reads and writes a file).
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** vigiles's own directory in a project. */
+exports.VIGILES_DIR = ".vigiles";
+/** The execution tier of coverage (`coverage-artifact.ts`). */
+exports.COVERAGE_ARTIFACT_FILE = "coverage.json";
+/** The flight-recorder ledger (`observe.ts`). */
+exports.LEDGER_FILE = "runs.jsonl";
+/** Compiled hooks' named state, `record()`/`state()` (`hook-state-store.ts`). */
+exports.HOOK_STATE_DIR = "state";
+/** The skill in progress (`adapters/claude-code/skill-runtime.ts`). */
+exports.ACTIVE_SKILL_FILE = "active-skill.json";
+/** The subagent stack in progress (`adapters/claude-code/agent-runtime.ts`). */
+exports.ACTIVE_AGENT_FILE = "active-agent.json";
+/** Inside-an-effect-boundary marker (`adapters/claude-code/effect-region.ts`). */
+exports.EFFECT_ACTIVE_FILE = "effect-active.json";
+/** The calls a guard allowed this session (`core/guards.ts`). */
+exports.GUARD_LEDGER_FILE = "guard-ledger.json";
+/** What an `observe`-mode hook would have blocked (`hook-runtime.ts`). */
+exports.HOOK_OBSERVATIONS_FILE = "hook-observations.jsonl";
+/** Recorded model runs for eval replay, the default `cacheDir` (`eval.ts`). */
+exports.EVAL_CACHE_DIR = "eval-cache";
+/** Every per-checkout path vigiles writes under `.vigiles/`. The one list. */
+exports.LOCAL_FILES = [
+    { name: exports.COVERAGE_ARTIFACT_FILE, dir: false },
+    { name: exports.LEDGER_FILE, dir: false },
+    { name: exports.HOOK_STATE_DIR, dir: true },
+    { name: exports.ACTIVE_SKILL_FILE, dir: false },
+    { name: exports.ACTIVE_AGENT_FILE, dir: false },
+    { name: exports.EFFECT_ACTIVE_FILE, dir: false },
+    { name: exports.GUARD_LEDGER_FILE, dir: false },
+    { name: exports.HOOK_OBSERVATIONS_FILE, dir: false },
+    { name: exports.EVAL_CACHE_DIR, dir: true },
+];
+/**
+ * The names under `.vigiles/` that ARE the project's and must stay committable.
+ * Not used at runtime — it is the other half of the classification the guard in
+ * `local-files.test.ts` holds the source to, and the list that test checks is
+ * NOT ignored.
+ */
+exports.COMMITTED_PATHS = [
+    "hooks", // hook sources + their stamps (`hook-install.ts`)
+    "providers", // registered hook-context providers
+    "eval-locks", // committed eval staleness stamps (`eval-lock.ts`)
+    "eval-baseline.json", // the committed regression baseline (`eval-baseline.ts`)
+    "generated.d.ts", // linter-rule types for specs (`vigiles init` / `generate types`)
+    "schema.json", // YAML-LSP frontmatter schema (`vigiles init`)
+    "guards.json", // the declared guard set (`core/guards.ts`)
+    "action-gates.json", // declared action gates (`action-gate.ts`)
+];
+/** The header comment on a `.vigiles/.gitignore` vigiles creates. */
+/** The ignore file vigiles keeps inside `.vigiles/`. One spelling for every reader. */
+exports.LOCAL_GITIGNORE_FILE = ".gitignore";
+exports.LOCAL_GITIGNORE_HEADER = [
+    "# Written by vigiles. These files describe one checkout on one machine and are",
+    "# never committed. Everything else in .vigiles/ is the project's: commit it.",
+];
+/** The ignore lines, in order: every local path, then the file itself. */
+function localIgnoreEntries() {
+    return [
+        ...exports.LOCAL_FILES.map((f) => `/${f.name}${f.dir ? "/" : ""}`),
+        `/${exports.LOCAL_GITIGNORE_FILE}`,
+    ];
+}
+/**
+ * Is `entry` ignoring its path after git reads `lines` top to bottom.
+ *
+ * Conservative on purpose: ANY negation after the entry's last occurrence counts
+ * as cancelling it. Git re-includes on `!/coverage.json`, but equally on
+ * `!coverage.json` or `!*.json` (last matching pattern wins), and matching
+ * gitignore globs here would be a second, partial implementation of git. The
+ * cost of being conservative is one extra append after an unrelated negation;
+ * the next call finds the entries last and leaves the file alone.
+ */
+function inEffect(lines, entry) {
+    let on = false;
+    for (const line of lines) {
+        if (line === entry)
+            on = true;
+        else if (line.startsWith("!"))
+            on = false;
+    }
+    return on;
+}
+/**
+ * Keep `<vigilesDir>/.gitignore` listing every local path. Call it where a
+ * local file is written — not from `vigiles init`, which a project may never
+ * run, while the write always happens.
+ *
+ * - Absent → created with {@link LOCAL_GITIGNORE_HEADER} and every entry.
+ * - Every entry IN EFFECT → not touched (no rewrite, no mtime change).
+ * - Otherwise the entries not in effect are appended and nothing is removed
+ *   or reordered. Appending is enough because git's last matching rule wins.
+ *
+ * "In effect" is judged the way git reads the file, not by text membership:
+ * lines in order, a later negation cancels an earlier `/entry` (see
+ * {@link inEffect}), and leading whitespace is part of the pattern (only
+ * trailing whitespace is dropped).
+ * Both cases were measured with `git check-ignore`: `/coverage.json` followed
+ * by `!/coverage.json`, and ` /coverage.json`, each leave the file NOT
+ * ignored while a trimmed set would call the entry present.
+ *
+ * Costs one read on the hot path. Best-effort: any fs error is swallowed —
+ * keeping git tidy must never break a hook, a test run or an audit.
+ */
+/**
+ * The entries a `.vigiles/.gitignore` with this content does NOT put in effect.
+ * One reader for both questions — "what to append" ({@link ensureLocalFilesIgnored})
+ * and "does the committed copy already carry them" (the CLI's tracked-file check).
+ */
+function entriesNotInEffect(content) {
+    const lines = content.split(/\r?\n/).map((l) => l.replace(/\s+$/, ""));
+    return localIgnoreEntries().filter((e) => !inEffect(lines, e));
+}
+function ensureLocalFilesIgnored(vigilesDir) {
+    try {
+        const file = (0, node_path_1.resolve)(vigilesDir, exports.LOCAL_GITIGNORE_FILE);
+        const entries = localIgnoreEntries();
+        let current;
+        try {
+            current = (0, node_fs_1.readFileSync)(file, "utf-8");
+        }
+        catch {
+            current = undefined;
+        }
+        if (current === undefined) {
+            (0, node_fs_1.mkdirSync)(vigilesDir, { recursive: true });
+            (0, node_fs_1.writeFileSync)(file, [...exports.LOCAL_GITIGNORE_HEADER, ...entries, ""].join("\n"));
+            return;
+        }
+        const missing = entriesNotInEffect(current);
+        if (missing.length === 0)
+            return;
+        const header = current.split(/\r?\n/).includes(exports.LOCAL_GITIGNORE_HEADER[0])
+            ? []
+            : exports.LOCAL_GITIGNORE_HEADER;
+        const sep = current === "" || current.endsWith("\n") ? "" : "\n";
+        (0, node_fs_1.appendFileSync)(file, sep + [...header, ...missing, ""].join("\n"));
+    }
+    catch {
+        /* best-effort — an unwritable .vigiles/ is not a failure of anything */
+    }
+}
+//# sourceMappingURL=local-files.js.map

package/dist/observe.d.ts

@@ -1,7 +1,8 @@
+import { LEDGER_FILE } from "./local-files.js";
 /** Bumped when the record shape changes in a non-additive way. */
 export declare const OBSERVE_VERSION = 1;
-/** The ledger filename under the `.vigiles/` directory. */
-export declare const LEDGER_FILE = "runs.jsonl";
+/** The ledger filename under the `.vigiles/` directory — defined on the one local-files list. */
+export { LEDGER_FILE };
 /** Fields every record carries; `v`/`ts` are stamped by the writer, not the caller. */
 export interface ObservationBase {
     /** schema version (`OBSERVE_VERSION`) */

package/dist/observe.js

@@ -24,10 +24,10 @@ exports.formatLedgerSummary = formatLedgerSummary;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const local_files_js_1 = require("./local-files.js");
+Object.defineProperty(exports, "LEDGER_FILE", { enumerable: true, get: function () { return local_files_js_1.LEDGER_FILE; } });
 /** Bumped when the record shape changes in a non-additive way. */
 exports.OBSERVE_VERSION = 1;
-/** The ledger filename under the `.vigiles/` directory. */
-exports.LEDGER_FILE = "runs.jsonl";
 /** Serialize one record to a single JSONL line (trailing newline included). */
 function formatObservation(record) {
     return JSON.stringify(record) + "\n";
@@ -39,14 +39,15 @@ function formatObservation(record) {
  */
 function appendObservation(input, cwd = process.cwd()) {
     try {
-        const dir = (0, node_path_1.resolve)(cwd, ".vigiles");
+        const dir = (0, node_path_1.resolve)(cwd, local_files_js_1.VIGILES_DIR);
         (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        (0, local_files_js_1.ensureLocalFilesIgnored)(dir);
         const record = {
             v: exports.OBSERVE_VERSION,
             ts: new Date().toISOString(),
             ...input,
         };
-        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, exports.LEDGER_FILE), formatObservation(record));
+        (0, node_fs_1.appendFileSync)((0, node_path_1.resolve)(dir, local_files_js_1.LEDGER_FILE), formatObservation(record));
     }
     catch {
         /* best-effort — recording is never allowed to break a session */
@@ -59,7 +60,7 @@ function appendObservation(input, cwd = process.cwd()) {
 function readObservations(cwd = process.cwd()) {
     let raw;
     try {
-        raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, ".vigiles", exports.LEDGER_FILE), "utf8");
+        raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, local_files_js_1.VIGILES_DIR, local_files_js_1.LEDGER_FILE), "utf8");
     }
     catch {
         return [];
@@ -129,7 +130,7 @@ function formatLedgerSummary(records, committedLocks) {
     if (records.length === 0)
         return "";
     const lines = [
-        `Flight recorder — ${records.length} record${records.length === 1 ? "" : "s"} in .vigiles/${exports.LEDGER_FILE}`,
+        `Flight recorder — ${records.length} record${records.length === 1 ? "" : "s"} in .vigiles/${local_files_js_1.LEDGER_FILE}`,
     ];
     const counts = new Map();
     for (const r of records)

package/package.json

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