vigiles 30.0.1 → 31.0.0

package/dist/adapter-conformance.js

@@ -14,8 +14,7 @@ exports.assertAdapterLoadsHooks = assertAdapterLoadsHooks;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const compile_js_1 = require("./core/compile.js");
-const spec_js_1 = require("./core/spec.js");
+const tool_contract_js_1 = require("./core/tool-contract.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
 const vocabulary_consistency_js_1 = require("./core/vocabulary-consistency.js");
 const event_capability_js_1 = require("./core/event-capability.js");
@@ -190,21 +189,16 @@ function checkAdapterConformance(adapter) {
     catch (e) {
         need(false, `layout.settings ("${adapter.layout.settings.label}") threw on its own output: ${String(e)}`);
     }
-    // Behavioural: the dialect drives the compiler — its own built-in tool must
-    // pass the subagent tool-contract check under this dialect.
+    // Behavioural: the dialect drives the subagent tool-contract check — its own built-in tool
+    // must pass that check under this dialect. This calls the SAME validator `compileAgent` uses
+    // (`verifyToolContract` + `authoringIssues`) rather than `compileAgent` itself: the tool
+    // contract is what this line claims to check, and compiling a whole agent would tie this
+    // synchronous public kit to the compiler's (async) reference validation for nothing.
     const tool = adapter.dialect.builtinAgentTools[0];
     if (tool) {
-        const spec = (0, spec_js_1.experimental_agent)({
-            name: "conformance",
-            description: "conformance probe",
-            tools: [tool],
-            body: "probe",
-        });
-        const r = (0, compile_js_1.compileAgent)(spec, {
-            specFile: "conformance.md.spec.ts",
-            dialect: adapter.dialect,
-        });
-        need(!r.errors.some((e) => e.type === "unknown-tool"), `dialect rejects its own built-in tool "${tool}"`);
+        const issues = (0, tool_contract_js_1.authoringIssues)((0, tool_contract_js_1.verifyToolContract)([tool], adapter.dialect));
+        need(issues.length === 0, `dialect rejects its own built-in tool "${tool}"` +
+            (issues.length ? `: ${issues.map((i) => i.message).join("; ")}` : ""));
     }
     return { ok: failures.length === 0, failures };
 }

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/claude-code.js

@@ -15,6 +15,11 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatSelectionReport = exports.assertNoCollision = exports.measureSelectionMatrix = exports.agent = exports.experimental_skill = exports.experimental_agent = exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
+// 🔴 PUBLIC ENTRY POINT `vigiles/claude-code` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-claude-code.api.md`, which
+// `npm run api:check` fails on.
 /**
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin

package/dist/cli-main.js

@@ -39,6 +39,7 @@ 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");
@@ -334,9 +335,9 @@ function compileGeneratorSkillToFile(specPath, source) {
     return false;
 }
 /** Compile a ClaudeSpec → its primary + any additional targets. */
-function compileClaudeToFile(spec, specPath, config, dialect) {
+async function compileClaudeToFile(spec, specPath, config, dialect) {
     const basePath = process.cwd();
-    const { markdown, errors, warnings, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
+    const { markdown, errors, warnings, linterResults, targets } = await (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
         dialect,
@@ -470,9 +471,9 @@ function formatArtifactSize(markdown) {
     return `${size} · ~${String(kTokens)}k tokens est.`;
 }
 /** Compile a declarative SkillSpec → SKILL.md. */
-function compileSkillToFile(spec, specPath, dialect) {
+async function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { artifact, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
+    const { artifact, errors, warnings } = await (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
@@ -494,9 +495,9 @@ function compileSkillToFile(spec, specPath, dialect) {
     return false;
 }
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
-function compileAgentToFile(spec, specPath, dialect) {
+async function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { artifact, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
+    const { artifact, errors, warnings } = await (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         dialect,
@@ -591,7 +592,7 @@ async function compile(specPaths, config, excludes, opts = {}) {
             const specDialect = opts.harnessFlag === undefined
                 ? ((0, adapter_registry_js_1.adapterForInstructionFile)(targetFile)?.dialect ?? dialect)
                 : dialect;
-            if (compileClaudeToFile(spec, specPath, config, specDialect)) {
+            if (await compileClaudeToFile(spec, specPath, config, specDialect)) {
                 writeInstructionMirrors(specPath.replace(/\.spec\.ts$/, ""), declaredHarnesses);
             }
             else {
@@ -607,11 +608,11 @@ async function compile(specPaths, config, excludes, opts = {}) {
             for (const w of (0, skill_harness_js_1.skillFrontmatterDropWarnings)(spec, forHarnesses)) {
                 console.log(`⚠ ${w}`);
             }
-            if (!compileSkillToFile(spec, specPath, dialect))
+            if (!(await compileSkillToFile(spec, specPath, dialect)))
                 allValid = false;
         }
         else if (spec._specType === "agent") {
-            if (!compileAgentToFile(spec, specPath, dialect))
+            if (!(await compileAgentToFile(spec, specPath, dialect)))
                 allValid = false;
         }
         else if (spec._specType === "railway") {
@@ -820,7 +821,7 @@ async function findDuplicateRules(excludes, threshold = 0.3, silent = false, sco
  * Each named file is parsed on demand; there is no project-wide index. Returns
  * the count of broken references.
  */
-function verifyMarkdownSymbols(files, silent) {
+async function verifyMarkdownSymbols(files, silent) {
     if (files.length === 0)
         return 0;
     const cwd = process.cwd();
@@ -834,7 +835,7 @@ function verifyMarkdownSymbols(files, silent) {
         catch {
             continue;
         }
-        const broken = (0, refs_js_1.verifySymbolRefs)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, f)));
+        const broken = await (0, refs_js_1.verifySymbolRefs)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, f)));
         if (broken.length === 0)
             continue;
         if (!silent) {
@@ -1360,7 +1361,7 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
             // collected lazily so a repo with no railway spec never pays for the walk.
             if (spec._specType === "railway")
                 knownAgents ??= await collectAgentNames(excludes);
-            const errors = specCompileErrors(spec, specPath, dialect, config, knownAgents ?? []);
+            const errors = await specCompileErrors(spec, specPath, dialect, config, knownAgents ?? []);
             for (const e of errors)
                 found.push(`${target}: ${e.message} (from ${specPath})`);
         }
@@ -1398,11 +1399,11 @@ async function checkSpecRefs(excludes, config, silent, dialect) {
  * only the options differ. Exhaustive over `_specType`, so a FIFTH spec type is
  * a tsc error here instead of a silent skip, which is the failure this closes.
  */
-function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
+async function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
     const basePath = process.cwd();
     switch (spec._specType) {
         case "claude":
-            return (0, compile_js_1.compileClaude)(spec, {
+            return (await (0, compile_js_1.compileClaude)(spec, {
                 basePath,
                 specFile: specPath,
                 dialect,
@@ -1411,13 +1412,11 @@ function specCompileErrors(spec, specPath, dialect, config, knownAgents) {
                 maxSectionLines: config?.maxSectionLines,
                 catalogOnly: config?.catalogOnly,
                 linters: config?.linters,
-            }).errors;
+            })).errors;
         case "skill":
-            return (0, compile_js_1.compileSkill)(spec, { basePath, specFile: specPath, dialect })
-                .errors;
+            return (await (0, compile_js_1.compileSkill)(spec, { basePath, specFile: specPath, dialect })).errors;
         case "agent":
-            return (0, compile_js_1.compileAgent)(spec, { basePath, specFile: specPath, dialect })
-                .errors;
+            return (await (0, compile_js_1.compileAgent)(spec, { basePath, specFile: specPath, dialect })).errors;
         case "railway":
             return (0, compile_js_1.compileRailway)(spec, { specFile: specPath, knownAgents }).errors;
         default:
@@ -1724,7 +1723,7 @@ async function runLint(restArgs, flags, excludes, config) {
         }
     }
     // 9. Verify code-shaped symbol references live (see src/refs.ts).
-    const symbolRefErrors = verifyMarkdownSymbols(files, silent);
+    const symbolRefErrors = await verifyMarkdownSymbols(files, silent);
     // 10. Verify `vigiles:mcp server#tool` marks against live MCP servers
     // (only when a .mcp.json declares them). See src/mcp.ts.
     const mcpRefErrors = await verifyMarkdownMcpRefs(files, silent);
@@ -4915,6 +4914,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
@@ -4930,9 +4944,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,11 +5053,13 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     // a flag: the run already happened, and this is the runner recording what it
     // saw — the same shape as the flight-recorder ledger it already appends to.
     recordRunCoverage(cwd, results, kind, harnessFlagFrom(args));
-    // 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.
-    (0, local_files_tracked_js_1.warnTrackedLocalFiles)(cwd);
     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
@@ -5047,20 +5067,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
@@ -5071,6 +5094,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")) {
@@ -5621,7 +5646,7 @@ async function handleHookRuntime(kind, restArgs) {
             actionHookCommand();
             return;
         case "refs":
-            refsHookCommand();
+            await refsHookCommand();
             return;
         case "eval-lock-nudge":
             evalLockNudgeHookCommand();
@@ -5770,7 +5795,7 @@ function evalLockNudgeHookCommand() {
  * agent mark its references, at write time, with full context. `vigiles:ignore`
  * opts a prose span out.
  */
-function refsHookCommand() {
+async function refsHookCommand() {
     let raw = "";
     try {
         raw = (0, node_fs_1.readFileSync)(0, "utf-8");
@@ -5803,7 +5828,7 @@ function refsHookCommand() {
     catch {
         return;
     }
-    const issues = (0, refs_js_1.collectRefIssues)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file)));
+    const issues = await (0, refs_js_1.collectRefIssues)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file)));
     const action = (0, refs_js_1.refsHookAction)(issues.length, severity);
     if (action === "ok")
         return;

package/dist/codex.js

@@ -14,6 +14,11 @@ 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 });
+// 🔴 PUBLIC ENTRY POINT `vigiles/codex` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-codex.api.md`, which
+// `npm run api:check` fails on.
 /**
  * `vigiles/codex` — the OpenAI Codex harness adapter. Sits beside
  * `vigiles/claude-code`: same harness-agnostic `vigiles` testing core, a

package/dist/core/compile.d.ts

@@ -63,7 +63,7 @@ export interface CompileError {
 export declare function validateFileRef(filePath: string, basePath: string): CompileError | null;
 export declare function readPackageScripts(basePath: string): Record<string, string> | null;
 export declare function validateCommandRef(command: string, basePath: string): CompileError | null;
-export declare function validateSymbolRef(file: string, name: string, basePath: string): CompileError | null;
+export declare function validateSymbolRef(file: string, name: string, basePath: string): Promise<CompileError | null>;
 export declare function validateDirRef(dirPath: string, basePath: string): CompileError | null;
 export declare function validateGlobRef(pattern: string, basePath: string): CompileError | null;
 export interface CompileClaudeResult {
@@ -142,7 +142,7 @@ export declare const DEFAULT_MAX_SECTION_CHARS = 15000;
  * Returns the compiled markdown, validation errors, and linter check results.
  * The markdown is generated even if there are errors (with warnings).
  */
-export declare function compileClaude(spec: ClaudeSpec, options?: CompileClaudeOptions): CompileClaudeResult;
+export declare function compileClaude(spec: ClaudeSpec, options?: CompileClaudeOptions): Promise<CompileClaudeResult>;
 export interface CompileSkillResult {
     /**
      * The stamped artifact — present ONLY when `errors` is empty. `null` is what
@@ -163,7 +163,7 @@ export declare function compileSkill(spec: SkillSpec, options?: {
     /** The harness dialect — supplies `skillFrontmatterKeys`. Omitting it emits
      *  every key the compiler can render, so existing callers are unchanged. */
     dialect?: HarnessDialect;
-}): CompileSkillResult;
+}): Promise<CompileSkillResult>;
 export interface CompileAgentResult {
     /**
      * The stamped artifact — present ONLY when `errors` is empty. `null` is what
@@ -186,7 +186,7 @@ export declare function compileAgent(spec: AgentSpec, options: {
     /** The harness dialect to verify the tool contract against (required — the
      *  core defines no default dialect; the adapter/composition root injects it). */
     dialect: HarnessDialect;
-}): CompileAgentResult;
+}): Promise<CompileAgentResult>;
 export interface CompileRailwayOptions {
     /** Names of compiled agents, to resolve `delegate` targets. Skipped if omitted. */
     knownAgents?: readonly string[];
@@ -230,5 +230,5 @@ export interface AdoptResult {
  * Compare a generated file against what the spec would produce.
  * Returns the diff so users can see what was manually changed.
  */
-export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string, dialect: HarnessDialect): AdoptResult;
+export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string, dialect: HarnessDialect): Promise<AdoptResult>;
 //# sourceMappingURL=compile.d.ts.map