vigiles 26.0.1 → 26.2.0

package/dist/run-script.d.ts

@@ -137,6 +137,62 @@ export interface RunScriptDeps {
     /** Run the command confined with an allowlisted-egress netns. */
     readonly egress: ScriptSpawner;
 }
+/**
+ * True when the exit code is the shell's own report that it never reached the
+ * program — so nothing of the harness ran and no surface may be credited.
+ *
+ * 🔴 THE NUMBERS ARE MEASURED, NOT CITED. 126/127 are POSIX *conventions*; what
+ * matters is what `spawnSync(cmd, { shell: true })` actually returns here.
+ * Measured 2026-08-12, `/bin/sh` → dash (Debian), each case a real file:
+ *
+ * ```
+ *  126 | direct non-executable    | ./noexec.sh      | out=""    | Permission denied
+ *  127 | direct missing           | ./missing.sh     | out=""    | not found
+ *  127 | bare unknown command     | nosuchcmd-xyz    | out=""    | not found
+ *  127 | bad shebang (exists+x)   | ./badshebang.sh  | out=""    | env: 'nosuchinterp'
+ *  126 | is a directory           | ./               | out=""    | Permission denied
+ *    3 | real hook, exit 3        | ./exit3.sh       | out="ran" |
+ *    0 | real hook, exit 0        | ./ok.sh          | out="ran" |
+ * ```
+ *
+ * The exposure this closes: a harness may legitimately assert that a hook is
+ * NOT executable (`assert.equal(runHook("./hooks/a.sh").exitCode, 126)`). That
+ * test passes, records a check — and the unconditional probe used to credit
+ * `hooks/a.sh` with an execution-tier record although only `/bin/sh` ran. The
+ * file exists and IS a discovered surface, so `resolveProbe` resolves it happily.
+ *
+ * ⚠️ TWO SHAPES ARE DELIBERATELY MISSED, both toward SILENCE (a missed probe
+ * costs one coverage line; a false grant costs the claim). Measured, same run:
+ *
+ * ```
+ *    2 | sh + missing             | sh ./missing.sh          | out=""    | cannot open
+ *    0 | sh + non-executable      | sh ./noexec.sh           | out="ran" |
+ *    0 | bash + non-executable    | bash ./noexec.sh         | out="ran" |
+ *  127 | ran, THEN failed to launch| ./ok.sh && ./missing.sh | out="ran" |
+ * ```
+ *
+ *  - `sh <missing>` exits **2** under dash, which is Claude Code's BLOCK code —
+ *    indistinguishable from a gate legitimately denying, so it cannot be encoded.
+ *    It is also mostly moot: a path that does not exist was never discovered as a
+ *    surface, and `resolveProbe` matches only discovered surfaces.
+ *  - `sh <file>` / `bash <file>` on a non-executable file exit **0 and print
+ *    "ran"** — the interpreter reads the file as an argument, so the exec bit is
+ *    irrelevant and the hook genuinely EXECUTED. Those must keep attributing, and
+ *    do.
+ *  - A compound whose last leaf fails to launch reports 126/127 for the whole
+ *    line even though an earlier leaf ran. We abstain: silence, not a false grant.
+ *
+ * A hook that deliberately exits 126/127 itself is missed the same way, and the
+ * same direction.
+ *
+ * @internal Exported so the guard sweep asks the SAME question rather than
+ * re-deriving it (one-detector-no-drift). It reads these codes for the opposite
+ * purpose — not "may I credit this file with coverage?" but "may I score this
+ * guard at all?" — and the answer is the same fact: the shell never reached the
+ * program, so nothing the exit code says is the program's opinion. Not part of
+ * the public API.
+ */
+export declare function shellNeverLaunched(status: number | null | undefined): boolean;
 /**
  * The run orchestration with injectable spawn seams: pick direct vs. confined
  * via the safe-by-default policy (`decideSandbox`), then assemble the result.
@@ -144,6 +200,44 @@ export interface RunScriptDeps {
  * with fake spawners — no real bwrap.
  */
 export declare function runScriptWith(command: string, stdin: string, opts: RunScriptOptions, deps: RunScriptDeps): ScriptRunResult;
+/**
+ * Which of the three ways to start a script this run gets — or the refusal.
+ *
+ * 🔴 THE ONE PLACE THAT DECIDES, because a SECOND place that decided the same
+ * thing got it wrong. `experimental_verifyPluginGuards` must know whether a run
+ * will be confined BEFORE it runs anything: a confined run starts in a fresh
+ * empty directory, so a relative script that exists here will not exist there,
+ * and an interpreter that cannot open its script exits 2 — this harness's DENY
+ * code — which is then scored as a block. It answered that question with its own
+ * copy of the expression below, and the copy was a term short: `recordEgress`
+ * selects the netns recorder and therefore confinement, and the copy did not
+ * say so. So a `recordEgress` sweep pre-flighted against the host's cwd and env,
+ * then ran somewhere neither existed.
+ *
+ * Returning the ROUTE rather than a boolean is what makes that unrepeatable: the
+ * runner below dispatches on it and owns no policy of its own, and the pre-flight
+ * asks the same function instead of re-deriving the answer. A future option that
+ * selects confinement is added HERE, once, and every reader inherits it.
+ *
+ * A refusal counts as non-direct, and deliberately: the sweep is describing the
+ * environment a run WOULD have, and the environment it would have refused to run
+ * unconfined in is the confined one.
+ */
+export type ScriptRunRoute = {
+    readonly kind: "egress";
+} | {
+    readonly kind: "sandboxed";
+} | {
+    readonly kind: "direct";
+} | {
+    readonly kind: "refuse";
+    readonly reason: string;
+};
+/** What a run with these options will do, given what the machine can offer. */
+export declare function routeScriptRun(opts: Pick<RunScriptOptions, "egress" | "sandbox" | "trusted" | "recordEgress">, available: {
+    readonly sandbox: boolean;
+    readonly egress: boolean;
+}): ScriptRunRoute;
 export declare const REAL_DEPS: RunScriptDeps;
 export declare function egressRoutes(): boolean;
 /**

package/dist/run-script.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REAL_DEPS = void 0;
+exports.shellNeverLaunched = shellNeverLaunched;
 exports.runScriptWith = runScriptWith;
+exports.routeScriptRun = routeScriptRun;
 exports.egressRoutes = egressRoutes;
 exports.runScript = runScript;
 /**
@@ -84,6 +86,13 @@ const coverage_probe_js_1 = require("./coverage-probe.js");
  *
  * A hook that deliberately exits 126/127 itself is missed the same way, and the
  * same direction.
+ *
+ * @internal Exported so the guard sweep asks the SAME question rather than
+ * re-deriving it (one-detector-no-drift). It reads these codes for the opposite
+ * purpose — not "may I credit this file with coverage?" but "may I score this
+ * guard at all?" — and the answer is the same fact: the shell never reached the
+ * program, so nothing the exit code says is the program's opinion. Not part of
+ * the public API.
  */
 function shellNeverLaunched(status) {
     return status === 126 || status === 127;
@@ -100,22 +109,31 @@ function runScriptWith(command, stdin, opts, deps) {
     // at the primitive, so `runHook` and a bare `runScript` both count. See
     // check-count.ts.
     (0, check_count_js_1.recordCheck)();
-    // Allowlisted egress is its own confined path (bwrap netns + slirp4netns +
-    // nft); it can't run unconfined, so it refuses outright when the tooling is
-    // absent rather than falling back to a direct run that ignores the allowlist.
-    const res = opts.egress
-        ? runEgress(command, stdin, opts, deps)
-        : runConfinedOrDirect(command, stdin, opts, deps);
+    // The route is DECIDED elsewhere (`routeScriptRun`) and only dispatched here,
+    // so this function holds no confinement policy a second reader could fall
+    // behind — see the type's header for the sweep that fell behind it.
+    const route = routeScriptRun(opts, {
+        sandbox: deps.available,
+        egress: deps.egressAvailable,
+    });
+    if (route.kind === "refuse")
+        throw new Error(route.reason);
+    const spawn = route.kind === "egress"
+        ? deps.egress
+        : route.kind === "sandboxed"
+            ? deps.sandboxed
+            : deps.direct;
+    const res = spawn(command, stdin, opts);
     // …and WHICH surface it exercised, read off the command line that WAS
     // executed (plus `opts.env`, because the documented idiom passes the hook path
     // through one). Attribution by execution, not by file name — see
     // coverage-probe.ts. Derived here at the primitive so `runHook` and a bare
     // `runScript` both attribute without either knowing about coverage.
     //
-    // 🔴 AFTER THE SPAWN, NOT BEFORE, AND THE ORDER IS THE WHOLE CLAIM. Both
-    // branches above can THROW before any spawner is reached: `runEgress` refuses
-    // when the allowlist sandbox is missing, and `runConfinedOrDirect` refuses when
-    // confinement was required and bwrap is absent. A harness that asserts exactly
+    // 🔴 AFTER THE SPAWN, NOT BEFORE, AND THE ORDER IS THE WHOLE CLAIM. The route
+    // above can be `refuse` and THROW before any spawner is reached: the allowlist
+    // sandbox is missing, or confinement was required and bwrap is absent. A
+    // harness that asserts exactly
     // that refusal — `assert.throws(() => runHook(untrusted…))`, a legitimate and
     // documented test — caught the error, exited 0 with checks recorded, and the
     // runner wrote an execution-tier coverage record for a hook that never ran.
@@ -140,18 +158,21 @@ function runScriptWith(command, stdin, opts, deps) {
         filesWritten: res.filesWritten,
     };
 }
-/** The allowlisted-egress branch: confine-with-netns, or refuse if unavailable. */
-function runEgress(command, stdin, opts, deps) {
-    if (!deps.egressAvailable) {
-        throw new Error("refusing to run egress: { allow } without the allowlist sandbox: it " +
-            "needs Linux + bubblewrap (bwrap) + slirp4netns + nft — install them to " +
-            "run with a packet-layer egress allowlist, or use recordEgress to record " +
-            "and block instead");
-    }
-    return deps.egress(command, stdin, opts);
-}
-/** The default branch: pick direct vs. confined via the safe-by-default policy. */
-function runConfinedOrDirect(command, stdin, opts, deps) {
+/** What a run with these options will do, given what the machine can offer. */
+function routeScriptRun(opts, available) {
+    // Allowlisted egress is its own confined path (bwrap netns + slirp4netns +
+    // nft); it can't run unconfined, so it refuses outright when the tooling is
+    // absent rather than falling back to a direct run that ignores the allowlist.
+    if (opts.egress)
+        return available.egress
+            ? { kind: "egress" }
+            : {
+                kind: "refuse",
+                reason: "refusing to run egress: { allow } without the allowlist sandbox: it " +
+                    "needs Linux + bubblewrap (bwrap) + slirp4netns + nft — install them to " +
+                    "run with a packet-layer egress allowlist, or use recordEgress to record " +
+                    "and block instead",
+            };
     // Confinement follows provenance: a trusted hook (the default) runs directly;
     // marking a hook untrusted defaults it to "auto" (confine-or-refuse), so
     // foreign code is never run unconfined by accident. An explicit `sandbox`
@@ -164,13 +185,13 @@ function runConfinedOrDirect(command, stdin, opts, deps) {
     const decision = (0, sandbox_js_1.decideSandbox)({
         trusted: false,
         mode,
-        available: deps.available,
+        available: available.sandbox,
     });
     if (decision.action === "throw")
-        throw new Error(decision.reason);
+        return { kind: "refuse", reason: decision.reason };
     return decision.action === "sandbox"
-        ? deps.sandboxed(command, stdin, opts)
-        : deps.direct(command, stdin, opts);
+        ? { kind: "sandboxed" }
+        : { kind: "direct" };
 }
 /** Run the hook command directly through a shell (the default, unconfined). */
 function directSpawn(command, stdin, opts) {

package/dist/scan-core.js

@@ -225,9 +225,23 @@ function firstBodyParagraph(md) {
     }
     return para.join(" ").trim() || undefined;
 }
-/** The body of a SKILL.md with the leading `---` frontmatter block stripped. */
+/**
+ * The body of a SKILL.md with the leading `---` frontmatter block stripped, PLUS
+ * how many lines that block consumed.
+ *
+ * 🔴 The count is returned rather than discarded because a downstream detector
+ * emits LINE NUMBERS. `markdownRefs` counts from one over whatever string it is
+ * given, so a coordinate computed over the body is short by exactly the stripped
+ * frontmatter — on a 5-line block, the ref on file line 11 printed as 6 (#206).
+ * A struct instead of a bare string so the offset is in the caller's hand at the
+ * call site, not something to remember.
+ */
 function skillBody(md) {
-    return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+    const body = md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+    const consumed = md.slice(0, md.length - body.length);
+    // Newlines in the consumed prefix == lines before the body starts. Counts a
+    // CRLF file identically (the `\r` rides along inside the line).
+    return { body, strippedLines: consumed.split("\n").length - 1 };
 }
 /**
  * The on-disk path for a materialized file key. `loadPlugin` prefixes each
@@ -337,10 +351,14 @@ function scanSkills(files, cls, ctx) {
         // a ref under one of those declared dirs against the repo root — OPT-IN, so a
         // repo that doesn't set it is byte-identical to before (no masking of a real
         // missing bundled resource). See feedback P1-4.
-        const resourceIssues = (0, skill_resources_js_1.skillResourceIssues)(skillBody(md), skillDir, {
+        const { body: bodyMd, strippedLines } = skillBody(md);
+        const resourceIssues = (0, skill_resources_js_1.skillResourceIssues)(bodyMd, skillDir, {
             repoRoot: sharedDirsRoot,
             sharedDirs,
             existsSync: ctx.existsSync,
+            // Findings carry a line number the author is meant to OPEN, so give the
+            // detector back the frontmatter it never saw (#206).
+            lineOffset: strippedLines,
         });
         // The lethal trifecta is a property of what a unit CAN do. For a SKILL that is
         // NOT its `allowed-tools:` — measured 2026-08-11, and documented by Claude Code

package/dist/score-core.d.ts

@@ -163,7 +163,27 @@ export declare function trifectaExposure(r: ScanReport): TrifectaExposure;
  * surfaced separately, never scored).
  */
 export declare function reportDeductions(r: ScanReport): Deduction[];
-/** True when a report has no loadable plugin surface at all (the empty machine). */
+/**
+ * True when a report has no loadable plugin surface at all (the empty machine).
+ *
+ * 🔴 THE ONE PLACE the surface set is enumerated, and every scorer must ask it
+ * rather than write the list again. `scoreReport` used to keep its own copy and
+ * that copy had dropped `inlineHooks` — so a plugin whose entire contribution is
+ * hooks declared inline in `plugin.json` scored 0 / F with "no loadable plugin
+ * surface" while the same report printed `inlineHooks: 2` (#199). Measured on a
+ * two-inline-hook fixture: this predicate said `false` and `scoreReport` said
+ * `0`, against `auditScore`'s `100` — a 100-point disagreement between two
+ * numbers documented to be equal.
+ *
+ * A hooks-only plugin is a legitimate shape, the same way a command-only or
+ * MCP-only one is: a repo can ship gates and nothing else. Zero has to mean "no
+ * surface of any kind", because it reads as "this plugin is broken" — a
+ * different statement from "this plugin has no skills or subagents".
+ *
+ * Hooks count in BOTH forms: `hooks[]` is the script-backed ones, `inlineHooks`
+ * the shell one-liners that carry no script file to path-check. The second is
+ * still a gate that runs.
+ */
 export declare function isEmptyMachine(r: ScanReport): boolean;
 /**
  * THE shared integrity score — `100 − Σ(all graded penalties)`, clamped to

package/dist/score-core.js

@@ -307,7 +307,27 @@ function reportDeductions(r) {
         // advisory note below). The score ranks what's BROKEN.
     ];
 }
-/** True when a report has no loadable plugin surface at all (the empty machine). */
+/**
+ * True when a report has no loadable plugin surface at all (the empty machine).
+ *
+ * 🔴 THE ONE PLACE the surface set is enumerated, and every scorer must ask it
+ * rather than write the list again. `scoreReport` used to keep its own copy and
+ * that copy had dropped `inlineHooks` — so a plugin whose entire contribution is
+ * hooks declared inline in `plugin.json` scored 0 / F with "no loadable plugin
+ * surface" while the same report printed `inlineHooks: 2` (#199). Measured on a
+ * two-inline-hook fixture: this predicate said `false` and `scoreReport` said
+ * `0`, against `auditScore`'s `100` — a 100-point disagreement between two
+ * numbers documented to be equal.
+ *
+ * A hooks-only plugin is a legitimate shape, the same way a command-only or
+ * MCP-only one is: a repo can ship gates and nothing else. Zero has to mean "no
+ * surface of any kind", because it reads as "this plugin is broken" — a
+ * different statement from "this plugin has no skills or subagents".
+ *
+ * Hooks count in BOTH forms: `hooks[]` is the script-backed ones, `inlineHooks`
+ * the shell one-liners that carry no script file to path-check. The second is
+ * still a gate that runs.
+ */
 function isEmptyMachine(r) {
     const surfaces = r.skills.length +
         r.agents.length +
@@ -341,11 +361,15 @@ function pluralizeLabel(n, label) {
 /** Deterministic structural-health score for one scanned plugin. */
 function scoreReport(r) {
     // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
-    // load. A command-only or MCP-only plugin (commands/*.md or .mcp.json with no
-    // skills/agents/hooks) IS a legitimate plugin, though — Anthropic ships
-    // command-only plugins in its own marketplace — so it must NOT score 0.
-    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
-    if (surfaces === 0 && !r.mcp) {
+    // load. A command-only, MCP-only or HOOKS-only plugin IS a legitimate plugin,
+    // though — Anthropic ships command-only plugins in its own marketplace, and a
+    // repo can reasonably ship gates and nothing else — so none of them scores 0.
+    //
+    // 🔴 Asked of `isEmptyMachine`, never re-enumerated here. The hand-written copy
+    // that used to sit on this line had dropped `inlineHooks`, so a hooks-only
+    // plugin scored 0 while `auditScore` — which does ask the predicate — scored the
+    // same report 100 (#199). Two lists mean two answers.
+    if (isEmptyMachine(r)) {
         return { score: 0, issues: ["no loadable plugin surface"] };
     }
     const deductions = reportDeductions(r);

package/dist/self-resolve.d.mts

@@ -0,0 +1,20 @@
+/** The shape a Node resolve hook must return. */
+export type SelfResolved = {
+    url: string;
+    format?: string | null;
+    shortCircuit?: boolean;
+};
+/**
+ * Resolve `vigiles` / `vigiles/<subpath>` against the CLI's OWN installation,
+ * or `null` when this is not our specifier / we cannot serve it.
+ *
+ * `null` rather than a throw of its own: the caller is inside a `catch` and the
+ * ORIGINAL resolution error is the accurate one to re-raise. An unknown subpath
+ * (`vigiles/nope`) would otherwise surface as `ERR_PACKAGE_PATH_NOT_EXPORTED`
+ * from our rescue, blaming the rescue for the author's typo.
+ *
+ * The root is read from the environment at CALL time, not at module load, so a
+ * test can drive both branches in one process.
+ */
+export declare function resolveSelfSpecifier(specifier: string): SelfResolved | null;
+//# sourceMappingURL=self-resolve.d.mts.map

package/dist/self-resolve.mjs

@@ -0,0 +1,75 @@
+/**
+ * ONE rescue for the bare `vigiles` specifier, shared by both module-resolution
+ * hooks this package registers.
+ *
+ * 🔴 WHY IT EXISTS. A spec does `import { instructionFile } from "vigiles/spec"`
+ * and a harness does `import { runHook } from "vigiles"`, so the package has to
+ * sit in a `node_modules` Node can reach from that file. In a repo that already
+ * has a `package.json`, the obvious way to put it there is `npm install` in the
+ * root — which installs the whole dependency tree. Measured by an adopter
+ * (#184): **840 packages in 2 minutes** where vigiles alone is 42 and about
+ * 90 MB; the other 798 were a model-eval framework and an agent SDK that the
+ * gate — `lint`, `compile` and `test`, all deterministic reads — never touches.
+ * One run sat 11 minutes in that step before being cancelled. In a repo with NO
+ * `package.json` at all (Python, Rust, Go) there is no install to run: the
+ * typed-spec path was simply unavailable, and `compile` exited 1 with
+ * `ERR_MODULE_NOT_FOUND`.
+ *
+ * ⚠️ `NODE_PATH` does NOT solve this, and that was measured rather than assumed:
+ * Node ignores it for ESM resolution, and both a spec and a harness are ESM. So
+ * the only ways to resolve a bare specifier from elsewhere are a real
+ * `node_modules` entry (a symlink) or a resolver hook. This is the hook half.
+ *
+ * 🔴 WHY IT IS SHARED. It was written once for harness scripts and the spec host
+ * did not get it, so `vigiles test` worked on a repo without `package.json` and
+ * `vigiles compile` did not — the same question answered two different ways by
+ * two files. Copying the branch into the second hook would have made that
+ * divergence permanent instead of closing it (`one-detector-no-drift`), so the
+ * branch lives here and both hooks call it.
+ *
+ * Scope is deliberately narrow: ONLY the `vigiles` specifier and its subpaths,
+ * and only when normal resolution has already FAILED. A repo that has vigiles
+ * installed locally keeps resolving to the local copy — the caller tries
+ * `nextResolve` first and only reaches this on the way out — so nothing changes
+ * for a repo that already worked. This only fills the hole where resolution
+ * would otherwise throw.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+/**
+ * Resolve `vigiles` / `vigiles/<subpath>` against the CLI's OWN installation,
+ * or `null` when this is not our specifier / we cannot serve it.
+ *
+ * `null` rather than a throw of its own: the caller is inside a `catch` and the
+ * ORIGINAL resolution error is the accurate one to re-raise. An unknown subpath
+ * (`vigiles/nope`) would otherwise surface as `ERR_PACKAGE_PATH_NOT_EXPORTED`
+ * from our rescue, blaming the rescue for the author's typo.
+ *
+ * The root is read from the environment at CALL time, not at module load, so a
+ * test can drive both branches in one process.
+ */
+export function resolveSelfSpecifier(specifier) {
+    // Handed in by the parent process (the CLI), which knows where it is
+    // installed. Absent = nobody promised us a root; stay out of the way.
+    const self = process.env.VIGILES_SELF_ROOT;
+    if (!self)
+        return null;
+    if (specifier !== "vigiles" && !specifier.startsWith("vigiles/"))
+        return null;
+    try {
+        const require = createRequire(pathToFileURL(`${self}/package.json`));
+        // Resolve through the package's own `exports` map rather than guessing a
+        // file path, so a subpath like `vigiles/eval` obeys the same contract it
+        // would from a normal install. Node's self-reference rule is what makes
+        // this work when `self` IS the vigiles package rather than a copy inside
+        // some `node_modules`.
+        return {
+            url: pathToFileURL(require.resolve(specifier, { paths: [self] })).href,
+            shortCircuit: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=self-resolve.mjs.map

package/dist/spec-hooks.d.mts

@@ -19,6 +19,8 @@ type Loaded = {
 };
 type NextLoad = (url: string, context: LoadContext) => Loaded | Promise<Loaded>;
 /**
+ * Two rescues, both attempted ONLY after normal resolution has failed.
+ *
  * `./x.js` → `./x.ts` when the sibling exists.
  *
  * This is the TypeScript ESM convention (`tsc` under `nodenext` requires the
@@ -27,6 +29,14 @@ type NextLoad = (url: string, context: LoadContext) => Loaded | Promise<Loaded>;
  * dogfood specs import `src/core/spec.js`, a file that does not exist on disk.
  * Attempted only AFTER normal resolution fails, so it can never shadow a real
  * `.js` file.
+ *
+ * Then `vigiles` / `vigiles/<subpath>` against the CLI's own install. Without
+ * it, a repo with no `node_modules/vigiles` — every Python, Rust or Go repo,
+ * where there is not even an install to run — could not compile a spec at all:
+ * `init` scaffolded `import { instructionFile } from "vigiles/spec"` and
+ * `compile` exited 1 with `ERR_MODULE_NOT_FOUND`. `vigiles test` had carried
+ * this rescue since #184; the spec host did not, which is the whole reason the
+ * branch now lives in one shared module rather than in each hook.
  */
 export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<Resolved>;
 /** Transpile `.ts`/`.mts` with the TypeScript this package already ships. */

package/dist/spec-hooks.mjs

@@ -18,12 +18,18 @@
  * `./x.js` → `./x.ts` specifier rewrite, and bare specifiers. NOT tsconfig
  * `paths`, JSX, or decorator configuration — specs are configuration modules,
  * not applications.
+ *
+ * The one bare specifier it does more than pass through is `vigiles` itself —
+ * see `./self-resolve.mjs`, shared with the harness hook.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import ts from "typescript";
+import { resolveSelfSpecifier } from "./self-resolve.mjs";
 const TS_SOURCE = /\.m?ts$/;
 /**
+ * Two rescues, both attempted ONLY after normal resolution has failed.
+ *
  * `./x.js` → `./x.ts` when the sibling exists.
  *
  * This is the TypeScript ESM convention (`tsc` under `nodenext` requires the
@@ -32,6 +38,14 @@ const TS_SOURCE = /\.m?ts$/;
  * dogfood specs import `src/core/spec.js`, a file that does not exist on disk.
  * Attempted only AFTER normal resolution fails, so it can never shadow a real
  * `.js` file.
+ *
+ * Then `vigiles` / `vigiles/<subpath>` against the CLI's own install. Without
+ * it, a repo with no `node_modules/vigiles` — every Python, Rust or Go repo,
+ * where there is not even an install to run — could not compile a spec at all:
+ * `init` scaffolded `import { instructionFile } from "vigiles/spec"` and
+ * `compile` exited 1 with `ERR_MODULE_NOT_FOUND`. `vigiles test` had carried
+ * this rescue since #184; the spec host did not, which is the whole reason the
+ * branch now lives in one shared module rather than in each hook.
  */
 export async function resolve(specifier, context, nextResolve) {
     try {
@@ -44,6 +58,9 @@ export async function resolve(specifier, context, nextResolve) {
                 return { url: candidate.href, format: "module", shortCircuit: true };
             }
         }
+        const rescued = resolveSelfSpecifier(specifier);
+        if (rescued)
+            return rescued;
         throw err;
     }
 }

package/dist/test.d.ts

@@ -58,10 +58,15 @@ export type { HookRunResult, BlockMechanism, RunHookOptions, HookInput, HookOutp
 export * from "./harness-assert.js";
 export { experimental_emitTool, experimental_parseEmitted, experimental_assertEmittedOk, type EmitFieldSchema, type EmitObjectSchema, type EmitPropertySchema, type EmitTrackSchema, type EmitToolDefinition, type ExperimentalEmitTool, } from "./experimental-emit.js";
 export { loadHook } from "./load-hook.js";
+export { experimental_hookState } from "./hook-state-store.js";
+export type { HookStateHandle, SeedStateOptions } from "./hook-state-store.js";
+export type { StateFact, Duration } from "./core/hook-state.js";
 export { evalChecks, assertChecks, tool, toolWith, notTool, onlyTools, skill, output, hookFired, received, turns, wrote, didNotWrite, subagent, blocked, allowed, mcp, cost, latency, tokens, inputTokens, outputTokens, cacheTokens, } from "./check.js";
 export type { ArgMatcher, Check, CheckJSON, CheckResult, JudgeFn, } from "./check.js";
 export { DISASTER_CATALOG, verifyGuardrail, unblockedDisasters, assertBlocksDisasters, formatGuardrailReport, experimental_alternateSpellings, } from "./guardrail-check.js";
 export type { DisasterEvent, DisasterCategory, GuardrailResult, VerifyGuardrailOptions, } from "./guardrail-check.js";
+export { experimental_verifyPluginGuards, experimental_formatPluginGuardReport, } from "./verify-plugin-guards.js";
+export type { PluginGuardReport, SweptHook, SweptHookOutcome, NonCommandHookAction, VerifyPluginGuardsOptions, } from "./verify-plugin-guards.js";
 export * from "./tool-stub.js";
 export { runHarnessTest, runHarness, parseToolCalls, parseSubagents, parseResultEvent, parseOutput, parseHooks, decideSandbox, specTrusted, sandboxAvailable, } from "./harness-test.js";
 export type { HarnessTestSpec, Trace, SubagentTrace, HarnessTestResult, RunHarnessTestOptions, ModelTurn, ModelRequest, ToolCall, HookFire, HarnessTestDriver, SandboxMode, } from "./harness-test.js";

package/dist/test.js

@@ -66,8 +66,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.specTrusted = exports.decideSandbox = exports.parseHooks = exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.recordCheck = void 0;
-exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = void 0;
+exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_formatPluginGuardReport = exports.experimental_verifyPluginGuards = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.experimental_hookState = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.recordCheck = void 0;
+exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = void 0;
 // --- reporting: how much did this script actually do? ---
 // `vigiles test` can otherwise see only an exit code, so a file that runs NOTHING
 // prints the same `✓` as one that ran and passed (measured 2026-08-08 on a file
@@ -113,6 +113,15 @@ Object.defineProperty(exports, "experimental_assertEmittedOk", { enumerable: tru
 // the CLI runtime uses, so a hook that loads in a test loads identically in prod.
 var load_hook_js_1 = require("./load-hook.js");
 Object.defineProperty(exports, "loadHook", { enumerable: true, get: function () { return load_hook_js_1.loadHook; } });
+// Seed + read a compiled hook's NAMED STATE from a test. A throttled hook only
+// does anything interesting against an OLD fact, and "old" is not something a
+// test can produce by waiting — so without this a consumer testing a throttle
+// had to reconstruct the store's private path by hand (the dogfood repo did,
+// and it broke when the facts were renamed). It is on THIS barrel and not on
+// `vigiles/hook` on purpose: `vigiles/hook` is the only import a compiled hook
+// may have, and its guarantee is that it hands out no writer.
+var hook_state_store_js_1 = require("./hook-state-store.js");
+Object.defineProperty(exports, "experimental_hookState", { enumerable: true, get: function () { return hook_state_store_js_1.experimental_hookState; } });
 // --- the declarative check vocabulary ---
 // Enumerated rather than `export *` ON PURPOSE: `judged` also lives in check.ts
 // and its default judge is a real model call, so it is the one member of this
@@ -153,6 +162,18 @@ Object.defineProperty(exports, "unblockedDisasters", { enumerable: true, get: fu
 Object.defineProperty(exports, "assertBlocksDisasters", { enumerable: true, get: function () { return guardrail_check_js_1.assertBlocksDisasters; } });
 Object.defineProperty(exports, "formatGuardrailReport", { enumerable: true, get: function () { return guardrail_check_js_1.formatGuardrailReport; } });
 Object.defineProperty(exports, "experimental_alternateSpellings", { enumerable: true, get: function () { return guardrail_check_js_1.experimental_alternateSpellings; } });
+// The same battery, pointed at a DIRECTORY instead of one command string. It
+// reads each hook's event, matcher, command and condition off the same
+// registration, so the pairing mistake `verifyGuardrail`'s own comment has to ask
+// callers to avoid ("pass the hook's declared `if` here") cannot be made. It
+// belongs on THIS barrel and beside the battery for the same reason the battery
+// does: nothing here calls a model.
+// The report + its renderer ship together: the sweep's one motivating use is
+// "point the battery at YOUR hooks", and without the formatter that is a
+// hand-written fold over a discriminated union at every call site.
+var verify_plugin_guards_js_1 = require("./verify-plugin-guards.js");
+Object.defineProperty(exports, "experimental_verifyPluginGuards", { enumerable: true, get: function () { return verify_plugin_guards_js_1.experimental_verifyPluginGuards; } });
+Object.defineProperty(exports, "experimental_formatPluginGuardReport", { enumerable: true, get: function () { return verify_plugin_guards_js_1.experimental_formatPluginGuardReport; } });
 // Tool stubs on PATH (rung R2): shadow a CLI tool with a recorded canned result.
 __exportStar(require("./tool-stub.js"), exports);
 // The assembled machine — AGNOSTIC SURFACE ONLY. The Claude-Code transport