vigiles 15.0.2 → 15.0.3

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

@@ -97,6 +97,14 @@ export interface CommandView {
      * line happens to be side-effecting for an unrelated reason (`grep -c x
      * notes/S.md 2>/dev/null`) matches both and gets blocked. To gate WRITES to a
      * directory, use {@link writesTo}; conflating the two is the trap.
+     *
+     * OVER-INCLUSIVE ON PURPOSE, AND THE OPPOSITE WAY ROUND FROM {@link
+     * PathView.under}. This is a DENYLIST primitive — every caller spells
+     * `touches(secret) ? deny() : allow()` — so a miss is an ALLOW, not silence. An
+     * unprovable answer is therefore reported as a MATCH: a token that could name
+     * something under the prefix under some root or some `cd` matches, and the gate
+     * blocks. See {@link prefixVerdict} for the three answers and {@link
+     * matchesPrefix} for the two biases.
      */
     touches(prefixes: readonly string[]): boolean;
     /**
@@ -130,7 +138,36 @@ export interface CommandView {
      */
     pipesToShell(): boolean;
 }
-export declare function commandView(raw: string): CommandView;
+/**
+ * Trailing separators removed — EXCEPT the one that is the path itself.
+ *
+ * 🔴 THE CARVE-OUT IS THE RULE, NOT AN EDGE CASE, and skipping it fails
+ * SILENTLY. Strip every trailing separator and the POSIX root `"/"` becomes
+ * `""`, the Windows drive root `"C:/"` becomes `"C:"` — and `isAbsoluteRef`
+ * reads a bare drive letter as RELATIVE. Nothing throws: an allowlist prefix of
+ * `"C:/"` simply stops matching, so a confinement gate denies every path and a
+ * react hook goes quiet, both looking like a correct decision.
+ *
+ * This lives here, in one place, because the same normalisation is applied to
+ * two different things — the PREFIX being matched against, and the project ROOT
+ * a path is resolved against (`run-hook.ts` imports it for the latter). Round 28
+ * fixed the root and left the prefix; round 29 found the prefix. Two copies of a
+ * rule is how the second one survives the fix to the first.
+ */
+export declare function trimTrailingSeparators(path: string): string;
+/**
+ * An AST-backed view of a Bash command.
+ *
+ * @param raw - the command line as the tool event carried it.
+ * @param root - the project root repo-relative prefixes resolve against, from
+ *   the runtime ({@link projectRootOf}: `$CLAUDE_PROJECT_DIR`, else the event's
+ *   own `cwd`, never `process.cwd()`). Omitting it does NOT disarm the denylist
+ *   matchers — without a root an absolute token is `"undecidable"` rather than
+ *   placeable, and {@link CommandView.touches} treats that as a match. It does
+ *   cost precision: with a root, `/somewhere-else/notes/x` is provably not this
+ *   repo's `notes`; without one it can only be over-blocked.
+ */
+export declare function commandView(raw: string, root?: string): CommandView;
 /**
  * The typed event a Bash gate decides over. Generic over the declared context
  * `needs` (`N`) so `e.ctx` exposes ONLY the facts the hook declared — reading an
@@ -160,13 +197,24 @@ export declare const tool: (name: string) => {
     tool: string;
 };
 export declare function defineHook<const N extends readonly NeedSpec[] = readonly []>(p: HookProgram<N>): HookProgram<N>;
-/** Build the typed event from a raw PreToolUse event, then decide. */
+/**
+ * Build the typed event from a raw PreToolUse event, then decide.
+ *
+ * `root` is the project root repo-relative prefixes in the hook resolve against,
+ * threaded exactly as {@link decideFileGate} threads it: omitted, it falls back
+ * to the event's OWN `cwd` (a payload field, so this stays pure and reads no
+ * environment); the CLI passes {@link projectRootOf}, which prefers
+ * `$CLAUDE_PROJECT_DIR`. Until 2026-08-12 no root reached here at all, and the
+ * denylist matchers on {@link CommandView} were bypassable by spelling a path
+ * absolutely — see the block above {@link PrefixVerdict} for the measurement.
+ */
 export declare function decideProgram<N extends readonly NeedSpec[]>(program: HookProgram<N>, rawEvent: {
     tool_name?: string;
     tool_input?: {
         command?: unknown;
     };
-}, ctx?: Record<string, string | boolean>): Decision;
+    cwd?: unknown;
+}, ctx?: Record<string, string | boolean>, root?: string | undefined): Decision;
 /** Map a Decision to the CC hook exit code — the protocol the author never writes. */
 export declare function decisionExitCode(d: Decision): number;
 /**
@@ -270,10 +318,105 @@ export declare function verifyHookStamp(source: string, stamp: SHA256Hash): bool
 /** An AST-free view of a file path — the matching primitive for file tools. */
 export interface PathView {
     readonly raw: string;
-    /** True iff the path sits under at least one allowed prefix (e.g. "src/**"). */
+    /**
+     * True iff the path sits under at least one allowed prefix (e.g. "src/**").
+     *
+     * A prefix is matched in ITS OWN spelling: a repo-relative prefix (`"src"`,
+     * `"migratsiya/papers/"`) is compared against the path made repo-relative, an
+     * absolute prefix (`"/etc"`) against the path made absolute. Which of those is
+     * available depends on the project root — see {@link pathView}.
+     */
     under(prefixes: readonly string[]): boolean;
+    /**
+     * The path as a repo-relative reference, or `undefined` when this view cannot
+     * produce one — an absolute path with no known root, or a path that resolves
+     * OUTSIDE the root (`/etc/passwd`, a sibling checkout). Exposed because a hook
+     * that wants to report or re-match the path needs the same answer `under`
+     * used, and `raw` alone does not carry it.
+     */
+    readonly rel: string | undefined;
 }
-export declare function pathView(raw: string): PathView;
+/**
+ * A view of a file path, matched against prefixes by {@link PathView.under}.
+ *
+ * 🔴 `root` IS NOT OPTIONAL IN PRACTICE — WITHOUT IT THIS IS DEAD FOR EVERY REAL
+ * EVENT. Claude Code's Edit/Write/MultiEdit tools always send an ABSOLUTE
+ * `file_path`, and every hook in the wild writes repo-relative prefixes
+ * (`under(["migratsiya/papers/"])`). Before the root existed, the two could
+ * never meet: the comparison ran `"/home/u/repo/migratsiya/papers/x.tex"`
+ * against `"migratsiya/papers"` and returned `false` for all input, forever.
+ * MEASURED 2026-08-12 on the live runtime with one compiled react hook and two
+ * spellings of the same file — the relative one printed its checklist, the
+ * absolute one exited 0 in silence. Three shipped hooks in a consumer repo were
+ * dead by it, all three compiled *specifically to replace hooks that were dead*,
+ * and none of the tests noticed because the harness helper built relative paths.
+ *
+ * ## Which way a miss errs, and why it is not the same answer as `touches`
+ *
+ * `under` is the ALLOWLIST/COVERAGE primitive: its callers spell
+ * `under(P) ? allow() : deny()` (confinement) and `under(P) ? notice() : nothing()`
+ * (a nudge). For both, an unprovable answer must be `false` — a confinement gate
+ * denies (fails closed) and a nudge stays quiet. So:
+ *
+ * - path resolves OUTSIDE the root → `false` for every relative prefix. Not a
+ *   bias, the truth: a repo-relative prefix names nothing in another checkout.
+ *   This is the {@link resolveRef} lesson — the suffix match it replaced handed
+ *   `/home/other-project/package.json` a grant meant for this repo's.
+ * - NO root known and the path is absolute → `false` for every relative prefix.
+ *   Here we genuinely cannot tell, and `false` is the choice: silence, never a
+ *   false grant. It is also the pre-fix behaviour, so nothing regresses.
+ *
+ * ⚠️ THE ASYMMETRY INVERTS FOR A DENYLIST, AND `under` DOES NOT SERVE THAT CASE.
+ * A gate written `under(["secrets"]) ? deny() : allow()` reads an unprovable
+ * `false` as ALLOW — a false grant. The Bash-side counterpart {@link
+ * CommandView.touches} exists precisely for that direction and takes the
+ * opposite bias from the SAME rule ({@link prefixVerdict}), which is why the
+ * resolver {@link matchesPrefix} makes each caller name its own. `PathView` has
+ * no such counterpart; a file-side denylist inherits the allowlist bias.
+ * Reported, not papered over.
+ *
+ * @param raw - the `file_path` the tool event carried, any spelling.
+ * @param root - the project root relative prefixes resolve against. Comes from
+ *   the runtime (`$CLAUDE_PROJECT_DIR`, else the event's own `cwd`), never from
+ *   `process.cwd()` — under a git worktree the process's cwd is a DIFFERENT
+ *   checkout from the one the harness resolved the hook out of, and that exact
+ *   mismatch already wedged a repo once.
+ */
+export declare function pathView(raw: string, root?: string): PathView;
+/**
+ * The project root a compiled hook's repo-relative prefixes resolve against.
+ *
+ * Two sources, in order, and `process.cwd()` is deliberately NOT one of them:
+ *
+ * 1. **`$CLAUDE_PROJECT_DIR`** — what the harness itself resolved the hook's own
+ *    path against (`.claude/settings.json` spells the command
+ *    `"$CLAUDE_PROJECT_DIR/.claude/hooks/x.hook.ts"`), so it is the same root the
+ *    hook was loaded from by construction.
+ * 2. **the event's `cwd`** — Claude Code puts the session's working directory in
+ *    every hook payload. A fallback, not a peer: it is where the session is, and
+ *    the two coincide in the ordinary case.
+ *
+ * `process.cwd()` is excluded because under a git worktree it can be a different
+ * checkout than the one the harness is driving, and a root from the wrong
+ * checkout turns every repo-relative prefix into a non-match — the same silent
+ * death this whole function exists to end. When NEITHER source is present the
+ * answer is `undefined` and the miss errs toward silence (see {@link pathView}).
+ */
+export declare function projectRootOf(event: {
+    readonly cwd?: unknown;
+}, env?: Readonly<Record<string, string | undefined>>): string | undefined;
+/**
+ * The one case {@link pathView} cannot answer and must not answer silently: an
+ * ABSOLUTE `file_path` with no project root in sight. Every repo-relative prefix
+ * in the hook returns `false`, so a gate waves everything through and a nudge
+ * never fires — indistinguishable, from the outside, from a hook with nothing to
+ * say. Returns the warning line, or `undefined` when there is nothing wrong.
+ *
+ * Narrow on purpose: a RELATIVE `file_path` is decidable without a root, so it
+ * warns about nothing. That matters because a react hook's `notice` also goes to
+ * stderr, and a warning on every event would read as the hook firing.
+ */
+export declare function undecidablePathWarning(filePath: unknown, root: string | undefined): string | undefined;
 /** The event a file-tool gate decides over (Edit/Write/Read carry `file_path`). */
 export interface FileToolEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly event: string;
@@ -298,13 +441,22 @@ export declare const tools: (...names: string[]) => {
     tools: string[];
 };
 export declare function defineFileGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<FileGateHook<N>, "role">): FileGateHook<N>;
-/** Run a file-tool gate against a raw PreToolUse event (reads `file_path`). */
+/**
+ * Run a file-tool gate against a raw PreToolUse event (reads `file_path`).
+ *
+ * `root` is the project root repo-relative prefixes resolve against; omitted, it
+ * falls back to the event's OWN `cwd` (a payload field — this stays pure and
+ * reads no environment). The CLI passes {@link projectRootOf} instead, which
+ * prefers `$CLAUDE_PROJECT_DIR`. Without either, an absolute `file_path` matches
+ * no relative prefix — see {@link pathView} for why that direction was chosen.
+ */
 export declare function decideFileGate<N extends readonly NeedSpec[]>(hook: FileGateHook<N>, raw: {
     tool_name?: string;
     tool_input?: {
         file_path?: unknown;
     };
-}, ctx?: Record<string, string | boolean>): Decision;
+    cwd?: unknown;
+}, ctx?: Record<string, string | boolean>, root?: string | undefined): Decision;
 /** The event a UserPromptSubmit gate decides over — it sees the prompt TEXT. */
 export interface PromptEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly event: string;
@@ -443,14 +595,20 @@ export interface ReactHook {
     readonly react: (e: ReactEvent) => Reaction;
 }
 export declare const defineReact: (p: Omit<ReactHook, "role">) => ReactHook;
-/** Run a react hook against a raw PostToolUse event → the (classified) Reaction. */
+/**
+ * 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.
+ */
 export declare function runReact(hook: ReactHook, raw: {
     tool_name?: string;
     tool_input?: {
         file_path?: unknown;
     };
     tool_response?: unknown;
-}): Reaction;
+    cwd?: unknown;
+}, root?: string | undefined): Reaction;
 /** The raw event fields the decode functions read (the union across roles). */
 export interface RawHookEvent {
     readonly tool_name?: string;
@@ -466,6 +624,12 @@ export interface RawHookEvent {
     readonly prompt?: string;
     /** Stop / SubagentStop (stop-gate) — the prior-block loop guard. */
     readonly stop_hook_active?: boolean;
+    /**
+     * The session's working directory, which Claude Code puts in EVERY hook
+     * payload. The fallback project root repo-relative path prefixes resolve
+     * against when the runtime does not pass one — see {@link projectRootOf}.
+     */
+    readonly cwd?: string;
 }
 /** The normalized outcome of running a hook program — discriminated by role. */
 export type HookProgramOutcome = {
@@ -478,26 +642,161 @@ export type HookProgramOutcome = {
     readonly kind: "reaction";
     readonly reaction: Reaction;
 };
+/** Record where a hook program was loaded from. Called by `loadHook` ONLY. */
+export declare function rememberHookSource(hook: AnyHook, file: string): void;
+/** The file a hook was loaded from, or `undefined` for one built in-process. */
+export declare function hookSource(hook: AnyHook): string | undefined;
 /**
  * Evaluate a compiled hook against a raw event, in-process, dispatching by role:
  * a gate → its `Decision`, an inject → the injected context text, a react → its
  * (effect-classified) `Reaction`. Pure — no subprocess, no model. The ergonomic
  * base for testing a compiled hook (see `assertHookDenies` / `assertHookAllows`).
  */
-export declare function runHookProgram(hook: AnyHook, event: RawHookEvent, ctx?: Record<string, string | boolean>): HookProgramOutcome;
+export declare function runHookProgram(hook: AnyHook, event: RawHookEvent, ctx?: Record<string, string | boolean>, root?: string | undefined): HookProgramOutcome;
+/**
+ * The repository a wedged hook belongs to, as the runtime sees it. Supplied by
+ * the caller because core takes no `node:path` and reads no disk — and because
+ * the hook's own path does NOT determine it (see {@link isLoadPathRepairEvent}).
+ */
+export interface HookRepoPaths {
+    /**
+     * Absolute root that relative references resolve against. Must be the SAME
+     * root the runtime reads the hook and its stamp with, or the write accepted
+     * here is not the file the runtime reads.
+     */
+    readonly root: string;
+    /**
+     * The actual files whose breakage can wedge THIS hook's module resolution,
+     * already resolved by the caller: the `package.json` at every ancestor of the
+     * hook, plus the repo's `.vigilesrc.json`. Node walks that chain, so a
+     * monorepo package's own `package.json` is on it and a sibling checkout's is
+     * not.
+     */
+    readonly loadPathFiles: readonly string[];
+}
 /**
- * True when this event IS the author repairing the hook — the only thing a
- * stale-stamp refusal must let through, or the repo wedges (see the note above):
+ * True when this event IS the author repairing the hook — a FILE WRITE, and only
+ * a file write.
+ *
+ * 🔴 THIS USED TO ADMIT A BASH COMMAND, AND THAT WAS THE WHOLE PROBLEM. The
+ * escape accepted `vigiles compile …`, and recognising a trusted ACTION from an
+ * untrusted STRING produced five findings in a row, each fix correct and each
+ * followed by another: `.some()` over the leaves → the operand (`compile
+ * /tmp/payload.spec.ts`, which `loadSpec` imports) → the executable path
+ * (`/tmp/vigiles compile`) → the working directory (`cd /tmp/evil && vigiles
+ * compile`). The degrees of freedom in a command string are unbounded — argv,
+ * cwd, PATH, `node_modules` resolution, a hostile `.vigilesrc.json`, a shell
+ * function — so no amount of parsing closes the class. Two more constraints
+ * predict two more findings.
+ *
+ * ## Why the command was not needed at all — measured, not argued
+ *
+ * MEASURED 2026-08-12 against the real runtime, on a stale-stamp fixture:
+ * writing `{}` into the stamp sidecar (or deleting it) makes
+ * `verifyStampOrRefuse` return early, so the hook LOADS AND ENFORCES again —
+ * `ls` passed and `git push --force` was still denied with the hook's own reason.
+ * The repo is unwedged by a file write, and the gate is back on duty; the author
+ * then runs `vigiles compile` through the NORMAL gate, needing no escape at all.
+ *
+ * MEASURED the same day on the load-wedge fixture: with `package.json` holding
+ * conflict markers, `vigiles compile <hook>` exits 1 —
+ * `Cannot load hook …: Invalid package config` — because compile has to load the
+ * hook through the same broken resolver the runtime just failed on. The command
+ * the escape existed to permit CANNOT repair that wedge. It was pure liability.
+ *
+ * So the Bash escape kept only a git whitelist — and a later round measured that
+ * those run `.git/hooks/*` too and deleted them as well. NO command is an escape
+ * now; the repair is what it always should have been: a write
+ * ({@link isLoadPathRepairEvent}).
+ *
+ * ## What is accepted here
+ *
+ * A write whose target is the hook's own source, or its stamp sidecar
+ * (`.vigiles/hooks/<basename>.json`). Both are repo-owned paths derived from the
+ * file the runtime was invoked with, never from the event.
+ *
+ * 🔴 SCOPE IS NOT THE SAME QUESTION AS EXECUTION. A previous round defended a
+ * suffix comparison here on the ground that a write executes nothing — true, and
+ * beside the point: `/home/another-project/.claude/hooks/guard.hook.mjs` ends
+ * the same way as this repo's hook, so a wedge in one checkout granted a write
+ * into another. Both sides now resolve against `repoRoot` and compare whole
+ * ({@link resolveRef}); the absolute-vs-relative tolerance that suffix matching
+ * was reached for is what resolution gives you properly.
+ *
+ * This grants nothing new: a Bash gate never gated file tools in the first place
+ * (the 2026-08-10 incident was fixed by hand-editing JSON while every Bash
+ * command was refused), and a file gate already let the hook's own source be
+ * rewritten, which is strictly more powerful than clearing its stamp.
+ */
+export declare function isStampRepairEvent(event: RawHookEvent, hookFile: string, repoRoot: string): boolean;
+/**
+ * True when this event is a load-path REPAIR — a file write, and only a file
+ * write, to one of the files whose breakage takes the runtime down.
+ *
+ * 🔴 THE GIT ESCAPE USED TO LIVE HERE AND IT EXECUTED REPO CODE. `git merge
+ * --abort` · `git rebase --abort` · `git checkout -- <path>` were admitted on the
+ * reasoning that they "only move the tree to states git already holds; none
+ * executes a line of repo code". MEASURED against git 2.43.0 with hooks installed
+ * in `.git/hooks/`, and the reasoning is false for ALL THREE:
+ *
+ *   git checkout -- f.txt   → post-checkout          (args `<sha> <sha> 0`)
+ *   git merge --abort       → reference-transaction  (prepared, committed)
+ *   git rebase --abort      → reference-transaction  (×4) + post-checkout
+ *
+ * `reference-transaction` fires on ANY ref update, and every one of these updates
+ * a ref. `.git/hooks/*` is writable by exactly the actor this door assumes —
+ * whoever could wedge the repo in the first place — so the whitelist was an
+ * arbitrary-execution path standing open precisely while the gate enforced
+ * nothing. Same shape as the `vigiles compile` escape one layer down: a command
+ * believed inert because of what it MEANS rather than what it DOES.
+ *
+ * ## Why the replacement is a write, not a safer command
+ *
+ * `git -c core.hooksPath=/nonexistent …` does suppress all three (measured: no
+ * hook ran for any of them). It was rejected anyway. It puts free-form structure
+ * back into the accepted string — the exact thing five findings on the compile
+ * door came from — and it buys nothing, because MEASURED on the load-wedge
+ * fixture a plain file write already restores the gate to ENFORCING:
+ *
+ *   wedged     : `ls` refused
+ *   after Edit : `ls` allowed, `git push --force` DENIED by the hook's own reason
+ *
+ * You do not need to finish recovering, only to stop being wedged. Once the hook
+ * loads, the gate decides normally and `git merge --abort` is an ordinary allowed
+ * command — through the gate, not around it.
+ *
+ * ## What is accepted
+ *
+ * A write to the hook's own source, its stamp sidecar, or one of
+ * {@link HARNESS_CONFIG_FILES}. That set is COMPLETE for a compiled hook rather
+ * than a guess: `checkHookImports` rejects every import but `vigiles/hook`, so the
+ * load path is the hook file plus the config that resolves that specifier —
+ * nothing else can break it.
+ *
+ * A file write executes nothing, which is the property no command on this door
+ * ever had.
+ *
+ * ## …IN THIS REPOSITORY, which is a separate question
  *
- * - a Bash command that invokes `vigiles compile` (however it's launched —
- *   `npx vigiles compile`, `pnpm exec vigiles compile`, `./node_modules/.bin/vigiles compile`),
- *   which is what regenerates the stamp; or
- * - an edit/write whose target IS this hook's own source file, so a FILE gate
- *   over the repo can still be fixed by editing the hook again.
+ * "A write executes nothing" answers the EXECUTION objection and says nothing
+ * about SCOPE. Under the suffix comparison this used to do, a write to
+ * `/home/another-project/package.json` was accepted while THIS repo was wedged —
+ * a file that cannot repair the failure, in a checkout the wedged session has no
+ * business touching. Every candidate is now resolved against
+ * {@link HookRepoPaths.root} and compared whole against the paths the runtime
+ * itself derived ({@link HookRepoPaths.loadPathFiles}, plus this root's
+ * {@link HARNESS_CONFIG_FILES} so the floor case can never be argued away).
  *
- * AST-backed (`leafCommandsNormalized`), so it sees the invocation through a
- * compound command or a wrapper, exactly like every other matcher here.
+ * ⚠️ THE HOOK'S OWN PATH DOES NOT GIVE THE ROOT, so the caller passes it. A hook
+ * lives at `.claude/hooks/…`, `.vigiles/hooks/…`, a plugin subdirectory or the
+ * repo root itself; there is no fixed depth to walk up, and finding a `.git`
+ * marker would mean reading disk, which core does not do. Nor would a
+ * git-derived root be RIGHT: `verifyStampOrRefuse` reads the hook and its stamp
+ * sidecar via `process.cwd()`, so any other root would accept writes to files
+ * the runtime does not read — repairs that do not repair. The root is therefore
+ * the one the rest of the runtime already uses, and it is passed in rather than
+ * invented here.
  */
-export declare function isStampRepairEvent(event: RawHookEvent, hookFile: string): boolean;
+export declare function isLoadPathRepairEvent(event: RawHookEvent, hookFile: string, repo: HookRepoPaths): boolean;
 export {};
 //# sourceMappingURL=hook-program.d.ts.map