vigiles 15.0.3 → 15.2.0

package/dist/core/hook-program.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineReact = exports.nothing = exports.notice = exports.run = exports.defineInject = exports.inject = exports.tools = exports.HookCompileError = exports.tool = exports.ask = exports.deny = exports.allow = void 0;
+exports.nothing = exports.notice = exports.run = exports.inject = exports.tools = exports.HookCompileError = exports.tool = exports.ask = exports.deny = exports.allow = void 0;
+exports.matchesTool = matchesTool;
+exports.invalidToolPatterns = invalidToolPatterns;
 exports.gateAction = gateAction;
 exports.trimTrailingSeparators = trimTrailingSeparators;
 exports.commandView = commandView;
@@ -24,9 +26,13 @@ exports.definePromptGate = definePromptGate;
 exports.decidePromptGate = decidePromptGate;
 exports.defineStopGate = defineStopGate;
 exports.decideStopGate = decideStopGate;
+exports.defineInject = defineInject;
 exports.runInject = runInject;
+exports.injectionOf = injectionOf;
 exports.responseView = responseView;
+exports.defineReact = defineReact;
 exports.runReact = runReact;
+exports.outcomeWrites = outcomeWrites;
 exports.rememberHookSource = rememberHookSource;
 exports.hookSource = hookSource;
 exports.runHookProgram = runHookProgram;
@@ -69,6 +75,69 @@ const toml_1 = require("@iarna/toml");
 const hook_events_js_1 = require("./hook-events.js");
 const merge_conflict_js_1 = require("./merge-conflict.js");
 const hook_providers_js_1 = require("./hook-providers.js");
+const hook_state_js_1 = require("./hook-state.js");
+/**
+ * Does `name` match a hook's declared tool list, under the SAME semantics as the
+ * matcher the compiler emits for it?
+ *
+ * 🔴 IT DID NOT, AND THE DISAGREEMENT WAS SILENT. `hookRouting` joins a react's
+ * tools with `|` and emits that as the harness matcher, and a Claude Code matcher
+ * is a REGEX — `Edit|Write|MultiEdit` only works because it is one. The runtime
+ * meanwhile compared with `Array.includes`, i.e. exact string equality. So a hook
+ * declaring a tool FAMILY compiled fine, was wired up fine, was routed to by the
+ * harness fine, and was then dropped by vigiles' own filter without a word.
+ *
+ * MEASURED 2026-08-12 against the real runtime, before the fix:
+ *
+ *   $ echo '{"tool_name":"mcp__4f54037d-0499__list_events",…}' \
+ *       | vigiles hook-runtime run-program mcp-family.hook.mjs
+ *   exit=0                       # silence — react() never ran
+ *   $ echo '{"tool_name":"mcp__.*",…}' | …
+ *   FIRED on mcp__.*             # fires only for a tool LITERALLY named "mcp__.*"
+ *
+ * That is the false-confidence class this whole subsystem exists to eliminate,
+ * living inside the subsystem. The live evidence that the harness really does
+ * route these: the knowledge base has shipped `"matcher": "mcp__.*"` in
+ * `.claude/settings.json` for months and its stamp file was last written the
+ * morning this was measured. The MCP server's id changes per session, so an exact
+ * list cannot be written down — a family matcher is the only correct spelling.
+ *
+ * Anchored `^(…)$` so a pattern cannot match a longer tool name by accident, and
+ * identical to `includes` for ordinary names, which contain no metacharacters.
+ * An unparseable pattern is rejected at COMPILE ({@link invalidToolPatterns}), so
+ * the fallback here is unreachable in a compiled hook and exists only so that a
+ * hand-constructed one degrades to exact matching rather than throwing mid-event.
+ */
+function matchesTool(tools, name) {
+    // An EMPTY list matches NOTHING. Found by a mutation that was meant to disable
+    // tool-less reacts and didn't: with no tools the joined pattern is `^()$`,
+    // which matches the EMPTY STRING — and a tool-less event's name is the empty
+    // string. Without this line `tools()` would quietly be a catch-all on exactly
+    // the events where a react has no tool to check. Declaring nothing must mean
+    // nothing, not everything.
+    if (tools.length === 0)
+        return false;
+    if (tools.includes(name))
+        return true;
+    try {
+        return new RegExp(`^(${tools.join("|")})$`).test(name);
+    }
+    catch {
+        return false;
+    }
+}
+/** Tool patterns that are not valid regexes — rejected at compile, see {@link matchesTool}. */
+function invalidToolPatterns(tools) {
+    return tools.filter((t) => {
+        try {
+            new RegExp(`^(${t})$`);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    });
+}
 const allow = () => ({ kind: "allow" });
 exports.allow = allow;
 const deny = (reason) => ({ kind: "deny", reason });
@@ -371,6 +440,18 @@ function writeTargetsOf(leaf) {
             return [];
     }
 }
+/**
+ * A write target as it lands on disk, given the chdir wrapper the leaf ran under
+ * (`env -C migratsiya sed -i s/a/b/ papers/x.tex` writes `migratsiya/papers/x.tex`).
+ *
+ * Absolute targets and `~`-rooted ones already name their directory and are
+ * returned untouched. The join itself is {@link resolveRef} rather than a fresh
+ * `a + "/" + b`, because two functions normalising the same string differently is
+ * the defect class this file keeps finding.
+ */
+const underChdir = (target, chdir) => chdir === null || target === "" || target.startsWith("~")
+    ? target
+    : resolveRef(chdir, target);
 /**
  * An AST-backed view of a Bash command.
  *
@@ -388,10 +469,20 @@ function commandView(raw, root) {
     // The operation-normalized leaves carry the redirections (and quote-unwrapped,
     // wrapper-resolved argv) that `writesTo` needs; `leafCommands` cannot see them.
     const normalized = (0, bash_effects_js_1.leafCommandsNormalized)(raw);
-    const writeTargets = normalized.flatMap((leaf) => [
+    const allWriteTargets = normalized.flatMap((leaf) => [
+        // 🔴 A REDIRECTION IS NOT JOINED ONTO THE LEAF'S CHDIR, AND THAT IS THE
+        // SHELL'S RULE, NOT A SHORTCUT. `env -C dir cmd > out.txt` opens `out.txt`
+        // in the SHELL's directory — the redirection happens before `env` ever runs
+        // and `-C` only moves the process `env` execs. Joining here would report a
+        // file the command never writes.
         ...leaf.redirects.flatMap((r) => r.writes && r.target !== null ? [r.target] : []),
-        ...writeTargetsOf(leaf),
+        // The wrapped program's own operands DO resolve against it — see
+        // `NormalizedLeaf.chdir` for why the value was being read and discarded.
+        ...writeTargetsOf(leaf).map((t) => underChdir(t, leaf.chdir)),
     ]);
+    const matchedWriteTargets = (prefixes) => [
+        ...new Set(allWriteTargets.filter((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match")))),
+    ];
     return {
         raw,
         runs(program, opts) {
@@ -432,7 +523,13 @@ function commandView(raw, root) {
             ? [tok, tok.slice(tok.indexOf("=") + 1)]
             : [tok])
             .some((tok) => prefixes.some((p) => matchesPrefix(prefixVerdict(tok, p, root), "match"))),
-        writesTo: (prefixes) => writeTargets.some((t) => prefixes.some((p) => matchesPrefix(prefixVerdict(t, p, root), "match"))),
+        // DERIVED, not a second implementation of the same rule. The boolean stays
+        // because `writesTo(secrets) ? deny() : allow()` is the common gate shape,
+        // but it is a PROJECTION of the list — one code path, so the two can never
+        // drift the way `runs()` and `writesTo` did (one reads raw leaves, the other
+        // normalized ones, and a gate built on both had a silent hole).
+        writesTo: (prefixes) => matchedWriteTargets(prefixes).length > 0,
+        writeTargets: matchedWriteTargets,
         pipesToShell: () => leaves.some(isBareShellLeaf),
     };
 }
@@ -523,6 +620,9 @@ function hookRouting(hook) {
             hook.role === "prompt-gate" ||
             hook.role === "stop-gate")
             return { on: hook.on };
+        // A react MAY also be tool-less (Stop/SessionEnd) — same shape, same reason.
+        if (hook.match === undefined)
+            return { on: hook.on };
         return { on: hook.on, matcher: hook.match.tools.join("|") };
     }
     return { on: hook.on, matcher: hook.match.tool };
@@ -569,6 +669,16 @@ function compileHookProgram(source, hook, opts = {}) {
         throw new HookCompileError(`hook program uses capabilities outside \`${ALLOWED_IMPORT}\`: ${violations.join(", ")} — only the sanctioned API is allowed (capability = API surface).`);
     }
     const { on, matcher: rawMatcher } = hookRouting(hook);
+    // A tool pattern that is not a valid regex cannot match under the semantics the
+    // emitted matcher is read with, so it would compile to a hook that never fires.
+    // Reject it here rather than let `matchesTool` fall back silently.
+    if ("match" in hook && hook.match !== undefined && "tools" in hook.match) {
+        const bad = invalidToolPatterns(hook.match.tools);
+        if (bad.length > 0) {
+            throw new HookCompileError(`invalid tool matcher pattern(s): ${bad.join(", ")} — a tool matcher is a ` +
+                `regex (that is why "Edit|Write" works), so it must parse as one.`);
+        }
+    }
     // A hook registered under an event the harness never fires is dead — reject it.
     if (opts.dialect) {
         const issues = (0, hook_events_js_1.verifyHookEvents)([on], opts.dialect);
@@ -809,7 +919,8 @@ function defineFileGate(p) {
  */
 function decideFileGate(hook, raw, ctx = {}, root = typeof raw.cwd === "string" ? raw.cwd : undefined) {
     const t = raw.tool_name ?? "";
-    if (!hook.match.tools.includes(t))
+    // Same matcher semantics as the emitted settings block — see {@link matchesTool}.
+    if (!matchesTool(hook.match.tools, t))
         return (0, exports.allow)();
     const fp = typeof raw.tool_input?.file_path === "string"
         ? raw.tool_input.file_path
@@ -844,23 +955,30 @@ function decideStopGate(hook, raw, ctx = {}) {
         ctx: ctx,
     });
 }
-const inject = (context) => ({
+/**
+ * Context to add, plus any facts that just became true:
+ * `inject(text, record("calendar.nagged"))`.
+ *
+ * The writes are trailing arguments on every output builder, so there is one rule
+ * to learn rather than a per-role spelling — and a hook that records nothing is
+ * written exactly as it was before.
+ */
+const inject = (context, ...records) => ({
     kind: "inject",
     context,
+    records,
 });
 exports.inject = inject;
-const defineInject = (p) => ({
-    role: "inject",
-    ...p,
-});
-exports.defineInject = defineInject;
+function defineInject(p) {
+    return { role: "inject", ...p };
+}
 /**
  * Run an inject hook → the CC JSON the author never hand-writes. The compiler
  * targets `additionalContext` (the RIGHT field for this event), so the
  * wrong-JSON-field pain can't occur.
  */
-function runInject(hook, raw) {
-    const out = hook.produce({ event: hook.on, source: raw.source ?? "startup" });
+function runInject(hook, raw, ctx = {}) {
+    const out = injectionOf(hook, raw, ctx);
     return {
         hookSpecificOutput: {
             hookEventName: hook.on,
@@ -868,6 +986,14 @@ function runInject(hook, raw) {
         },
     };
 }
+/** The full {@link Injection} — the runtime needs its `records`, which the CC JSON drops. */
+function injectionOf(hook, raw, ctx = {}) {
+    return hook.produce({
+        event: hook.on,
+        source: raw.source ?? "startup",
+        ctx: ctx,
+    });
+}
 /** Normalize an arbitrary tool_response payload to text (object → JSON). */
 function responseText(raw) {
     if (typeof raw === "string")
@@ -888,36 +1014,55 @@ function responseView(raw) {
         contains: (needle) => text.includes(needle),
     };
 }
-/** Run a command in reaction — its effect is classified AT CONSTRUCTION (audit/diff-able). */
-const run = (command) => ({
+/**
+ * Run a command in reaction — its effect is classified AT CONSTRUCTION
+ * (audit/diff-able). Trailing arguments record facts.
+ *
+ * ⚠️ `run()` is for invoking a real TOOL. Using it to write a stamp
+ * (`run("date +%s > .claude/.stamp")`) was the only way to remember anything
+ * before `record()` existed; it is now the wrong tool — it spends a subprocess
+ * and a shell on a variable assignment, and it classifies as side-effecting.
+ */
+const run = (command, ...records) => ({
     kind: "run",
     command,
     effect: (0, bash_effects_js_1.classifyBashCommand)(command),
+    records,
 });
 exports.run = run;
-/** Surface a non-blocking note (no execution). */
-const notice = (message) => ({
+/** Surface a non-blocking note (no execution). Trailing arguments record facts. */
+const notice = (message, ...records) => ({
     kind: "notice",
     message,
+    records,
 });
 exports.notice = notice;
-/** Do nothing. */
-const nothing = () => ({ kind: "none" });
-exports.nothing = nothing;
-const defineReact = (p) => ({
-    role: "react",
-    ...p,
+/**
+ * Take no action. Trailing arguments still record facts — `nothing(record("x"))`
+ * is the shape of a hook whose entire job is to WITNESS that something happened
+ * (an MCP call, a deploy) so a different hook can read it later.
+ */
+const nothing = (...records) => ({
+    kind: "none",
+    records,
 });
-exports.defineReact = defineReact;
+exports.nothing = nothing;
+function defineReact(p) {
+    return { role: "react", ...p };
+}
 /**
  * Run a react hook against a raw PostToolUse event → the (classified) Reaction.
  *
  * `root` behaves exactly as in {@link decideFileGate}: the event's own `cwd` by
- * default, the CLI's {@link projectRootOf} when the runtime supplies one.
+ * default, the CLI's {@link projectRootOf} when the runtime supplies one. It
+ * trails `ctx` so the argument order matches {@link decideProgram} and
+ * {@link decideFileGate} — every decode function reads `(hook, raw, ctx, root)`.
  */
-function runReact(hook, raw, root = typeof raw.cwd === "string" ? raw.cwd : undefined) {
+function runReact(hook, raw, ctx = {}, root = typeof raw.cwd === "string" ? raw.cwd : undefined) {
     const t = raw.tool_name ?? "";
-    if (!hook.match.tools.includes(t))
+    // No `match` → a tool-less event (Stop/SessionEnd): there is nothing to filter
+    // on, and filtering on the empty string is how these hooks used to die.
+    if (hook.match !== undefined && !matchesTool(hook.match.tools, t))
         return (0, exports.nothing)();
     const fp = typeof raw.tool_input?.file_path === "string"
         ? raw.tool_input.file_path
@@ -927,8 +1072,23 @@ function runReact(hook, raw, root = typeof raw.cwd === "string" ? raw.cwd : unde
         tool: t,
         path: pathView(fp, root),
         response: responseView(raw.tool_response),
+        ctx: ctx,
     });
 }
+/**
+ * The state writes an outcome declares, filtered to the ones the runtime may
+ * actually perform. A gate's `Decision` carries none — deliberately: a gate is
+ * the role that must be trustworthy and runs on every tool call, so it READS
+ * state (via `needs`) and never writes it. Adding a write there later is easy;
+ * removing one would not be.
+ */
+function outcomeWrites(outcome) {
+    if (outcome.kind === "injection")
+        return (0, hook_state_js_1.admissibleWrites)(outcome.records);
+    if (outcome.kind === "reaction")
+        return (0, hook_state_js_1.admissibleWrites)(outcome.reaction.records);
+    return (0, hook_state_js_1.admissibleWrites)([]);
+}
 /**
  * The file a hook program was LOADED from — the one coverage attribution in this
  * codebase that needs no parsing at all.
@@ -989,16 +1149,14 @@ function runHookProgram(hook, event, ctx = {}, root = event.cwd) {
                 kind: "decision",
                 decision: decideStopGate(hook, event, ctx),
             };
-        case "inject":
-            return {
-                kind: "injection",
-                context: runInject(hook, event).hookSpecificOutput
-                    .additionalContext,
-            };
+        case "inject": {
+            const out = injectionOf(hook, event, ctx);
+            return { kind: "injection", context: out.context, records: out.records };
+        }
         case "react":
             return {
                 kind: "reaction",
-                reaction: runReact(hook, event, root),
+                reaction: runReact(hook, event, ctx, root),
             };
         default:
             return (0, hash_js_1.assertNever)(kind);
@@ -1027,6 +1185,48 @@ function runHookProgram(hook, event, ctx = {}, root = event.cwd) {
 function isAbsoluteRef(ref) {
     return ref.startsWith("/") || /^[A-Za-z]:\//.test(ref);
 }
+/**
+ * Does this ROOT name a Windows filesystem? One predicate, because the two
+ * questions that ask it — how many segments `..` may not pop through, and
+ * whether a `//` leader is a share or a stutter — must never disagree about the
+ * same root. `//x` is caught by the second arm: too short to be a share, but
+ * still not something to read as POSIX.
+ */
+const namesWindowsFs = (root) => WINDOWS_ROOT.test(root) || root.startsWith("//");
+/**
+ * How many leading segments of a resolved path ARE its root — the floor a `..`
+ * must not pop through. `0` on POSIX, `1` for a drive (`C:`), `2` for a UNC
+ * share (`//server/share`), and 2/4 for the `//?/` spellings of those two.
+ *
+ * 🔴 A `//` LEADER IS THE ROOT'S ANSWER, NEVER THE OPERAND'S — the round-37
+ * lesson at a third site (after the case fold in {@link caseInsensitiveFs} and
+ * the UNC leader in {@link resolveRef}). Read from the string alone,
+ * `//repo/a/../src/x.ts` looks share-rooted, so a count taken off the operand
+ * would guard `repo/a` and stop `..` collapsing at all — under a POSIX root that
+ * doubled slash is a stutter, not a share. The `//` forms are therefore gated on
+ * the root, exactly as the leader is.
+ *
+ * ⚠️ A DRIVE LETTER IS THE ONE THING THAT NAMES A WINDOWS FILESYSTEM BY ITSELF,
+ * and that is not a second rule — {@link isAtOrUnder} already says it about a
+ * base (`WINDOWS_ROOT.test(rawBase)`), because `C:/x` has no POSIX reading the
+ * way `//x` does. It earns its place at a real call site rather than in the
+ * abstract: {@link absoluteSpelling} resolves a ROOTLESS absolute path against
+ * the literal `"/"`, so gating the drive on the root too would leave
+ * `C:/../repo/x` still losing its drive right there — the sibling call site a
+ * fix written only where the defect was found would have missed.
+ *
+ * The count itself is read off {@link WINDOWS_ROOT} rather than re-derived,
+ * because that regex already IS this file's single answer to "what is a Windows
+ * root"; the two forms and the `//?/` spelling are enumerated there, once.
+ */
+const rootSegmentCount = (joined, root) => {
+    const matched = WINDOWS_ROOT.exec(joined)?.[0];
+    if (matched === undefined)
+        return 0; // POSIX, or relative: no root inside `out`
+    if (/^[/\\]/.test(matched) && !namesWindowsFs(root))
+        return 0; // stutter, not share
+    return matched.split(/[/\\]+/).filter((s) => s !== "").length;
+};
 /**
  * Resolve a path reference against a root, without node:path (core stays
  * dependency-free). Mirrors `resolve(root, ref)`: an absolute ref wins, a
@@ -1048,12 +1248,27 @@ function resolveRef(root, ref) {
     const joined = isAbsoluteRef(r)
         ? r
         : `${slashes(root).replace(/\/+$/, "")}/${r}`;
+    // 🔴 `..` CLAMPS AT THE ROOT, IT DOES NOT EAT IT. A real filesystem holds
+    // still at the top: on Windows `C:/..` is `C:/`, on POSIX `/..` is `/`. An
+    // unconditional `out.pop()` popped the DRIVE LETTER out of `C:/../repo/src/x`,
+    // leaving the relative-looking `repo/src/x` — which then failed to resolve
+    // against `C:/repo`, so a gate stopped recognising a path naming its own
+    // repository. A UNC share went one worse: two `..` ate `share` and then
+    // `server`.
+    //
+    // ⚠️ POSIX WAS ALREADY CORRECT BY ACCIDENT, and the accident is worth naming
+    // so nobody "simplifies" it back: its leader `/` is held OUTSIDE `out` (see
+    // the leader below), so popping an empty array is already the clamp. The
+    // Windows forms broke precisely because their root lives INSIDE `out` —
+    // exactly the segments the loop treats as ordinary directories.
+    const floor = rootSegmentCount(joined, root);
     const out = [];
     for (const seg of joined.split("/")) {
         if (seg === "" || seg === ".")
             continue;
         if (seg === "..") {
-            out.pop();
+            if (out.length > floor)
+                out.pop();
             continue;
         }
         out.push(seg);
@@ -1071,8 +1286,7 @@ function resolveRef(root, ref) {
     // stutter, so preserving the pair unconditionally made it stop resolving
     // against a POSIX root and an allowlist gate denied a valid edit. Semantics
     // belong to the filesystem, and only the root knows which one that is.
-    const unc = joined.startsWith("//") &&
-        (WINDOWS_ROOT.test(root) || root.startsWith("//"));
+    const unc = joined.startsWith("//") && namesWindowsFs(root);
     const leader = unc ? "//" : joined.startsWith("/") ? "/" : "";
     return leader + out.join("/");
 }

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

@@ -1,3 +1,4 @@
+import { type StateEntry, type StateFact, type StateNeed } from "./hook-state.js";
 /** The closed set of built-in facts a gate may declare via `needs`, with value types. */
 export interface ProviderResults {
     /** The current git branch, or "" outside a git repo / on an unborn HEAD. */
@@ -27,8 +28,16 @@ export interface InlineProvider<Name extends string = string> {
     readonly run: string;
     readonly dangerous: boolean;
 }
-/** A `needs` entry — a built-in name, an inline `provide`/`dangerously`, or a `provider()` ref. */
-export type NeedSpec = ProviderName | InlineProvider | RegisteredRef;
+/**
+ * A `needs` entry — a built-in name, an inline `provide`/`dangerously`, a
+ * `provider()` ref, or a `state()` read of a fact some hook recorded.
+ *
+ * `state()` rides this union rather than getting its own accessor so that ALL of
+ * a hook's external inputs stay in one declared list: the dependency is auditable
+ * from outside the hook, and reading an undeclared one is a `tsc` error. See the
+ * design note in `hook-state.ts`.
+ */
+export type NeedSpec = ProviderName | InlineProvider | RegisteredRef | StateNeed;
 /**
  * Declare an INLINE read-only fact: `provide("k8sCtx", "kubectl config current-context")`.
  * The command MUST be provably read-only (compile rejects it otherwise — use
@@ -71,8 +80,8 @@ export interface RegisteredRef<Name extends string = string> {
 export declare const provider: <const Name extends string>(name: Name) => RegisteredRef<Name>;
 /** name → its registered provider; the runtime resolves a `provider(name)` ref against this. */
 export type ProviderRegistry = Record<string, RegisteredProvider>;
-type NeedName<E extends NeedSpec> = E extends ProviderName ? E : E extends InlineProvider<infer Nm> ? Nm : E extends RegisteredRef<infer Rn> ? Rn : never;
-type NeedValue<E extends NeedSpec> = E extends ProviderName ? ProviderResults[E] : string;
+type NeedName<E extends NeedSpec> = E extends ProviderName ? E : E extends InlineProvider<infer Nm> ? Nm : E extends RegisteredRef<infer Rn> ? Rn : E extends StateNeed<infer Sn> ? Sn : never;
+type NeedValue<E extends NeedSpec> = E extends ProviderName ? ProviderResults[E] : E extends StateNeed ? StateFact : string;
 /**
  * The typed `e.ctx` for a hook that declared `needs: N` — ONLY the declared facts
  * are present (built-in name → its typed value, inline → string), so reading an
@@ -95,6 +104,14 @@ export interface ProviderIO {
     readonly platform: NodeJS.Platform;
     /** Whether the process is on a CI server (the CLI injects `ci-info`'s verdict). */
     readonly isCI: boolean;
+    /**
+     * Read one recorded fact from THIS hook's state namespace, or `null` if it was
+     * never recorded. The namespace is resolved by the caller, so a key can never
+     * address another owner's store — see `hook-state.ts`.
+     */
+    readonly readState: (key: string) => StateEntry | null;
+    /** Epoch milliseconds, injected so fact ages are pinnable in a test. */
+    readonly now: number;
 }
 interface ProviderDef<K extends ProviderName> {
     /**
@@ -133,6 +150,6 @@ export declare function unsafeProvider(def: RegisteredProvider): boolean;
  * throws. Pure over the injected `io` (CLI passes a real execSync; tests a fake)
  * and the `registry` (the loaded `.vigiles/providers/`, for `provider()` refs).
  */
-export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Record<string, string | boolean>;
+export declare function gatherContext(needs: readonly NeedSpec[], io: ProviderIO, registry?: ProviderRegistry): Record<string, string | boolean | StateFact>;
 export {};
 //# sourceMappingURL=hook-providers.d.ts.map

package/dist/core/hook-providers.js

@@ -26,6 +26,7 @@ exports.gatherContext = gatherContext;
  * testable with a fake exec and core depends on no child_process.
  */
 const bash_effects_js_1 = require("./bash-effects.js");
+const hook_state_js_1 = require("./hook-state.js");
 /**
  * Declare an INLINE read-only fact: `provide("k8sCtx", "kubectl config current-context")`.
  * The command MUST be provably read-only (compile rejects it otherwise — use
@@ -105,6 +106,11 @@ function unknownProviders(needs, registeredNames = []) {
     for (const n of needs) {
         if (isInline(n))
             continue;
+        // A `state()` key is self-defining: it resolves to "never recorded" until
+        // some hook records it, which is a legitimate steady state (the very first
+        // run of every throttled hook), not a dangling reference.
+        if ((0, hook_state_js_1.isStateNeed)(n))
+            continue;
         if (isRef(n)) {
             if (!registered.has(n.name))
                 out.push(n.name);
@@ -141,7 +147,13 @@ function unsafeProvider(def) {
 function gatherContext(needs, io, registry = {}) {
     const ctx = {};
     for (const need of needs) {
-        if (isInline(need))
+        if ((0, hook_state_js_1.isStateNeed)(need)) {
+            // The one need that reaches no subprocess: the trusted runtime hands the
+            // stored entry (or null) straight in, and the fact view does the clamping
+            // every shell stamp-reader used to re-implement by hand.
+            ctx[need.name] = (0, hook_state_js_1.stateFact)(io.readState(need.name), io.now);
+        }
+        else if (isInline(need))
             ctx[need.name] = tryExec(io, need.run);
         else if (isRef(need)) {
             const def = registry[need.name];