vigiles 26.1.1 → 26.2.0

package/dist/core/hook-matcher.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hookMatcherIssues = hookMatcherIssues;
+exports.hookMatcherReach = hookMatcherReach;
 const tool_contract_js_1 = require("./tool-contract.js");
 const mcp_tool_js_1 = require("./mcp-tool.js");
 // ---------------------------------------------------------------------------
@@ -32,8 +33,31 @@ const REAL_SHAPE_PROBES = [
 ];
 /** The widest correct MCP matcher — what a too-narrow one should become. */
 const WIDE_MCP_MATCHER = "mcp__.*__.*";
-/** Match-all matchers the harness special-cases (and `*` isn't even a regex). */
-const MATCH_ALL = new Set(["", "*", "**", ".*"]);
+/**
+ * Match-all matchers the harness special-cases (and `*` isn't even a regex).
+ *
+ * 🔴 MEASURED, AND `**` IS NOT ONE OF THEM. It sat in this set on no evidence
+ * while the table at the top of this file — the measured one — never listed it.
+ * Against a real `claude` 2.1.263, one hook per run, marker file as the oracle,
+ * 3 runs of each:
+ *
+ * | matcher | a `Bash` call | fired |
+ * | ------- | ------------- | ----- |
+ * | `*`     | `Bash`        | yes   |
+ * | `.*`    | `Bash`        | yes   |
+ * | `""`    | `Bash`        | yes   |
+ * | `**`    | `Bash`        | NO    |
+ *
+ * The direction of that mistake is the expensive one: believing `**` selects
+ * everything makes a guard registered under it come back "measured, allows
+ * 0/7" — an ACCUSATION that a repo's guard let seven disasters through, when
+ * the harness never invoked it once. The mirror image of scoring a hook that
+ * could not start. `**` now falls through to the regex path, where it does not
+ * compile, and both the sweep and the `hook-matcher` rule report a hook that
+ * never fires. Pinned by `src/hook-matcher-delivery.test.ts` so the day Claude
+ * Code starts honouring it, the claim goes red instead of quietly rotting.
+ */
+const MATCH_ALL = new Set(["", "*", ".*"]);
 /** Cap on segments harvested from a matcher — bounds the probe corpus. */
 const MAX_DERIVED_SEGMENTS = 4;
 // ---------------------------------------------------------------------------
@@ -293,4 +317,55 @@ function hookMatcherIssues(entries, declaredServers, dialect) {
     }
     return findings;
 }
+/**
+ * Would this matcher select a call to `tool` — i.e. does the harness spawn the
+ * hook at all?
+ *
+ * The same two MEASURED facts the module header pins, asked as a question rather
+ * than as a defect: on a harness whose matchers are tool names (Claude Code), a
+ * matcher with no regex metacharacter is compared by string EQUALITY and one
+ * with metacharacters is an UNANCHORED regex. It lives here and not in the
+ * caller so those semantics have one home (one-detector-no-drift) —
+ * `hookMatcherIssues` judges a matcher, this one applies it.
+ *
+ * FAIL-OPEN WHERE THE HARNESS IS, AND NOT ONE STEP FURTHER. An absent matcher or
+ * a match-all really does select every tool, so answering `"selects"` there
+ * states a fact — the same direction `decideHookCondition`
+ * (`core/hook-condition.ts`) fails open, and for the same reason it gives: where
+ * Claude Code cannot tell, it RUNS the hook, so mirroring it can only ever add a
+ * run, never invent a skip.
+ *
+ * 🔴 THAT REASONING DOES NOT REACH AN UNCOMPILABLE MATCHER, and this function
+ * used to apply it there anyway. `Bash(` is what the `invalid-regex` finding
+ * above already reports as "the harness can't compile it, so the hook never
+ * fires" — the harness fails CLOSED. Answering `"selects"` therefore does not
+ * add a run the harness makes, it MANUFACTURES one: a caller feeds the hook a
+ * battery it would never have been handed, and an unconditional-deny body scores
+ * a full pass for a hook that cannot run. That is the false-confidence class
+ * this module exists to remove, so an uncompilable matcher gets its own answer
+ * and the caller declines to score it.
+ *
+ * @param matcher - the registration's matcher, or `null` when it declares none.
+ * @param tool - the tool named by the call, e.g. `"Bash"`.
+ * @param style - the active harness's `HookProtocol.matcherStyle`. `"exact"`
+ *   (the default, Claude Code) applies the literal-equality rule above;
+ *   `"regex"` (Codex) compiles EVERY matcher, so `ash` matches `Bash` and the
+ *   glob spellings `*` / `**` — which are Claude Code's documented match-all,
+ *   not regexes — come back `"uncompilable"` rather than being assumed to be
+ *   special-cased by a harness nobody measured.
+ */
+function hookMatcherReach(matcher, tool, style = "exact") {
+    if (matcher === null || matcher === "")
+        return "selects";
+    if (style === "exact") {
+        if (MATCH_ALL.has(matcher))
+            return "selects";
+        if (isLiteralMatcher(matcher))
+            return matcher === tool ? "selects" : "misses";
+    }
+    const re = compileMatcher(matcher);
+    if (re === null)
+        return "uncompilable";
+    return re.test(tool) ? "selects" : "misses";
+}
 //# sourceMappingURL=hook-matcher.js.map

package/dist/core/hook-normalize.d.ts

@@ -56,6 +56,39 @@ export interface HookRegistration {
  * for any non-object / malformed input — never throws.
  */
 export declare function normalizeHooks(raw: unknown): HookRegistration[];
+/**
+ * A declared hook action that carries no command — `prompt`, `http`, `mcp_tool`
+ * or `agent`. Real, supported actions; simply not shell processes, so no tier
+ * that drives a shell can measure one.
+ */
+export interface NonCommandHookAction {
+    /** The event it registers under. */
+    readonly event: string;
+    /** The tool/path matcher of the entry it sits in, or `null`. */
+    readonly matcher: string | null;
+    /** Its declared `type`, e.g. `"prompt"`. Never `"command"`. */
+    readonly type: string;
+}
+/**
+ * The declared actions {@link normalizeHooks} does NOT return, and why anyone
+ * should care.
+ *
+ * 🔴 SILENCE HERE READ AS "NO HOOKS DECLARED", which is the exact false-empty a
+ * guard sweep exists to prevent. Claude Code supports five action types
+ * (command / http / mcp_tool / prompt / agent) and `normalizeHooks` keeps only
+ * the first, correctly — the others are not shell processes and nothing that
+ * spawns a shell can drive them. But a repository whose PreToolUse hooks are all
+ * `prompt` actions then produced an empty registration list, and a caller that
+ * reads only the length cannot tell "this repo declared no guards" from "this
+ * repo declared four guards I cannot run". The first is an accusation; the
+ * second is a limit of the tier. So the dropped actions are RETURNED rather than
+ * discarded, and the caller reports them as declared-but-not-measured.
+ *
+ * A holder counts only when it declares a `type` that is not `"command"`. An
+ * entry with neither a type nor a command is malformed config, not an action,
+ * and calling it one would invent a hook the repository never declared.
+ */
+export declare function nonCommandHookActions(raw: unknown): NonCommandHookAction[];
 /** Distinct event names present in the raw hooks object (object-keyed shape). */
 export declare function hookEventNames(raw: unknown): string[];
 //# sourceMappingURL=hook-normalize.d.ts.map

package/dist/core/hook-normalize.js

@@ -23,6 +23,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeHooks = normalizeHooks;
+exports.nonCommandHookActions = nonCommandHookActions;
 exports.hookEventNames = hookEventNames;
 /**
  * The config key a hook's condition is written under. Read here rather than from
@@ -86,6 +87,50 @@ function normalizeHooks(raw) {
     }
     return out;
 }
+/**
+ * The declared actions {@link normalizeHooks} does NOT return, and why anyone
+ * should care.
+ *
+ * 🔴 SILENCE HERE READ AS "NO HOOKS DECLARED", which is the exact false-empty a
+ * guard sweep exists to prevent. Claude Code supports five action types
+ * (command / http / mcp_tool / prompt / agent) and `normalizeHooks` keeps only
+ * the first, correctly — the others are not shell processes and nothing that
+ * spawns a shell can drive them. But a repository whose PreToolUse hooks are all
+ * `prompt` actions then produced an empty registration list, and a caller that
+ * reads only the length cannot tell "this repo declared no guards" from "this
+ * repo declared four guards I cannot run". The first is an accusation; the
+ * second is a limit of the tier. So the dropped actions are RETURNED rather than
+ * discarded, and the caller reports them as declared-but-not-measured.
+ *
+ * A holder counts only when it declares a `type` that is not `"command"`. An
+ * entry with neither a type nor a command is malformed config, not an action,
+ * and calling it one would invent a hook the repository never declared.
+ */
+function nonCommandHookActions(raw) {
+    if (!isRecord(raw))
+        return [];
+    const out = [];
+    for (const [event, arr] of Object.entries(raw)) {
+        if (!Array.isArray(arr))
+            continue;
+        for (const entry of arr) {
+            if (!isRecord(entry))
+                continue;
+            const matcher = entryMatcher(entry);
+            const nested = entry.hooks;
+            const holders = Array.isArray(nested) ? nested : [entry];
+            for (const h of holders) {
+                if (!isRecord(h))
+                    continue;
+                const type = h.type;
+                if (typeof type !== "string" || type === "" || type === "command")
+                    continue;
+                out.push({ event, matcher, type });
+            }
+        }
+    }
+    return out;
+}
 /** Distinct event names present in the raw hooks object (object-keyed shape). */
 function hookEventNames(raw) {
     return isRecord(raw) ? Object.keys(raw) : [];

package/dist/core/shell-vars.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Which environment variables a shell command actually DEPENDS ON — the
+ * parser-backed answer to "would this command run the same program here?".
+ *
+ * 🔴 WHY A PARSER AND NOT A REGEX, measured. The caller
+ * (`experimental_verifyPluginGuards`) refuses to run a hook whose command names
+ * a variable nothing has set, because running it would measure a different
+ * program than the harness runs. Deciding that with `/\$\{?NAME\}?/` gets two
+ * ordinary shapes wrong, in the direction that costs a measurement:
+ *
+ * | command                          | the shell            | a raw regex   |
+ * | -------------------------------- | -------------------- | ------------- |
+ * | `GUARD=hooks/g.sh; "$GUARD"`     | sets it, then expands| "unset GUARD" |
+ * | `echo '$NOT_A_VAR'`              | no expansion at all  | "unset …"     |
+ *
+ * Both are self-contained commands reported as unresolvable, so a real guard
+ * goes unmeasured for a reason that is not true of it. This is the
+ * `parse-structured-input-with-a-real-parser` rule applied to the same shell
+ * grammar `core/bash-effects.ts` already parses: an ASSIGNMENT and a SINGLE-
+ * QUOTED literal are nodes, so once the command is an AST the two mistakes above
+ * are not expressible.
+ *
+ * 🔴 AND THE PARSER REMOVED TWO WAYS TO BE WRONG WHILE ADDING A THIRD, in the
+ * worse direction. Subtracting every assigned name GLOBALLY excused a read the
+ * assignment never reached, so the sweep ran a differently-configured program
+ * and gave it a score. Measured against `/bin/sh` with the name exported first:
+ *
+ * ```
+ * export X=ambient;   echo "$X"; X=1           → ambient   (read comes FIRST)
+ * export FOO=ambient; FOO=1 sh -c "echo $FOO"  → ambient   (prefix assign does
+ *                                                           not reach its own
+ *                                                           command's words)
+ * (G=inner); printf '[%s]' "$G"                → []        (subshell-scoped)
+ * G=dominates; printf '[%s]' "$G"              → dominates (this one persists)
+ * ```
+ *
+ * So the rule is DOMINANCE, not membership, and CONTROL FLOW, not source order:
+ * an assignment excuses a read only when it is an unconditional top-level
+ * statement (see {@link persistingAssigns}) AND sits before that read. A prefix,
+ * subshell, function-body, backgrounded, conditional or pipelined assignment
+ * excuses nothing at all. Where dominance is not provable, the read stands.
+ *
+ * It does NOT reach into `bash-effects.ts` for the parse: that module's `sh`
+ * handle and node types are private to it, and its types model EFFECTS
+ * (redirections, wrapper heads, flag tables) rather than expansions. The shared
+ * thing is the dependency, not the code — both `require("mvdan-sh")`.
+ *
+ * CONSERVATIVE, ON PURPOSE, IN ONE DIRECTION. Over-reporting a dependency costs
+ * a hook its measurement (the caller says so and names the variable);
+ * under-reporting one lets a differently-configured program be measured and
+ * scored. So where the parser cannot decide, this reports MORE:
+ *
+ * - a parse failure falls back to the regex scan and says `parsed: false`;
+ * - `${FOO:-default}` and `${FOO:?msg}` count as reads even though the first
+ *   always resolves — reading the expansion operator is a further step, and its
+ *   only effect would be to measure more hooks;
+ * - a `for f in …` loop variable is a read (nothing binds it in the AST the way
+ *   an `Assign` does).
+ *
+ * `$1` / `$@` / `$?` are never reads: they are positional and special
+ * parameters, not environment the caller could set.
+ */
+/** What a command reads from its environment. */
+export interface ShellVarReads {
+    /** Names it expands and does not itself assign, first-seen order. */
+    readonly reads: readonly string[];
+    /**
+     * Whether the shell parser accepted the command. `false` means `reads` came
+     * from the regex fallback and may name a variable the command sets itself.
+     */
+    readonly parsed: boolean;
+}
+export declare function shellVarReads(command: string): ShellVarReads;
+//# sourceMappingURL=shell-vars.d.ts.map

package/dist/core/shell-vars.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * Which environment variables a shell command actually DEPENDS ON — the
+ * parser-backed answer to "would this command run the same program here?".
+ *
+ * 🔴 WHY A PARSER AND NOT A REGEX, measured. The caller
+ * (`experimental_verifyPluginGuards`) refuses to run a hook whose command names
+ * a variable nothing has set, because running it would measure a different
+ * program than the harness runs. Deciding that with `/\$\{?NAME\}?/` gets two
+ * ordinary shapes wrong, in the direction that costs a measurement:
+ *
+ * | command                          | the shell            | a raw regex   |
+ * | -------------------------------- | -------------------- | ------------- |
+ * | `GUARD=hooks/g.sh; "$GUARD"`     | sets it, then expands| "unset GUARD" |
+ * | `echo '$NOT_A_VAR'`              | no expansion at all  | "unset …"     |
+ *
+ * Both are self-contained commands reported as unresolvable, so a real guard
+ * goes unmeasured for a reason that is not true of it. This is the
+ * `parse-structured-input-with-a-real-parser` rule applied to the same shell
+ * grammar `core/bash-effects.ts` already parses: an ASSIGNMENT and a SINGLE-
+ * QUOTED literal are nodes, so once the command is an AST the two mistakes above
+ * are not expressible.
+ *
+ * 🔴 AND THE PARSER REMOVED TWO WAYS TO BE WRONG WHILE ADDING A THIRD, in the
+ * worse direction. Subtracting every assigned name GLOBALLY excused a read the
+ * assignment never reached, so the sweep ran a differently-configured program
+ * and gave it a score. Measured against `/bin/sh` with the name exported first:
+ *
+ * ```
+ * export X=ambient;   echo "$X"; X=1           → ambient   (read comes FIRST)
+ * export FOO=ambient; FOO=1 sh -c "echo $FOO"  → ambient   (prefix assign does
+ *                                                           not reach its own
+ *                                                           command's words)
+ * (G=inner); printf '[%s]' "$G"                → []        (subshell-scoped)
+ * G=dominates; printf '[%s]' "$G"              → dominates (this one persists)
+ * ```
+ *
+ * So the rule is DOMINANCE, not membership, and CONTROL FLOW, not source order:
+ * an assignment excuses a read only when it is an unconditional top-level
+ * statement (see {@link persistingAssigns}) AND sits before that read. A prefix,
+ * subshell, function-body, backgrounded, conditional or pipelined assignment
+ * excuses nothing at all. Where dominance is not provable, the read stands.
+ *
+ * It does NOT reach into `bash-effects.ts` for the parse: that module's `sh`
+ * handle and node types are private to it, and its types model EFFECTS
+ * (redirections, wrapper heads, flag tables) rather than expansions. The shared
+ * thing is the dependency, not the code — both `require("mvdan-sh")`.
+ *
+ * CONSERVATIVE, ON PURPOSE, IN ONE DIRECTION. Over-reporting a dependency costs
+ * a hook its measurement (the caller says so and names the variable);
+ * under-reporting one lets a differently-configured program be measured and
+ * scored. So where the parser cannot decide, this reports MORE:
+ *
+ * - a parse failure falls back to the regex scan and says `parsed: false`;
+ * - `${FOO:-default}` and `${FOO:?msg}` count as reads even though the first
+ *   always resolves — reading the expansion operator is a further step, and its
+ *   only effect would be to measure more hooks;
+ * - a `for f in …` loop variable is a read (nothing binds it in the AST the way
+ *   an `Assign` does).
+ *
+ * `$1` / `$@` / `$?` are never reads: they are positional and special
+ * parameters, not environment the caller could set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shellVarReads = shellVarReads;
+// mvdan-sh is a CJS package (GopherJS build) with no bundled TypeScript types —
+// the same require() `core/bash-effects.ts` uses, for the same parser.
+const _sh = require("mvdan-sh");
+const sh = _sh;
+/** A `$NAME` / `${NAME}` reference — not `$(…)`, `$1` or `$@`. */
+const VAR_REF = /\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g;
+/** An environment-variable name: what a caller could put in `env`. */
+const VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The fallback for a command the shell parser rejects: every `$NAME` in it. */
+function scanRefs(command) {
+    const names = new Set();
+    for (const [, name] of command.matchAll(VAR_REF))
+        names.add(name);
+    return [...names];
+}
+/**
+ * The environment variables `command` expands and does not set for itself.
+ *
+ * @param command - the shell command, exactly as the hook registers it.
+ */
+/** A node's byte offset in the source, or `null` when the binding withholds it. */
+function offsetOf(node) {
+    try {
+        return node.Pos().Offset();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where an assignment's effect BEGINS — one byte past its last, not at its first.
+ *
+ * 🔴 THE WHOLE OF THE SELF-REFERENTIAL BUG. The shell expands an assignment's
+ * RHS and only THEN binds the name, so `MODE="$MODE"` reads the environment and
+ * a read inside an initializer can never be dominated by the assignment
+ * containing it. Keyed on the assignment's START, it was: the walk is preorder,
+ * so the `Assign` node was recorded before its own `ParamExp` was visited, the
+ * assignment's offset was the smaller one, and the genuine ambient read
+ * disappeared. `MODE="$MODE"; [ "$MODE" = strict ] && exit 2` therefore reported
+ * NO dependency — so under confinement the sweep cleared `MODE` without saying
+ * so and scored whichever branch the empty value took.
+ *
+ * Keyed on the END, the containment falls out of the arithmetic rather than
+ * needing a special case: a read inside the initializer has a smaller offset
+ * than the assignment's end, so it stands; a read after the statement has a
+ * larger one, so it is excused. Both directions are pinned in the tests.
+ */
+function endOfOrNull(node) {
+    try {
+        return node.End().Offset();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Declaring keywords whose assignment persists into the rest of the SCRIPT.
+ *
+ * `local` is deliberately absent: it is meaningful only inside a function, and
+ * a function body is precisely the scope this walker never treats as reached.
+ */
+const PERSISTING_DECLARATIONS = new Set([
+    "export",
+    "readonly",
+    "declare",
+    "typeset",
+]);
+/**
+ * Offsets of the assignments that excuse a later read — and it is an ALLOWLIST,
+ * which is the whole of the fix. Two shapes are recognized, both TOP-LEVEL
+ * statements of the script and neither detached with `&`: a bare `NAME=value`,
+ * and a {@link PERSISTING_DECLARATIONS} keyword (`export NAME=value`), which the
+ * parser models as a different node for the same persisting statement.
+ *
+ * 🔴 SOURCE ORDER IS NOT CONTROL FLOW, and reading it as such was a third way to
+ * measure a differently-configured program. The earlier version marked the
+ * assignments it could prove do not PERSIST (subshell, function body, command
+ * prefix) and excused every other one that merely appeared earlier in the text —
+ * so an assignment the shell may never execute silently excused the read it
+ * sits before. Measured against `/bin/sh` with the name exported first:
+ *
+ * ```
+ * MODE=safe; [ "$MODE" = safe ]                 → runs, and excuses the read
+ * false && MODE=safe; [ "$MODE" = safe ]        → the AMBIENT value is read
+ * if false; then MODE=safe; fi; [ "$MODE" = x ] → the AMBIENT value is read
+ * MODE=safe & [ "$MODE" = safe ]                → detached: never reaches it
+ * true | MODE=safe; [ "$MODE" = safe ]          → pipeline subshell, discarded
+ * ```
+ *
+ * Four of those five excused the read under the old rule while the real shell
+ * went on reading the environment. Under confinement the sweep clears that
+ * environment, so it would have run the `MODE`-unset arm of a guard and scored
+ * whatever that arm happens to do.
+ *
+ * An allowlist rather than a longer denylist because the denylist can only ever
+ * be as complete as the grammar we remembered: `Subshell` and `FuncDecl` were on
+ * it, `BinaryCmd`, `IfClause`, `WhileClause`, `ForClause`, `CaseClause`, `Block`
+ * and a backgrounded `Stmt` were not, and the next construct would not be
+ * either. Inverting it makes the unlisted case default to "excuses nothing",
+ * which is the direction this module already errs in (see the header): an
+ * assignment we cannot place costs a measurement, never a false score.
+ *
+ * The cost is named rather than hidden: `{ MODE=safe; }; echo "$MODE"` does run
+ * unconditionally in this shell and is no longer excused. A brace group at the
+ * top of a hook command is rare, and reporting `MODE` as a dependency there ends
+ * in `unresolved` with the name printed — the safe error.
+ */
+function persistingAssigns(file) {
+    // start offset → the offset its binding takes effect at (see endOfOrNull).
+    const unconditional = new Map();
+    const take = (node) => {
+        const at = offsetOf(node);
+        const effective = endOfOrNull(node);
+        // A binding whose extent the parser withheld cannot be shown to dominate
+        // anything, so it is not recorded and every read of the name stands.
+        if (at !== null && effective !== null)
+            unconditional.set(at, effective);
+    };
+    for (const stmt of file.Stmts ?? []) {
+        // `&` detaches into a subshell, so the assignment never reaches this one.
+        if (stmt.Background === true)
+            continue;
+        const cmd = stmt.Cmd;
+        if (!cmd)
+            continue;
+        const kind = sh.syntax.NodeType(cmd);
+        // `export NAME=value` is a DeclClause, not a CallExpr — a separate node for
+        // the same persisting, unconditional statement. Its `Args` ARE the `Assign`
+        // nodes, so walking it reaches exactly them.
+        if (kind === "DeclClause") {
+            if (!PERSISTING_DECLARATIONS.has(cmd.Variant?.Value ?? ""))
+                continue;
+            sh.syntax.Walk(cmd, (node) => {
+                if (node && sh.syntax.NodeType(node) === "Assign")
+                    take(node);
+                return true;
+            });
+            continue;
+        }
+        if (kind !== "CallExpr")
+            continue;
+        // A `CallExpr` with WORDS carries prefix assignments (`FOO=1 cmd`), which do
+        // not outlive their own command; one with no words IS the assignment
+        // statement (`FOO=1`), which persists into the rest of the script.
+        if ((cmd.Args?.length ?? 0) > 0)
+            continue;
+        for (const assign of cmd.Assigns ?? [])
+            take(assign);
+    }
+    return unconditional;
+}
+function shellVarReads(command) {
+    let file;
+    try {
+        file = sh.syntax.NewParser().Parse(command, "hook.sh");
+    }
+    catch {
+        return { reads: scanRefs(command), parsed: false };
+    }
+    const unconditional = persistingAssigns(file);
+    const assignedAt = new Map();
+    const reads = [];
+    const seen = new Set();
+    sh.syntax.Walk(file, (node) => {
+        if (!node)
+            return true;
+        const kind = sh.syntax.NodeType(node);
+        const at = offsetOf(node);
+        if (kind === "Assign") {
+            const name = node.Name?.Value;
+            // The FIRST unconditional assignment is the only one that can dominate
+            // a read; a later one cannot reach backwards. What is stored is where the
+            // binding TAKES EFFECT (the assignment's end), not where it is written —
+            // see {@link endOfOrNull}.
+            const effective = at === null ? undefined : unconditional.get(at);
+            if (name !== undefined && name !== "" && effective !== undefined)
+                if (!assignedAt.has(name))
+                    assignedAt.set(name, effective);
+        }
+        else if (kind === "ParamExp") {
+            const name = node.Param?.Value;
+            if (name !== undefined && VAR_NAME.test(name) && !seen.has(name)) {
+                // 🔴 DOMINANCE, NOT MEMBERSHIP, AND CONTROL FLOW, NOT SOURCE ORDER.
+                // Subtracting every assigned name globally excused `echo "$GUARD";
+                // GUARD=hooks/g.sh` — where the expansion runs FIRST and really does
+                // read the environment. Counting an earlier OFFSET as dominance excused
+                // `false && MODE=safe; [ "$MODE" = safe ]`, which the shell also reads
+                // from the environment. Both let a differently-configured program be
+                // measured and scored, so an assignment excuses a read only when
+                // {@link persistingAssigns} proved it runs, and runs first — where
+                // "first" means it has FINISHED, because `MODE="$MODE"` expands its RHS
+                // before it binds the name (see {@link endOfOrNull}).
+                const assigned = assignedAt.get(name);
+                // `at === null` means the binding withheld the position: excuse nothing.
+                if (assigned === undefined || at === null || assigned > at) {
+                    seen.add(name);
+                    reads.push(name);
+                }
+            }
+        }
+        return true;
+    });
+    return { reads, parsed: true };
+}
+//# sourceMappingURL=shell-vars.js.map

package/dist/guardrail-check.d.ts

@@ -109,6 +109,21 @@ export declare function unblockedDisasters(results: readonly GuardrailResult[]):
  * build instead of failing in production.
  */
 export declare function assertBlocksDisasters(hookCommand: string, opts?: VerifyGuardrailOptions): void;
+/**
+ * One battery event as a report line, WITHOUT leading indentation so each caller
+ * nests it where its own layout needs.
+ *
+ * THREE outcomes, not two. "never run" is not a weaker "allows": the harness
+ * would not invoke this hook for that call at all, so the guard has no opinion
+ * to report. Printing it as `allows` is what made a conditional guard look like
+ * it had considered — and permitted — commands it can never see.
+ *
+ * @internal Shared by {@link formatGuardrailReport} and the directory-level
+ * sweep's formatter (`experimental_formatPluginGuardReport`), so the two renderers
+ * cannot drift into two vocabularies for the same three outcomes. Not part of the
+ * public API — a caller wanting these lines wants one of the two reports.
+ */
+export declare function guardrailRow(result: GuardrailResult): string;
 /**
  * Render a coverage report (informational, NEUTRAL). It reports what the
  * hook blocks WITHOUT judging it: a hook that allows these may simply not be a

package/dist/guardrail-check.js

@@ -5,6 +5,7 @@ exports.experimental_alternateSpellings = experimental_alternateSpellings;
 exports.verifyGuardrail = verifyGuardrail;
 exports.unblockedDisasters = unblockedDisasters;
 exports.assertBlocksDisasters = assertBlocksDisasters;
+exports.guardrailRow = guardrailRow;
 exports.formatGuardrailReport = formatGuardrailReport;
 /**
  * Guardrail verification — "prove your safety hook ACTUALLY blocks."
@@ -32,6 +33,7 @@ exports.formatGuardrailReport = formatGuardrailReport;
  */
 const bash_equivalents_js_1 = require("./core/bash-equivalents.js");
 const run_hook_js_1 = require("./run-hook.js");
+const run_script_js_1 = require("./run-script.js");
 /**
  * The curated battery. Deliberately small and high-signal: each is a textbook
  * destructive action a real safety hook in the wild claims to stop. Extend with
@@ -173,6 +175,27 @@ function verifyGuardrail(hookCommand, opts = {}) {
             tool_name: event.tool,
             tool_input: event.input,
         }, opts);
+        // 🔴 A PROGRAM THE SHELL NEVER LAUNCHED HAS NO OPINION, so it must not be
+        // reported as one. 126 ("found, not executable") and 127 ("not found") are
+        // the SHELL's own codes — not a language's exit convention and not a guess
+        // about stderr text — and they arrive when the interpreter is missing, the
+        // file is not executable, or the shebang is wrong. Left alone, they read as
+        // `ran and allowed`, which accuses a guard of letting a disaster through
+        // when it was never asked. Folding them into the existing not-run channel
+        // means `assertBlocksDisasters` and both renderers say WHY for free, and the
+        // verdict is unchanged: a guard that cannot start still protects nothing.
+        //
+        // ⚠️ ONLY WHEN NOTHING BLOCKED. `echo '{"…deny…}'; ./missing` exits 127 with
+        // a real deny on stdout; reclassifying that would hide a decision the hook
+        // genuinely made. The exit code loses to the decision, never the reverse.
+        if (!r.blocked && r.ran && (0, run_script_js_1.shellNeverLaunched)(r.exitCode))
+            return {
+                event,
+                blocked: false,
+                exitCode: r.exitCode,
+                ran: false,
+                reason: `the shell never launched this hook (exit ${String(r.exitCode)}: ${r.exitCode === 127 ? "command not found" : "not executable"}) — nothing here is the guard's decision`,
+            };
         return {
             event,
             blocked: r.blocked,
@@ -203,6 +226,25 @@ function assertBlocksDisasters(hookCommand, opts = {}) {
         : `  ⊘ ${m.event.label} — NOT RUN: ${m.reason}`);
     throw new Error(`Guardrail \`${hookCommand}\` did NOT block ${misses.length} dangerous action(s):\n${lines.join("\n")}\nA hook that doesn't block these is false confidence — fix it (PreToolUse + exit 2).`);
 }
+/**
+ * One battery event as a report line, WITHOUT leading indentation so each caller
+ * nests it where its own layout needs.
+ *
+ * THREE outcomes, not two. "never run" is not a weaker "allows": the harness
+ * would not invoke this hook for that call at all, so the guard has no opinion
+ * to report. Printing it as `allows` is what made a conditional guard look like
+ * it had considered — and permitted — commands it can never see.
+ *
+ * @internal Shared by {@link formatGuardrailReport} and the directory-level
+ * sweep's formatter (`experimental_formatPluginGuardReport`), so the two renderers
+ * cannot drift into two vocabularies for the same three outcomes. Not part of the
+ * public API — a caller wanting these lines wants one of the two reports.
+ */
+function guardrailRow(result) {
+    if (!result.ran)
+        return `⊘ not run  ${result.event.label} — ${result.reason}`;
+    return `${result.blocked ? "✅ blocks" : "·  allows"}  ${result.event.label}`;
+}
 /**
  * Render a coverage report (informational, NEUTRAL). It reports what the
  * hook blocks WITHOUT judging it: a hook that allows these may simply not be a
@@ -214,15 +256,7 @@ function formatGuardrailReport(hookCommand, results) {
     const blocked = results.filter((r) => r.blocked).length;
     const skipped = results.filter((r) => !r.ran).length;
     const head = `Guardrail coverage for \`${hookCommand}\` — blocks ${blocked}/${results.length} of the dangerous battery`;
-    const rows = results.map((r) => {
-        // THREE outcomes, not two. "never run" is not a weaker "allows": the harness
-        // would not invoke this hook for that call at all, so the guard has no opinion
-        // to report. Printing it as `allows` is what made a conditional guard look
-        // like it had considered — and permitted — commands it can never see.
-        if (!r.ran)
-            return `  ⊘ not run  ${r.event.label} — ${r.reason}`;
-        return `  ${r.blocked ? "✅ blocks" : "·  allows"}  ${r.event.label}`;
-    });
+    const rows = results.map((r) => `  ${guardrailRow(r)}`);
     const foot = [
         blocked < results.length
             ? "\nAllows ≠ a bug unless this guard is MEANT to block them — gate intent with\nassertBlocksDisasters(cmd, { categories: [...] })."