vigiles 14.13.0 → 14.13.2

package/dist/cli.js

@@ -4876,12 +4876,32 @@ function emitGate(decision, on, mode, file) {
             return; // emit nothing, exit 0
     }
 }
+/**
+ * Print the loud stderr banner that accompanies a REPAIR-only pass-through, and
+ * return true — the caller allows exactly this one tool call. Shared by the two
+ * refusal paths (stale stamp, unloadable program) so the wording can't drift.
+ */
+function announceRepairEscape(file, why) {
+    console.error(`vigiles: hook ${file} ${why}.\n` +
+        `vigiles: ALLOWING this one call because it is the repair action ` +
+        `(\`vigiles compile ${file}\`, or an edit to the hook itself) — without ` +
+        `this the gate blocks the only command that can fix it.\n` +
+        `vigiles: every OTHER tool call stays BLOCKED until the hook is recompiled.`);
+    return true;
+}
 /**
  * Fail closed if a stamp sidecar exists and the on-disk source no longer
  * matches it — a hand-edit that smuggles in a capability breaks the stamp.
  * No sidecar → run uncompiled (e.g. a test fixture or a not-yet-compiled hook).
+ *
+ * ONE exception, and it is loud: the author's own REPAIR action
+ * ({@link isStampRepairEvent}) is let through, or a repo WEDGES. A stale stamp on
+ * a PreToolUse Bash gate blocks every Bash command — including `vigiles compile`,
+ * the only command that regenerates the stamp — so a normal edit-compile cycle
+ * could paint you into a corner whose only escape was hand-editing
+ * `.claude/settings.json` to unwire the gate. Observed 2026-08-03.
  */
-function verifyStampOrRefuse(file) {
+function verifyStampOrRefuse(file, event) {
     const stampPath = hookStampPath(file);
     if (!(0, node_fs_1.existsSync)(stampPath))
         return;
@@ -4889,7 +4909,12 @@ function verifyStampOrRefuse(file) {
         const { stamp } = JSON.parse((0, node_fs_1.readFileSync)(stampPath, "utf-8"));
         const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), file), "utf-8");
         if (stamp && !(0, hook_program_js_1.verifyHookStamp)(source, stamp)) {
-            console.error(`vigiles: hook ${file} does not match its compiled stamp (tampered).`);
+            if ((0, hook_program_js_1.isStampRepairEvent)(event, file)) {
+                announceRepairEscape(file, "does not match its compiled stamp");
+                return;
+            }
+            console.error(`vigiles: hook ${file} does not match its compiled stamp (tampered). ` +
+                `If YOU edited it, run \`vigiles compile ${file}\` to regenerate the stamp.`);
             process.exit(2);
         }
     }
@@ -4902,7 +4927,10 @@ function verifyStampOrRefuse(file) {
  * points at. Reads the live event on stdin, loads the typed program, verifies
  * its stamp, and dispatches by role: a gate exits 2 + reason on `deny`; an
  * inject prints `additionalContext`; a react runs its effect-classified
- * command. A hook that won't load fails CLOSED (exit 2), never silent-allow.
+ * command. A hook that won't load — or whose stamp is stale — fails CLOSED
+ * (exit 2), never silent-allow, with ONE loudly-announced exception: the repair
+ * action itself ({@link isStampRepairEvent}), or the repo wedges with no way to
+ * recompile.
  */
 async function runHookProgramCommand(file) {
     if (!file) {
@@ -4929,11 +4957,20 @@ async function runHookProgramCommand(file) {
         program = await loadHookProgram(file);
     }
     catch {
+        // Same bootstrap escape as the stale stamp below: an edit that leaves the
+        // hook unloadable (a typo mid-edit) otherwise blocks the recompile that
+        // would fix it. A hook that can't load enforces nothing either way, so
+        // refusing the repair only wedges the repo. Everything else still fails
+        // CLOSED (exit 2), never silent-allow.
+        if ((0, hook_program_js_1.isStampRepairEvent)(event, file)) {
+            announceRepairEscape(file, "cannot be loaded");
+            return;
+        }
         console.error(`vigiles: cannot load hook program ${file}`);
         process.exit(2);
         return;
     }
-    verifyStampOrRefuse(file);
+    verifyStampOrRefuse(file, event);
     switch ((0, hook_program_js_1.dispatchKind)(program)) {
         case "inject": {
             const out = (0, hook_program_js_1.runInject)(program, { source: event.source });

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

@@ -485,5 +485,19 @@ export type HookProgramOutcome = {
  * base for testing a compiled hook (see `assertHookDenies` / `assertHookAllows`).
  */
 export declare function runHookProgram(hook: AnyHook, event: RawHookEvent, ctx?: Record<string, string | boolean>): HookProgramOutcome;
+/**
+ * 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):
+ *
+ * - 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.
+ *
+ * AST-backed (`leafCommandsNormalized`), so it sees the invocation through a
+ * compound command or a wrapper, exactly like every other matcher here.
+ */
+export declare function isStampRepairEvent(event: RawHookEvent, hookFile: string): boolean;
 export {};
 //# sourceMappingURL=hook-program.d.ts.map

package/dist/core/hook-program.js

@@ -25,6 +25,7 @@ exports.runInject = runInject;
 exports.responseView = responseView;
 exports.runReact = runReact;
 exports.runHookProgram = runHookProgram;
+exports.isStampRepairEvent = isStampRepairEvent;
 /**
  * Compiled hooks — a hook as a CONSTRAINED TYPED PROGRAM, not arbitrary shell.
  *
@@ -543,4 +544,59 @@ function runHookProgram(hook, event, ctx = {}) {
             return (0, hash_js_1.assertNever)(kind);
     }
 }
+// ---------------------------------------------------------------------------
+// Stale-stamp REPAIR detection — the bootstrap deadlock's escape hatch.
+//
+// `verifyStampOrRefuse` makes a compiled hook refuse to run once its source no
+// longer matches its stamp. That is correct for tampering, but it wedges the
+// AUTHOR: if the hook is a PreToolUse Bash gate wired into the same repo, editing
+// its source makes it block EVERY Bash command — including `vigiles compile`,
+// the only command that regenerates the stamp. Observed 2026-08-03; the only
+// escape was hand-editing `.claude/settings.json` to unwire the gate, compile,
+// and rewire.
+//
+// Fail-closed is kept for everything else. The ONE exception is the repair
+// action itself, and it is announced loudly on stderr. This does not weaken the
+// stamp's threat model in a way that matters: while the stamp is stale the hook
+// enforces NOTHING (it refuses every call), and an attacker who can rewrite a
+// hook's source can equally rewrite `.claude/settings.json` — the escape they'd
+// otherwise use. What the stamp buys is that a smuggled capability can never run
+// SILENTLY, and that is unchanged.
+// ---------------------------------------------------------------------------
+/** Compare two path references without node:path (core stays dependency-free). */
+function samePathRef(a, b) {
+    const norm = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+    const [x, y] = [norm(a), norm(b)];
+    return x === y || x.endsWith("/" + y) || y.endsWith("/" + x);
+}
+/** The basename of a path token, for matching `npx vigiles` / `./bin/vigiles`. */
+function basenameOf(token) {
+    const parts = token.replace(/\\/g, "/").split("/");
+    return parts[parts.length - 1] ?? token;
+}
+/**
+ * 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):
+ *
+ * - 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.
+ *
+ * AST-backed (`leafCommandsNormalized`), so it sees the invocation through a
+ * compound command or a wrapper, exactly like every other matcher here.
+ */
+function isStampRepairEvent(event, hookFile) {
+    const filePath = event.tool_input?.file_path;
+    if (typeof filePath === "string" && samePathRef(filePath, hookFile))
+        return true;
+    const command = event.tool_input?.command;
+    if (typeof command !== "string")
+        return false;
+    return (0, bash_effects_js_1.leafCommandsNormalized)(command).some((leaf) => {
+        const i = leaf.argv.findIndex((a) => basenameOf(a) === "vigiles");
+        return i !== -1 && leaf.argv.slice(i + 1).includes("compile");
+    });
+}
 //# sourceMappingURL=hook-program.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "14.13.0",
+  "version": "14.13.2",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",

package/skills/debug-my-harness/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: debug-my-harness
+allowed-tools: Read, Glob, Grep
 description: Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the harness actually did. NOT for writing new rules (use strengthen) or editing the spec (use edit-spec).
 ---
 

package/skills/edit-spec/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: edit-spec
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
 description: Edit a vigiles .spec.ts to change a compiled instruction file (CLAUDE.md / AGENTS.md) — add, modify, or remove a rule, section, command, or key file. Use whenever you need to change a CLAUDE.md/AGENTS.md that carries a vigiles hash (edit the spec, never the artifact), including adding a new enforce()/check()/guidance() rule.
 argument-hint: <what to change — e.g., "add a rule about error handling" or "update the testing section">
 ---

package/skills/strengthen/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: strengthen
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
 description: Upgrade a vigiles spec's guidance() rules to enforce() — scan the guidance rules in a CLAUDE.md/AGENTS.md spec and find existing linter rules (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) that back them. Use when asked to strengthen, harden, or make vigiles rules enforceable; NOT for general linting or fixing lint errors.
 ---
 

package/skills/test-harness/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: test-harness
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash
 description: Install vigiles and test a Claude Code harness — hooks, skills, settings, CLAUDE.md — by picking the right tier (unit / deterministic / eval) and writing a test that passes. Use when the user wants to check that a hook fires or blocks, that a skill triggers, that injected context lands, or that a harness change moves what the agent does.
 ---