vigiles 26.1.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/test.d.ts

@@ -65,6 +65,8 @@ export { evalChecks, assertChecks, tool, toolWith, notTool, onlyTools, skill, ou
 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.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.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 = 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
@@ -162,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

package/dist/verify-plugin-guards.d.ts

@@ -0,0 +1,194 @@
+import { type NonCommandHookAction } from "./core/hook-normalize.js";
+export type { NonCommandHookAction } from "./core/hook-normalize.js";
+import type { HarnessAdapter } from "./core/adapter.js";
+import { type DisasterCategory, type DisasterEvent, type GuardrailResult } from "./guardrail-check.js";
+import type { RunHookOptions } from "./run-hook.js";
+/** The hook a sweep looked at, as its config declares it. */
+export interface SweptHook {
+    /** The event it registers under, e.g. `"PreToolUse"`. */
+    readonly event: string;
+    /** Its tool matcher, or `null` when it declares none (matches everything). */
+    readonly matcher: string | null;
+    /** Its condition as written (Claude Code's `if`), or `null` when unconditional. */
+    readonly condition: string | null;
+    /** The command, with the harness's plugin-root token already expanded. */
+    readonly command: string;
+    /**
+     * Its position in the flattened registration list, so two hooks sharing a
+     * command are still distinguishable in a report. Stable for one sweep of one
+     * directory; not an identity across versions.
+     */
+    readonly index: number;
+}
+/**
+ * What happened to one hook. A DISCRIMINATED UNION, not a result list plus three
+ * nullable fields: `results` exists on exactly the outcome that has them, so
+ * "read the score of a hook that was never run" is a type error rather than a
+ * `0/7` someone quotes.
+ */
+export type SweptHookOutcome = {
+    /** The battery reached this hook; `results` holds one entry per event. */
+    readonly status: "measured";
+    readonly hook: SweptHook;
+    /** One result per battery event, in catalog order. */
+    readonly results: readonly GuardrailResult[];
+    /** Ids of the events it denied. */
+    readonly blocked: readonly string[];
+    /** Ids it ran on and let through. */
+    readonly allowed: readonly string[];
+    /** Ids the harness would never have handed it (condition did not match). */
+    readonly notRun: readonly string[];
+} | {
+    /**
+     * The battery does not apply to this hook — a different event, or a matcher
+     * that selects none of the battery's tools. NOT a score of zero.
+     */
+    readonly status: "not-applicable";
+    readonly hook: SweptHook;
+    /** One line naming which of the two it is, and against what. */
+    readonly reason: string;
+} | {
+    /**
+     * The command names a variable nothing has set, so the program we would run
+     * is not the program the harness runs. Refusing is the honest answer; the
+     * fix is in the caller's hands (pass `env`).
+     */
+    readonly status: "unresolved";
+    readonly hook: SweptHook;
+    /** One line naming the unset variables. */
+    readonly reason: string;
+};
+/** The whole sweep. */
+export interface PluginGuardReport {
+    /** The directory swept, resolved to an absolute path. */
+    readonly dir: string;
+    /** The adapter that read it, e.g. `"claude-code"`. */
+    readonly harness: string;
+    /** The event each disaster was delivered as (default `"PreToolUse"`). */
+    readonly event: string;
+    /** The battery that was used, so a report says what it measured against. */
+    readonly events: readonly DisasterEvent[];
+    /** One outcome per declared COMMAND hook, in config order. */
+    readonly hooks: readonly SweptHookOutcome[];
+    /**
+     * Declared actions this tier cannot drive because they are not commands —
+     * `prompt`, `http`, `mcp_tool`, `agent`.
+     *
+     * 🔴 THEY USED TO BE DROPPED, AND DROPPING THEM MANUFACTURED THE FALSE EMPTY
+     * `notes` exists to prevent. A repository whose hooks are all `prompt` actions
+     * has declared guards; it was reported as declaring none, in the words of the
+     * one sentence this report writes to be sure nobody reads an empty result as a
+     * clean bill of health. Not measured is a limit of the tier and says so; not
+     * declared is an accusation about the repository, and it was not true.
+     *
+     * They carry no score and never will here — a shell battery cannot drive a
+     * prompt — so they are a separate list rather than a fourth outcome status
+     * with an invented command.
+     */
+    readonly unmeasurable: readonly NonCommandHookAction[];
+    /**
+     * Why the sweep measured less than a reader might assume — no COMMAND hooks
+     * declared, a harness with no shell hooks, every hook on another event, or an
+     * action this tier cannot drive. Empty only when at least one hook was
+     * measured AND nothing was left undrivable: an undrivable action is a gap in
+     * COVERAGE, so it is said even when other hooks scored.
+     *
+     * 🔴 THIS IS THE EMPTY CASE'S VOICE. `hooks: []` on its own reads as a clean
+     * bill of health, which is the exact false confidence the battery exists to
+     * remove — so a sweep that measured nothing always says so in words.
+     */
+    readonly notes: readonly string[];
+}
+/** Options for {@link experimental_verifyPluginGuards}. */
+export interface VerifyPluginGuardsOptions extends Omit<RunHookOptions, "condition" | "protocol"> {
+    /**
+     * The harness to read the repo as. Defaults to Claude Code, so an existing
+     * Claude Code repo needs nothing. The condition grammar and the block protocol
+     * both come from this adapter's `hookProtocol`.
+     */
+    readonly adapter?: HarnessAdapter;
+    /** Restrict the battery to these categories (default: the whole catalog). */
+    readonly categories?: readonly DisasterCategory[];
+    /** Override the battery entirely. */
+    readonly events?: readonly DisasterEvent[];
+    /** The event each disaster is delivered as (default `"PreToolUse"`). */
+    readonly event?: string;
+}
+/**
+ * Run the disaster battery against every hook a plugin or repo declares, using
+ * each hook's OWN event, matcher and condition, and report per hook.
+ *
+ * ```ts
+ * import { experimental_verifyPluginGuards } from "vigiles";
+ *
+ * const report = experimental_verifyPluginGuards(".");
+ * for (const h of report.hooks) {
+ *   if (h.status === "measured")
+ *     console.log(`${h.blocked.length}/${h.results.length}  ${h.hook.command}`);
+ *   else console.log(`⊘ ${h.status}  ${h.hook.command} — ${h.reason}`);
+ * }
+ * for (const note of report.notes) console.log(note);
+ * ```
+ *
+ * Nothing here needs a model or a key. The hooks it finds are the ones the
+ * harness would load, so a hook that is present on disk but not registered is
+ * absent from the report by construction — which is the correct answer, and the
+ * one you would not get by globbing `hooks/*.sh`.
+ *
+ * ⚠️ It RUNS each reachable hook. A hook is a program you did not necessarily
+ * write, so point this at a repo whose hooks you are willing to execute, or pass
+ * `trusted: false` / `sandbox: "auto"` (inherited from {@link RunHookOptions}) to
+ * confine them. `verifyGuardrail` has always had the same property; sweeping a
+ * whole plugin makes it worth saying out loud.
+ *
+ * @experimental Days old, with no consumer outside this repository. The REPORT
+ * SHAPE is the part most likely to move — specifically whether `not-applicable`
+ * stays one status or splits by cause, and whether the per-hook counts stay id
+ * arrays. The prefix comes off when that shape survives sweeping several real
+ * third-party repos unchanged; see docs/experimental.md.
+ *
+ * @param dir - the plugin or repo root to read hooks from.
+ */
+export declare function experimental_verifyPluginGuards(dir: string, opts?: VerifyPluginGuardsOptions): PluginGuardReport;
+/**
+ * Render a {@link PluginGuardReport} as terminal text.
+ *
+ * ```ts
+ * import {
+ *   experimental_verifyPluginGuards,
+ *   experimental_formatPluginGuardReport,
+ * } from "vigiles";
+ *
+ * console.log(
+ *   experimental_formatPluginGuardReport(experimental_verifyPluginGuards(".")),
+ * );
+ * ```
+ *
+ * NEUTRAL, the same way {@link formatGuardrailReport} is: it reports what each
+ * hook blocks without deciding whether that was the hook's job. A repo's config
+ * never says which of its hooks is meant to be a bash-safety guard, so a verdict
+ * here would be invented rather than read.
+ *
+ * 🔴 A HOOK THE BATTERY NEVER REACHED IS NEVER GIVEN A NUMBER. A `measured` hook
+ * prints `blocks n/7`; a `not-applicable` or `unresolved` one prints its REASON
+ * under a `⊘` heading and no count at all, because a rendered `0/7` is the same
+ * false confidence the discriminated union exists to prevent, reintroduced one
+ * layer up where the type system can no longer see it. For the same reason the
+ * report's `notes` are printed FIRST and in full: a sweep that measured nothing
+ * has to say so in words, since an output with no rows reads as a clean bill of
+ * health.
+ *
+ * MANY HOOKS STAY READABLE by grouping the unmeasured half BY REASON — a repo
+ * with thirty hooks usually has two or three distinct reasons — and naming at
+ * most {@link HOOKS_PER_REASON} hooks per reason before counting the rest. The
+ * measured half is never collapsed: those are the hooks you came for.
+ *
+ * @experimental It renders {@link PluginGuardReport}, whose SHAPE is the part
+ * most likely to move (see {@link experimental_verifyPluginGuards}), so a stable
+ * name here would promise a stability its only input does not have. The prefix
+ * comes off with the same change that takes it off the report.
+ *
+ * @param report - a sweep from {@link experimental_verifyPluginGuards}.
+ */
+export declare function experimental_formatPluginGuardReport(report: PluginGuardReport): string;
+//# sourceMappingURL=verify-plugin-guards.d.ts.map